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.

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.

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.