Kit-fixups/Package Sets and Move Maps

Package sets define which catpkgs go in which kits. The package set files are located at kit-fixups/package-sets. They can either consist of a single file named (kit)-packages or a directory with the same name. In the case of a directory, all of the files inside the directory are concatenated and used as a package set.

Package Set Format

Package sets are a text-based format that consist of one catpkg entry per line. Let's look at the various types of package sets entries:

Entry type	Example	Explanation
literal	sys-apps/portage	Specify a single catpkg by exact name.
literal with move	sys-apps/oldpkg -> sys-foo/newpkg	Specify a catpkg by exact name, but copy it over as a new name.
category wildcard	sys-apps/*	Specify all packages that appear in a particular category.
category wildcard with exceptions	sys-apps/* -sys-apps/foo -sys-apps/bar	Specify all packages that appear in a particular category, with some exceptions.
regex	sys-.*/foo.*	Specify all catpkgs that match a particular regex.
dependencies in category	@depsincat@:x11-base/xorg-x11:media-fonts	In this example, anything in the media-fonts category that has dependencies upon x11-base/xorg-x11.
maintainer	@maintainer@:dev-lang:ml@gentoo.org	In this example, all dev-lang packages that have a maintainer of ml@gentoo.org.
has eclass	@has_eclass@:kde5	In this example, all catpkgs that use an eclass of kde5.eclass.
category has eclass	@cat_has_eclass@:x11-apps:xorg-2	In this example, all catpkgs in the x11-apps category that use an eclass of xorg-2.eclass.

   Important

It is possible to blacklist certain catpkgs for inclusion in particular kit by creating a "skip" list at kit-fixups/package-sets/mykitnamehere-packages-skip. This file can contain individual catpkgs, one per line, that should not be included in the package-set, even if they match any rules above. Note that you must use literal catpkgs in the skip list -- no patterns or other special matches are supported.

Inline Package Moves

   Note

The "literal with move" option is a new feature, described below.

The "literal with move" package set syntax described above is one way to tell the merge scripts to copy a catpkg from a source location but give it a new catpkg name, and they are specified directly in the package-set files.

If the old package name is found, it will be copied over as the new name. If the old name is not found, but the new name is found, the new name will be copied over as the new name. So either the old name or the new name, if found, will be copied over.

Move-Maps

You can also specify package moves by creating a file called kit-fixups/move-maps/kitname containing the same "literal with move" syntax. Global move maps can be placed in kit-fixups/move-maps/global. Also note that kit-fixups/move-maps/nokit or kit-fixups/move-maps/global is the only way to perform funtoo package moves for nokit. I recommend using the "global" method since it will still automatically work if someone else moves your package into a kit.

This move-maps functionality works similarly to package-moves that appear within a kit package-set, except that these moves do not automatically add either specified catpkg to the kit. So there must be something in the package-set that matches the old package name. After the old package is matched, additional logic looks at the move-maps and see if the match is in a move-map that tells us to copy it over as the "new" name. The old package will be copied over as the new name.

If you need to just rename a single package in a kit, it's fine to use the inline method. For more capability, move-maps/ are your friend. They're more powerful because a move-map specified with move-maps/ will also apply to any special wildcard package-set matches via @regex@, etc, whereas the inline method is limited by design. Also, the out-of-band method allows you to perform package moves on catpkgs in nokit.

   Important

Package moves give you the ability to rename catpkgs as they appear in kits. We still need to add functionality to provide this data to Portage so that it can update any package database entries for packages installed under the old name. This part is not done yet, so this is considered a testing-only feature for the time being and should only be used on local kit-fixups overlays for testing, not in our official kit-fixups repo yet.

Package Sets -- Putting It All Together

Here are some important facts about package sets:

1. Package set matches are executed in a particular order, and this order is defined by the order of kits in kit_groups in foundations.py.
2. Once a catpkg is matched during processing of a kit, that catpkg is assigned to that kit, and cannot appear in another kit.
3. If a catpkg is included in a particular branch of a kit, then that catpkg will appear in all branches of that kit, assuming it is available.
4. Each kit and branch defined in kit_groups specifies a "source" -- an entry in kit_source_defs which in turn defines a stack of repositories/overlays and associated SHA1 commits to use as sources for catpkgs.

So, here's how the package set processing would begin. If we look at kit_groups in foundations.py, we see that core-kit 1.0-prime is listed first. So we will look for catpkg matches for core-kit 1.0-prime using the kit-fixups/package-sets/core-kit-packages package set directory. We will apply these match rules against the gentoo_prime_protected kit source definition, and we will look for matches in each repository in the order listed in the kit_source_defs entry. The first match we find will be used as the source catpkg. But remember that we have specific rules in place, defined in the overlays property, that effectively gives gentoo-staging priority for most of the catpkgs.

After this is done, we will then process core-kit 1.2-prime, since 1.1-prime is deprecated and will be skipped, and then continue to core-hw-kit, and continue to work down the kit_groups list. This process will build up a set of catpkgs that will appear in each kit.