Project:Quality Assurance/Subslots

Subslots can be used to provide a more fine-grained slot-like exposure of package versions without the burden of slotting. Slot operators can be used to bind packages to specific slots and subslots of dependencies, and trigger rebuilds on their upgrades/downgrades.

What do subslots represent?
Subslots can be used to represent different package versions. The exact use is up to the package in question, and may differ from package to package. The package maintainers are recommended to use subslots in the most obvious way to avoid confusion. Whenever the most obvious answer is incorrect, the subslots should be described specifically.

The use of subslots (and slots) can be described in the metadata.xml file using the   element (and   elements).

Common examples of subslots:
 * for C/C++ libraries, slots usually represent ABI version of the library (and often match SOVERSION).

Notable exceptions:
 * Qt libraries are considered ABI-stable for each major release, and therefore the slot is used to represent public ABI version. Subslots are used to expose ABI changes in private ABI and normally should not be used by revdeps.
 * uses subslots to expose the ABI of the low-level libpoppler library. Most of the revdeps use high-level libraries which have reasonably stable ABI and therefore should not use slot ops.

Possible cases
When determining what kind of slot dependency to use, you should check how subslots are used in the dependency and how that maps to the package in question. For example, if the dependency uses subslots to expose ABI versions of a C library, you should determine whether your package links to that library.

There are three possible cases:


 * 1) the package requires a specific subslot or accepts a closed range of subslots -- e.g. a binary package that links to specific SOVERSION of a library which uses subslots for ABI,
 * 2) the package binds to one of subslots -- e.g. a source package that links to a library which uses subslots for ABI,
 * 3) the package does not care about subslots -- e.g. when you call an executable of a package that also provides a library.

Requiring specific subslot
To require a specific subslot, you need to specify the subslot in the slot dependency. If multiple subslots are allowed (and the package does not bind to either of them), then you can use the any-of dependency to expose that. Remember that in the latter case the package will not be rebuilt if one of the allowed subslots is replaced with the other.

Slot/subslot binding
To accept multiple subslots (slots) but bind to one of them, use the = slot operator. You can either use it as := to allow any slot (but bind to newest installed slot+subslot), or :x= to require slot x (and bind to the subslot of the installed version).

Subslot binding will cause the package to be rebuilt when the dependency is upgraded (downgraded) to a different subslot. If the rebuild fails or is not performed for some reason, it will cause the dependency graph to be inconsistent (and e.g. prevent depclean until the revdep is rebuilt).

Slot binding may cause the package to be rebuilt when the dependency is upgraded to a different slot. Alternatively, it will prevent the old slot from being uninstalled until the revdep is rebuilt.

It should be noted that when using the := slot operator, a matching dependency should be copied to DEPEND to ensure that the package in question is actually installed when building the package. Using := inside || blocks is forbidden by policy.

Non-binding slot dependencies
If the package does not need to bind to a specific subslot, it can either use the :* operator to allow any slot (i.e. package does not break when another slot is installed), or specify the required slot.

When the dependency is not slotted, the :* operator can be omitted. However, for packages that are slotted such a dependency may cause inconsistent behavior in different package managers and will trigger repoman warnings.