Package and Slot Moves

This chapter describes the use of package and slot moves. The package update mechanism is a powerful tool, and needs to be used with caution. In particular, the following must be noted:

  1. Updates are not one-shot operations and they are not stateful. All updates can be reapplied multiple times to the same system, and all old updates are applied to fresh Gentoo installations.
  2. Once an update entry is created, the old package name (or slot) cannot be reused. Attempting to reuse it will cause updates to apply again, to the reused name. This also means that updates cannot be undone.
  3. Updates can only perform one-to-one moves. They cannot be used to merge packages. Attempting to move two or more packages into a single name may cause serious problems for users.

Moving or renaming a package

Moving or renaming a package (sometimes called a "pkgmove" or just "move") requires several operations. Firstly, verify that the ebuilds will continue to work correctly after the move. If the category changes, you must verify all ${CATEGORY} uses. If the package name changes, you must verify ${PN}, ${P}, etc. Whenever the old value is necessary, substitute the variable reference with the verbatim text, so that it won't get affected by the move. Commit the changes separately before moving the package.

Afterwards, move the package files using git mv. Add the move entry to profiles/updates/ in the following format:

move old-category/old-name new-category/new-name

Following the update entry, find all references to the old package name and update them. These include:

  • dependencies, optfeature.eclass uses, has_version and best_version uses in other ebuilds and eclasses
  • all profiles/ tree entries (e.g. profiles/package.mask)
  • restrict entries in package metadata.xml files, as well as <pkg/> tags
  • news item Display-If-Installed
  • open bug summaries
  • wiki pages

Preferably, combine all those changes into a single commit to ensure atomicity during the update.

Changing ebuild's SLOT

The process for changing the ebuild's SLOT (a "slotmove") is very similar to the previous process. Besides changing the SLOT in the ebuild file, you also need to create a new entry in profiles/updates/ in the Gentoo repository in the following format:

slotmove app-text/gtkspell 0 2

Make sure that you have fixed all the reverse dependencies and that you have updated every file in profiles/ directory that happens to contain an entry which may be affected by your change.