Working with Meta-Repo ====================== ``metatools`` contains the ``merge-kits`` command which is a distribution maintainer tool for creating and updating ``meta-repo``. It can also be used for developers for generating a local ``meta-repo`` based on the contents of ``kit-fixups`` for local testing. This script works by sourcing ebuilds from various overlays, and combining them using special algorithms to yield the kits you use. A meta-repo is also generated, which points to the specific kits generated that are designed to work together. Funtoo Linux uses ``merge-kits`` in "production mode" (with the ``--prod`` option) to update Funtoo Linux -- both ``meta-repo`` and the kits that end up on your system. But it's also possible for developers to use ``merge-kits`` locally, to test local changes by generating a local ``meta-repo``. Definitions ------------ Before diving in, it would be good to define some terms for people new to Funtoo Linux. This is worth reading even if you know these terms as I'm going to set some context for the rest of this documentation here: ``ebuild`` An ebuild is an individual build script for Gentoo or Funtoo Linux, and ends with an ``.ebuild`` extension, and has a package name and version in its filename. For example: ``bash-5.0.ebuild``. ``repo`` or ``overlay`` Ebuilds are generally always organized into a "repo" (repository) or "overlay", which are essentially the same thing. This is a special directory tree that organizes ebuilds in the following structure: ``my-repo/category/package/package-version.ebuild``. Gentoo Linux has a monolithic "Portage tree" which is organized in this way and contains around 30,000 ebuilds. In Funtoo, we try to organize this tree into logical "kits" (we'll get to that definition soon.) There are also very many third-party overlays that exist in the Gentoo ecosystem, which can be added to your system to add new packages. ``catpkg`` Short-hand for "category-package", this is a specifier to uniquely identify a package by category. Example: ``app-shells/bash``. It doesn't contain a version. ``kit`` Used by Funtoo Linux, kits are official overlays of the Funtoo Linux project, with ebuilds organized by theme. For example, Funtoo Linux has a ``gnome-kit`` which contains all the ebuilds related to GNOME. Kits have a few minor differences from standard Gentoo overlays. First, we make some effort to ensure that a ``catpkg`` only exists in a single kit. Secondly, kits do have separate named git branches, such as ``4.20-release``. ``meta-repo`` Typically living at ``/var/git/meta-repo``, "meta-repo" is Funtoo's equivalent of Gentoo's "Portage Tree" or package database. A user of Funtoo Linux will grab the latest packages by running ``ego sync``, which will update the contents of ``meta-repo`` using ``git``. ``meta-repo`` is actually a very small git repository that only contains metadata that references the kits that make up a ``release`` of Funtoo Linux, as well as what the official branch is for that release, and what commit is the most recent. ``kit-fixups`` Kit-fixups is the 'master' repository for Funtoo Linux which contains YAML definitions of the Funtoo Linux release, kits, as well as our locally-maintained forked ``catpkgs`` for all our kits. Developer First Run ------------------- A developer might use the ``merge-kits`` command to generate a local version of ``meta-repo`` for testing. When used this way, you will have a private copy of ``meta-repo`` and kits. To use it in this way, use the following command:: $ merge-kits 1.4-release This command, when run, will do a lot of things: #. It will clone the official ``kit-fixups`` repository from ``code.funtoo.org`` and put it in ``~/repo_tmp/source-trees/``. #. It will look at the YAML in ``kit-fixups/foundations.yaml`` to determine how to build the ``1.4-release`` version of Funtoo Linux. #. It will then clone (or update) any source git repositories specified in ``foundations.yaml`` and put them in ``~/repo_tmp/source-trees/``. #. A new meta-repo git repository will be created in ``~/repo_tmp/dest-trees/meta-repo``, if one doesn't exist. #. Based on definitions in ``foundations.yaml``, it will generate all kits, which will end up in ``~/repo_tmp/dest-trees/meta-repo/kits``. This will involve spawning the ``doit`` command as needed to perform any auto-generation of ebuilds. When autogen is used, the results of autogen (the actual auto-generated ebuilds) *will be committed* to the kit. Once ``merge-kits`` completes successfully, you should be able to use the meta-repo you generated by performing the following steps:: $ su # cd /var/git # mv meta-repo meta-repo.bak # ln -s /home/user/repo_tmp/dest-trees/meta-repo meta-repo # ego sync --in-place You can now run ``emerge`` commands, etc. and your locally-generated meta-repo will be used rather than the official Funtoo one. Developer Day-to-Day Use ------------------------ The steps above are a good "first step" for experiencing the wonder of ``merge-kits``, but still isn't very useful, because while you generated your own meta-repo, its contents are going to be nearly identical to what Funtoo Linux already offers. The only difference might be that some auto-generated or recently-updated packages might be newer in your version if Funtoo Linux's meta-repo hasn't been updated as recently. What is usually much more useful is to point ``merge-kits`` to your own forked ``kit-fixups`` repository, which then will generate a meta-repo with your own personal changes. To do this, create a ``~/.merge`` file with the following contents:: [sources] kit-fixups = ssh://git@code.funtoo.org:7999/~drobbins/kit-fixups.git [branches] kit-fixups = my-tweaks You will need to remove any existing ``kit-fixups`` repo from ``~/repo_tmp/source-trees`` if it was cloned from another location, but once done, and ``merge-kits 1.4-release`` is run again, this time ``meta-repo`` will contain *your* personal changes. This is a great way to test more complex changes that have the potential of blowing things up on a grand scale.