diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml index e776150a..423006cb 100644 --- a/general-concepts/dependencies/text.xml +++ b/general-concepts/dependencies/text.xml @@ -850,5 +850,312 @@ USE flags. This would then break building your ebuild. + +
+Common pitfalls + + +

+The following pitfalls occur frequently when dealing with slots, slot +operators, any-of dependencies, and blockers. They are easy to miss and can lead +to subtle resolver behaviour or rebuild issues. The guidance below is a brief +summary; see the linked references for deeper background. +

+ + + + +Separate dependency specifications are not combined into one slot + + +

+Multiple independent dependency specifications are not guaranteed to be +satisfied by the same slot of a slotted package. For example, a common version +range like the following can be satisfied by two different slots: +

+ + +# Bad (if sys-libs/db is slotted): +DEPEND=">=sys-libs/db-2 + <sys-libs/db-5" + + +

+If sys-libs/db is slotted and two installed slots each satisfy one +side of the range, the resolver can legally use them separately. +

+ +

+Likewise, independent USE requirements may be met by different slots with +different USE configurations. For packages that are not truly multi-slotted +(i.e. slots represent mutually incompatible ABIs), the safe fix is to state the +intended slot explicitly or to express the intent via any-of groups limited per +slot. +

+ + +# Bad: +RDEPEND="sys-libs/db[foo] + bar? ( sys-libs/db[baz] )" + + + +DEPEND=" + || ( + =sys-libs/db-5*:5 + =sys-libs/db-4*:4 + ) +" + + + +RDEPEND=" + || ( + ( sys-libs/db:5 tools? ( sys-libs/db:5[cxx] ) ) + ( sys-libs/db:4 tools? ( sys-libs/db:4[cxx] ) ) + ) +" + + + + + + +The <c>:=</c> slot operator with multiple slots + + +

+The := operator records the slot/sub-slot of the best matching +installed version for the given + +dependency specification. If that +dependency specification can match slots newer than the versions you explicitly +allowed elsewhere, it may bind to the wrong slot (and even pull it in during +build). +

+ +

+To prevent this, ensure the dependency specification carrying := cannot +match slots newer than intended. One simple pattern is to cap it with an upper + +bound that excludes unwanted major versions while keeping := on the same +package: +

+ + +DEPEND=" + || ( + =sys-libs/db-5* + =sys-libs/db-4* + ) + <sys-libs/db-6:= +" + + +

+This forces the slot-operator binding to a version in the requested range at +build time. Be cautious when combining multiple conditional USE sets with a +slot operator; keeping the := dependency specification simple and +separately constrained is usually clearer. +

+ + + + + +Understanding any-of dependencies + + +

+An any-of group (|| ( ... )) guarantees only that at least one +immediate child element is satisfied for the relevant dependency class. It +does not guarantee which element will be chosen, nor does it bind the choice +made at build time to the choice used later at runtime. Order can be used as +an implementation hint but is not a contract. +

+ + +DEPEND=" + || ( + dev-libs/A + dev-libs/B + dev-libs/C + ) +" + + +

+If more than one alternative is installed, it is undefined which one is actually +going to be used. In fact, the package may even provide the user with explicit +run time choice of the dependency used, or use multiple of them. Replacing one +alternative with another later still satisfies the dependency and should not be +assumed to force rebuilds unless you have expressly tied the dependency via +slots/sub-slots (outside of any-of) or via other mechanisms. +

+ + + + + +Do not use <c>:=</c> inside any-of groups + + + +Do not place := dependency specifications inside || ( ... ) +groups. The semantics of the slot operator (binding to the slot/sub-slot of the +installed match) conflicts with the semantics of any-of (only one child needs to +match and may change later). As a result, the requirements cannot be satisfied +reliably and behaviour is undefined. pkgcheck will warn about this situation +with +BadDependency results. + + +

+Instead, keep the any-of block free of slot operators and add a separate, +well-constrained dependency specification carrying := if you need rebuild +tracking. +

+ + +# Bad: +RDEPEND=" + || ( + dev-libs/A:= + dev-libs/B:= + ) +" + + + +IUSE="a b" +REQUIRED_USE="^^ (a b)" +RDEPEND=" + a? ( dev-libs/A:= ) + b? ( dev-libs/B:= ) +" + + + +The above is only an illustration of structure. Choose the package for the +slot-operator binding that truly determines ABI compatibility for your +package, and constrain its version range appropriately. + + + + + + +Any-of and <c>:*</c> across classes + + +

+Any-of groups (|| ( ... )) and the :* slot operator are valid in +all dependency classes. However, there is no binding between occurrences in +different classes. An any-of in DEPEND guarantees only that at least one +alternative is installed before the build; an any-of in RDEPEND or +PDEPEND guarantees only that at least one is installed for runtime. +You should not assume the same alternative or slot will be used for both. +

+ + + + + +The <c>:=</c> slot operator across classes + + +

+The := operator is technically valid in all classes but is useful only +when the matching package is installed at the time metadata is recorded +(install from source or binary package creation). Practically, the dependency +specification using := should be present in RDEPEND to express the +rebuild relationship, and DEPEND must guarantee that a matching package +is installed at the relevant time. +

+ + +DEPEND="dev-libs/foo:=" +RDEPEND="${DEPEND}" + + + +The dependency specifications need not be textually identical as long as +DEPEND guarantees that some package matching the RDEPEND := +dependency specification is installed when metadata are recorded. + + + +# Also valid: +RDEPEND="dev-libs/foo:=" +DEPEND="dev-libs/foo" + + + + + + +Blockers across dependency classes + + +

+Blockers are valid in all classes but their usefulness differs: +

+ + + + +# Weak blocker: meaningful in RDEPEND +RDEPEND="!app-misc/foo" + +# Strong blocker: enforced pre-build or pre-install +DEPEND="!!sys-libs/bar" + + + + + + +Further reading + + +

+For extended discussion with examples, see the + +blog post and its + +follow-up, and the relevant sections of the Package Manager Specification +on + +any-of dependency specifications and + +slot dependencies. +

+ + + +