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:
|literal||Specify a single catpkg by exact name.|
|literal with move||Specify a catpkg by exact name, but copy it over as a new name.|
|category wildcard||Specify all packages that appear in a particular category.|
|category wildcard with exceptions||Specify all packages that appear in a particular category, with some exceptions.|
|regex||Specify all catpkgs that match a particular regex.|
|dependencies in category||In this example, anything in the |
|maintainer||In this example, all |
|has eclass||In this example, all catpkgs that use an eclass of |
|category has eclass||In this example, all catpkgs in the |
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
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.
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/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.
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:
- Package set matches are executed in a particular order, and this order is defined by the order of kits in
- Once a catpkg is matched during processing of a kit, that catpkg is assigned to that kit, and cannot appear in another kit.
- 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.
- Each kit and branch defined in
kit_groupsspecifies a "source" -- an entry in
kit_source_defswhich 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
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.