Packages can support having multiple versions installed simultaneously. This is
useful for libraries which may have changed interfaces between versions — for
gtk+ package can install both versions
parallel. This feature is called slotting.
Most packages have no need for slotting. These packages specify
in the ebuilds. This is purely a convention; the package manager does not treat
0 any different from other slot values.
SLOTis a mandatory variable and must not be empty.
Portage permits at most one instance of a package installation per
value. For example, say we have the following:
Then the user could have, say,
foo-2.0 installed in
parallel, but not
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.
DEPEND upon a package in a specific slot, refer to
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
EAPI=5 and higher, this situation can be handled by
using sub-slots, which are delimited from the regular slot by a
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.
libpng:0=). Therefore, it's best if you start using sub-slots in the library when the existing library interface changes.
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
structor 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
dev-util/libabigail or ABI Laboratory (available
in Gentoo as
dev-util/abi-compliance-checker if you prefer the non-web
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
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
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:
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:
Other ebuilds that install binaries which link to
can then request to be automatically rebuilt when the installed version of
foo:1 changes sub-slots — for example, when the user
Multiple libraries within a single package
A package might need to install several libraries. The canonical example
of this is
# 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.