Funtoo Metatools Project
Metatools 1.1.0 has been released, which includes a lot of new features and improvements.
19 August 2022
Metatools (git) (pypi) is the framework used by Funtoo Linux to create meta-repo and autogenerate ebuilds. It is a foundational tool for Funtoo Linux development. It is also a living experiment exploring how we can develop and maintain ebuilds more efficiently and effectively.
The latest release of metatools is 1.3.5, released on 09 November 2023. It is a regular software release. View Release Notes.
What is an "Autogen"?
Quite simply, an "autogen" is kind of like an ebuild generator, using the metatools Python framework to dynamically generate ebuilds. A key functionality of an autogen is to allow ebuilds to be generated to reflect the current version of source code that is available from upstream.
Where can I Find Autogens?
You can find autogens by looking in the kit-fixups repository (git) for any files named:
Both YAML and Python autogens use our metatools framework -- the YAML variants are higher-level autogens that feed metatools "generators", kind of like a pipeline. As of Jan 29, 2022, all Funtoo Linux source overlays -- kit-fixups as well as others -- support the creation of autogens. What this means is that it's possible to write an autogen for anything in Funtoo to ensure that it is always kept up-to-date.
To install metatools, emerge it:
root # emerge metatools
The command in metatools that performs autogeneration locally is called
doit. Prior to using this command locally, it's recommended to create an
~/.autogen file under your user account that
contains a GitHub personal access token. This will allow
doit to use it when querying GitHub and will prevent
doit from hitting API limits:
authentication: api.github.com: username: danielrobbins password: <insert access token string here>
For more information on setting up GitHub personal access tokens, see: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
Typical Developer Usage of Doit
This section describes basic usage of metatools, using the
doit command, which you may run directly in kit-fixups locally in order to test some autogens you happen to be working on for a PR.
Funtoo's meta-repo is defined in the kit-fixups repository (git), which is the starting point for all autogeneration of ebuilds.
To perform your first
doit run, enter into the appropriate kit-fixups directory and run the
user $ cd development/kit-fixups/core-kit/curated user $ doit [INFO 21:02:35] Fetched https://git-scm.com/download/linux 6042 bytes [INFO 21:02:35] Created: dev-vcs/git/git-2.35.1.ebuild [INFO 21:02:35] Fetched https://api.github.com/repos/hashicorp/vagrant_cloud/tags 9513 bytes [INFO 21:02:36] Created: dev-ruby/vagrant_cloud/vagrant_cloud-2.0.3.ebuild [INFO 21:02:36] Fetched https://api.github.com/repos/distcc/distcc/releases 34549 bytes [INFO 21:02:36] Created: sys-devel/distcc/distcc-3.4.ebuild [INFO 21:02:36] Fetched https://api.github.com/repos/dbrgn/tealdeer/releases 151336 bytes [INFO 21:02:36] Fetched https://api.github.com/repos/tmux/tmux/releases 94211 bytes [INFO 21:02:36] Created: app-misc/tmux/tmux-3.2a.ebuild [INFO 21:02:36] Fetched https://api.github.com/repos/lotabout/skim/releases 225892 bytes [INFO 21:02:36] Fetched https://ftp.debian.org/debian/pool/main/c/ca-certificates/ 7174 bytes [INFO 21:02:36] Created: app-misc/ca-certificates/ca-certificates-20211016.ebuild [INFO 21:02:36] Fetched https://api.github.com/repos/jarun/nnn/releases 564842 bytes [INFO 21:02:36] Fetched https://api.github.com/repos/netwide-assembler/nasm/tags 13895 bytes [INFO 21:02:36] Created: app-misc/nnn/nnn-4.4.ebuild [INFO 21:02:36] Fetched https://api.github.com/repos/doxygen/doxygen/tags?per_page=100 46121 bytes
What you are seeing above is output from the
doit command, which will:
- Find all autogens (
autogen.pyfiles) in the current directory tree.
- Execute them using multiple threads, during which
- Query upstream Web sites and APIs (like GitHub) for current versions of source code,
- Fetch all source code artifacts (distfiles) by using an efficient spider engine, and
- Auto-create ebuilds for these packages, along with Manifests.
Funtoo contributors will use the
doit command locally to test their autogens and ensure their proper operation before submitting a PR. Once you use
doit to autogen a small set of ebuilds, you can add them to your local meta-repo using a couple of methods. Some developers will copy them physically to
/var/git/meta-repo. It's also convenient to temporarily add the particular directory of kit-fixups as an overlay, which works if your ebuilds have newer versions that what is currently in your tree:
If you need to debug ebuild creation with the
doit command for specific package call it with
--debug and the
--pkg <pkgname> as parameters in the appropriate kit-fixups folder. e.g to debug the creation of a firefox ebuild do
user $ cd development/kit-fixups/browser-kit/curated/www-client/firefox user $ doit --debug --pkg firefox
If you need to create some logging statements for debugging of
autogen.py you can use logger from
hub.pkgtools.model.log or fetch a logger as by
log = logging.getLogger("metatools.autogen") to print out interesting information by using of
Additionally you can enter debugger with
Generate Your Own Meta-Repo
It's also very possible to generate your very own
meta-repo using the
merge-kits command. In this workflow, you will run
merge-kits next or
merge-kits 1.4-release to generate a particular release. The auto-generated meta-repo will be created in
meta-repo can be copied or symlinked into place at
user $ merge-kits next --fixups_url=<path to your fork> --fixups_branch=mybranch
When used in this way,
~/repo_tmp/dest-trees/meta-repo and the individual kit git repositories that exist inside
~/repo_temp/dest-trees/meta-repo/kits will be auto-created git trees with no remotes defined, but they can still be used as-is.
Here's more info for the important command-line options for
- Use this option to point to where to clone your kit-fixups repository from. You can also use the official URL for Funtoo's kit-fixups, which is https://code.funtoo.org/bitbucket/scm/core/kit-fixups.git. You only need to use this option the first time you run
merge-kits, or if you wipe
- This option will be available in 1.0.4, and is in 'git master' meta-repo right now. Use this option to specify your branch, which defaults to
master. This option is 'sticky', which means
merge-kitswill continue to use the specified branch as long as
~/repo_tmp/source-trees/kit-fixupshas not been wiped and you have not specified a different branch with another
--fixups-branchcall. Therefore, you can use this option to periodically change to a different branch you happen to be testing.
Where Can I Learn More about Metatools?
The best place to learn is to join us in the #metatools and #development channels on Discord.
There is "in progress" documentation for metatools at our to-be-launched projects site: https://projects.funtoo.org/metatools/docs/install.html SSL Cert is not yet valid and the documentation is a work in progress. Refer to this wiki page for current setup documentation until the documentation has caught up with the current release of metatools.
- Metatools 1.1.0 has been released, which includes a lot of new features and improvements.
- Metatools 1.0.3 has been released, with a bunch of improvements including support for running merge-kits.
- Metatools git master now can successfully regen the tree in "dev" mode. It doesn't use mongodb, or threading like the previous incarnation, but is still faster than the older threaded version. This is an important milestone -- soon we will be using this version for production tree regens.
- Drobbins is working on "master" branch, specifically merge-kits, and getting this working fully (currently, "legacy" branch is used for tree regen). This involves upgrading release YAML, implementing support for "sourced" kits, and testing.
- drobbins is working on the "master" branch of metatools. With the 1.0.2 release, mongodb is no longer a dependency.