Slotting

Packages can support having multiple versions installed simultaneously. This is useful for libraries which may have changed interfaces between versions — for example, the gtk+ package can install both versions 2.24 and 3.6 in parallel. This feature is called slotting.

Most packages have no need for slotting. These packages specify SLOT="0" in the ebuilds. This is purely a convention; the package manager does not treat 0 any different from other slot values.

"Fake slotting" where multiple SLOTs exist for the same package but they are mutually exclusive (i.e. block each other) is strongly discouraged, given that the existence of multiple SLOTs implies to users that parallel installation is possible.

Note: SLOT is a mandatory variable and must not be empty.

Portage permits at most one instance of a package installation per SLOT value. For example, say we have the following:

foo-1.1 with SLOT="1"
foo-1.2 with SLOT="1"
foo-2.0 with SLOT="2"
foo-2.1 with SLOT="2"

Then the user could have, say, foo-1.2 and foo-2.0 installed in parallel, but not foo-1.1 and foo-1.2. Note that it is entirely possible that the user may have foo-2.0 installed and no foo-1.x at all.

To DEPEND upon a package in a specific slot, refer to SLOT dependencies.

Considerations for slotting

Slotting is a powerful tool and as such, is easily abused. It's critical that when slotting, package maintainers carefully reflect on implications for reverse dependencies.

Do not be fooled by the ease in adapting the package itself to slotting: slotting the package itself may well be the easiest part.

Before proceeding at all, consider the wider implications beyond Gentoo. Especially examine other distributions and their handling of the problem in question. Unilaterally moving software can have devastating consequences for both users and other developers.

Suppose every possible consumer of a slotted package can be adapted in Gentoo: there is still more work to be done. Keep in mind that users may develop or test software on Gentoo systems which may be deployed elsewhere. They both want to be able to build that software without having to adapt to Gentooisms, and they also don't want to unintentionally write their software such that it relies on Gentooisms.

For example, slotting software by inventing a Gentoo-specific pkgconfig file and then patching all packages in the Gentoo repository is usually the wrong decision, because users won't be able to build software manually without patching it, and they may ship software that then fails to build on other distributions.

Even systems that lend themselves to slotting, such as Guile or Lua, cannot be naively slotted by just adapting the package itself. Other packages must be primed to handle a slotted landscape: an eclass mechanism usually needs to exist for packages to declare which versions they support, as well as force building against the version currently depended upon to avoid automagic dependencies.

For example, for slotted Guile, it may be trivial to make dev-scheme/guile itself install itself as guile-3.0 (and other -3.0 suffixes on its binaries), but packages depending on Guile will need an eclass to control which Guile the installed files are compatible with.

All reverse dependencies of a package should be tested and examined when considering any slotting approach, in particular asking the following:

how does this software use the to-be-slotted package;
how the build system should locate the (right) version of this package;
how the package (and the right version of it) should be located at runtime, if required.

Libraries

As a rule of thumb, libraries should not be slotted unless upstream explicitly intend (major) versions to be installable in parallel. The presumption should be that a library cannot be slotted until proven otherwise.

If a library is to be slotted, please consult with upstream wherever possible: ask them to begin installing pkgconfig files to aid porting build systems to detecting the library portably.

ABI should also be considered with slotted libraries: if a consumer of the library (in)directly links against another version of the library, loading two ABI-incompatible versions of the library in the same process, unpredictable runtime behaviour may occur (including crashes, or worse).

Executables

For utilities / executables, slotting may be acceptable as long as an unversioned, generic symlink or wrapper is made available for the benefit of user scripts or tools, and build systems which expect the generic name to be available.

An eselect module is often made available for these cases, though ebuilds normally shouldn't depend on its use.

Sub-slots

Sometimes a package installs a library that changes interfaces between versions, but it's undesirable or inconvenient to allow some of these versions to be installed simultaneously. In EAPI=5 and higher, this situation can be handled by using sub-slots, which are delimited from the regular slot by a / character, as in SLOT="slot/subslot". Packages can request to be automatically rebuilt when the subslot of a runtime dependency changes.

