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.