Difference between revisions of "Funtoo:Metatools/Advanced Usage"
Revision as of 20:05, April 17, 2022
As of April 2022, this functionality is only supported in the
legacy branch of metatools, not the current released version in Portage. Note that this feature will soon be re-added to a future release of metatools. See Project:Metatools for more information.
Funtoo Linux uses "merge scripts" to create its kits and update meta-repo. These scripts work 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.
Before starting, please read and understand the following pages:
This section is somewhat out-of-date and is in the process of being updated. The current tool used for generating meta-repo is metatools, setup of which is documented here. Because metatools was based on merge-scripts, the configuration is nearly identical and besides initial setup of metatools, the following instructions should generally apply.
merge-kits can be used in a variety of ways. If you are an individual developer, you may want to use
merge-kits in developer mode, which is its default mode. Developer mode makes it easy to generate a meta-repo and kits that you can test locally.
In developer mode, a
meta-repo and all automatically-generated kit git repositories are created from scratch. These git repositories will have no remotes, so they will simply exist locally on disk, and they will not have any history shared with the Funtoo project. It you look at the commit history for the kits and meta-repo, you will see that they essentially have no history.
Another way to use
merge-kits is with
gitolite as a remote, which is documented under the Gitolite Setup sub-page. Using this configuration,
merge-kits will write all of its destination git repositories to gitolite. You can then configure other systems to
ego sync from gitolite as a source. This can be good in a distributed development environment. This method can also be used to create a meta-repo and kits that diverge from Funtoo's kit but still connect to its history.
merge-kits script can be run in a production mode, which is very similar to using it with gitolite except that you may be pushing up your destination meta-repo and kits to a public location like GitHub or GitLab.
When first starting out with
merge-kits, you should definitely start with developer mode and see if that meets your needs first.
Getting The Code
The current tool used for generating meta-repo is metatools, setup of which is documented here. Please follow these instructions, which are current, to set up metatools locally.
Configuration and Paths
In general, you should run
merge-kits as a regular user, and this user needs to be a member of the
In the user's home directory, create a
~/.merge file with the following contents:
[sources] flora = https://code.funtoo.org/bitbucket/scm/co/flora.git kit-fixups = https://code.funtoo.org/bitbucket/scm/co/flora.git gentoo-staging = https://code.funtoo.org/bitbucket/scm/auto/gentoo-staging.git [branches] flora = master kit-fixups = master meta-repo = master
merge-kits will create a
~/repo_tmp directory where it will store all of its work. Inside
~/repo_tmp/source-trees, source git trees that will be used to generate meta-repo will be cloned. Inside
~/repo_tmp/dest-trees, git repositories will be created to write results into. The meta-repo will be stored at
/~repo_temp/dest-trees/meta-repo, and in developer mode, the kits will be stored in meta-repo, at
~/repo_tmp/dest-trees/meta-repo/kits, so that meta-repo is configured 'ready to use' at it would appear at
/var/git/meta-repo. When 'production' mode is specified via the
--prod switch, the meta-repo will not have kits stacked inside it but instead the kits will be written directly into
A metadata cache will also be created and stored at
~/repo_tmp/metadata-cache, and your user must be a member of the
portage group for
merge-all-scripts to be able to properly generate the metadata cache.
merge-kits, use it as follows:
user $ merge-kits 1.4-release
The script will then run, and it will git clone flora, kit-fixups and gentoo-staging from the URIs in the
~/.merge file, and assemble them into a complete meta-repo. The meta-repo will be located at
To use the
meta-repo for testing, you can add the following lines to
[global] meta_repo_path = /home/user/repo_tmp/dest-trees/meta-repo
Then, using ego 2.8.0 or later, run the following command:
root # ego sync --in-place
This will ensure that the proper kit branches in your meta-repo are checked out and that all the repos.conf and profiles files in
/etc/portage are configured correctly for your repository to be used. Note that no actual "
git pull" will be performed -- this is intentional and a special feature of the
--in-place option -- because your local git repositories have no remotes to pull from and contain all the information they need to be used.
You're now ready to use your meta-repo directly:
root # emerge foo