If an ebuild does not explicitly declare a sub-slot, the regular slot is used as the value of the sub-slot by default.

You may wish to review the QA team's documentation on subslots.

Note: Care must be taken when using sub-slots in a library ebuild for the first time. Adding sub-slots will trigger rebuilds for all the packages that already use slot-operator dependencies (e.g. switching from SLOT="0" to SLOT="0/14" in media-libs/libpng and package foo depends on libpng:0=). Therefore, it's best if you start using sub-slots in the library when the existing library interface changes.

ABI breakage

There are two ways a library can break compatibility with its consumers.

ABI (Application Binary Interface): this affects binaries built before the change. Applications linked against a library pre-ABI break may not work correctly after the break. These changes are related to internal structure, such as the size of a struct or the type of an argument (e.g. integer width). Fixing this requires a rebuild of all consumers.

API (Application Programming Interface): this affects consumers at compile time and usually occurs when a library has deprecated and then removed a function. Fixing this requires a code change in consumers.

Note that subslots are not used exclusively for this purpose. While they form the majority of uses in the Gentoo tree, subslots may have a meaning that is completely divorced from SONAMEs or ABI breakage. Check the usage in the relevant packages before using a subslot operator!

When made aware of ABI breakage, change the subslot. Note that the subslot does not have to strictly be the SONAME and therefore could be an arbitrary string (following naming rules).

Be aware that some upstreams may make releases without verifying if binary compatibility has been broken in a minor release. You should check using tools like dev-util/libabigail or ABI Laboratory (available in Gentoo as dev-util/abi-compliance-checker if you prefer the non-web version).

Generally, consumers which link against a library possessing a subslot that represents SONAME or binary compatibility should subscribe to it (request to be rebuilt when the subslot changes) with :=. Also, see the QA Policy Guide for information on proactively subscribing to subslots before they are defined.

General naming of a sub-slot

As a simple rule of thumb, the SONAME is usually a function of the library's linking filename libfoo.so and its first version component. The remaining version components are useful for ensuring a monotonic upgrade path of consumers, but aren't incorporated into the library's SONAME, which in this case would be libfoo.so.1.

The SONAME being incremented implies that the library's ABI has been broken.

As a result of the aforementioned convention, ebuilds usually expose the current ABI version as the subslot. For this libfoo example, if the library is libfoo.so.1.2, the ebuild might set:

SLOT="0/1"

Further, suppose the package foo installs a library whose SONAME is different for different versions. It would be reasonable to use the SONAME version as the sub-slot name:

foo-1.1 installs libfoo.so.5 — SLOT="1/5"
foo-1.2 installs libfoo.so.6 — SLOT="1/6"
foo-2.0 installs libfoo-2.so.0 — SLOT="2/0"
foo-2.1 installs libfoo-2.so.1 — SLOT="2/1"

Other ebuilds that install binaries which link to libfoo-2 (or libfoo) can then request to be automatically rebuilt when the installed version of foo:2 or foo:1 changes sub-slots — for example, when the user upgrades from foo-2.0 to foo-2.1.

Multiple libraries within a single package

A package might need to install several libraries. The canonical example of this is media-video/ffmpeg:

# Subslot: <libavutil_major>.<libavcodec_major>.<libavformat_major>
# Since FFmpeg ships several libraries, subslot is kind of limited here.
# Most consumers will use those three libraries, if a "less used" library
# changes its soname, consumers will have to be rebuilt the old way
# (preserve-libs) - which should not be relied upon.
# If, for example, a package does not link to libavformat and only libavformat
# changes its ABI then this package will be rebuilt needlessly. Hence, such a
# package is free _not_ to := depend on FFmpeg but I would strongly encourage
# doing so since such a case is unlikely.
SLOT="0/56.58.58"

In such cases, make the subslot a composite of the major SONAMEs of each of the installed libraries. This emphasises a point made above — subslots do not need to be equal to the exact SONAME of installed libraries, they only need to represent in some way ABI compatibility.

Slot names

Current versions of Portage accept slot and sub-slot names that begin with an alphanumeric character or _, and contain alphanumerics and _, -, ., and + characters.