Dependencies

CHOST vs CBUILD

In order to avoid ambiguity, we use the following terms to indicate different systems when cross-compiling. They serve as a shorthand for an overall system in addition to their literal value (e.g. $CHOST).

CBUILD

The system on which the build is performed. Dependencies that apply to the CBUILD system can be executed during build time.

CHOST

The system on which the package is going to be executed. When cross-compiling, dependencies applying to CHOST can not be executed.

When cross-compiling, CBUILD and CHOST are naturally different, as are the actual install paths for the different types of dependencies.

Note however that, while cross-compiling is used to help explain these concepts, it is not strictly required. CBUILD and CHOST could target the exact same hardware, but be installed into distinct SYSROOT/ROOT paths. The dependency distinctions still apply even if it isn't, strictly speaking, cross-compiling.

Build dependencies

Build dependencies are used to specify any dependencies that are required to unpack, patch, compile, test or install the package (but see Implicit system dependency for exemptions).

Starting with EAPI 7, build dependencies are split into two variables: BDEPEND and DEPEND. BDEPEND specifies dependencies applicable to CBUILD, i.e. programs that need to be executed during the build, e.g. virtual/pkgconfig. DEPEND specifies dependencies for CHOST, i.e. packages that need to be found on built system, e.g. libraries and headers.

In earlier EAPIs, all build dependencies are placed in DEPEND.

Runtime dependencies

The RDEPEND ebuild variable should specify any dependencies which are required at runtime. This includes libraries (when dynamically linked), any data packages and (for interpreted languages) the relevant interpreter.

Note that when installing from a binary package, only RDEPEND will be checked. It is therefore necessary to include items even if they are also listed in DEPEND.

Items which are in RDEPEND but not DEPEND could in theory be merged after the target package. Portage does not currently do this.

Post dependencies

The PDEPEND variable specifies runtime dependencies that do not strictly require being satisfied immediately. They can be merged after the package. This variable is used purely to resolve circular dependencies, while in general case RDEPEND should be used instead.

Basic dependency syntax

A basic DEPEND specification might look like the following:

DEPEND="dev-lang/ruby
	dev-ruby/ruby-gtk2
	dev-ruby/mysql-ruby"

Each package dependency specification is the full category and name of a package. Dependency specifications are separated by arbitrary whitespace — convention is to have one specification per line for readability purposes. When specifying names, the category part should be treated as mandatory.

Version dependencies

Sometimes a particular version of a package is needed. Where this is known, it should be specified. A simple example:

DEPEND=">=dev-libs/openssl-0.9.7d"

This states that at least version 0.9.7d of openssl is required.

DEPEND="gtk? ( =x11-libs/gtk+-2* )"

RDEPEND="!app-misc/foo"

RDEPEND="!!app-misc/foo"

RDEPEND="!<app-misc/foo-1.3"

SLOT dependencies

To depend on a specific SLOT, :SLOT should be appended to the package name, where 'SLOT' is the SLOT of the package wanted:

DEPEND="qt5? ( dev-qt/qtcore:5 )
	gtk? ( x11-libs/gtk+:2 )

To depend on a specific version or version-range within a SLOT we use:

DEPEND="qt5? ( ~dev-qt/qtcore-5.15.2:5 )
	gtk? ( >=x11-libs/gtk+-2.24.9:2 )

RDEPEND="media-libs/cogl:1.0=
	gnutls? ( >=net-libs/gnutls-2.8:= )"

RDEPEND="dev-libs/foo:2=
    >=dev-libs/bar-0.9:=
    media-gfx/baz:*
    x11-misc/wombat:0"

USE-conditional dependencies

To depend upon a certain package only if a given USE flag is set:

DEPEND="perl? ( dev-lang/perl )
	ruby? ( >=dev-lang/ruby-1.8 )
	python? ( dev-lang/python )"

It is also possible to depend upon a certain package if a given USE flag is not set:

RDEPEND="!crypt? ( net-misc/netkit-rsh )"

This should not be used for disabling a certain USE flag on a given architecture. In order to do this, the architecture team should add the USE flag to their use.mask file in the profiles/arch directory of the Gentoo repository.

This can be nested:

DEPEND="!build? (
	>=sys-libs/ncurses-5.2-r2
	gcj? (
		>=media-libs/libart_lgpl-2.1
		gtk? (
			x11-libs/libXt
			x11-libs/libX11
			x11-libs/libXtst
			x11-proto/xproto
			x11-proto/xextproto
			>=x11-libs/gtk+-2.2
			x11-libs/pango
		)
	)
	nls? ( sys-devel/gettext )
)"

Any of many dependencies

To depend on either foo or bar:

DEPEND="|| ( app-misc/foo app-misc/bar )"

To depend on either foo or bar if the baz USE flag is set:

DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )"

Built with USE dependencies

Available specifiers are:

There are also shortcuts for conditional situations:

DEPEND="
	>=dev-libs/boost-1.48[threads(+)]
	sys-devel/gcc[openmp(-)]"

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.

Example of a bad USE dependency on a slotted package

# Bad:
RDEPEND="sys-libs/db[foo]
	bar? ( sys-libs/db[baz] )"

Example of a good version range across slots

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

Example of a good USE dependency on a slotted package

RDEPEND="
	|| (
		( sys-libs/db:5 tools? ( sys-libs/db:5[cxx] ) )
		( sys-libs/db:4 tools? ( sys-libs/db:4[cxx] ) )
	)
"

The := 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:

Example of good use of := with version range

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.

Example of an any-of dependency

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 := inside any-of groups

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

Example of incorrect use of := inside any-of

# Bad:
RDEPEND="
	|| (
		dev-libs/A:=
		dev-libs/B:=
	)
"

Example of correct use of := outside any-of

IUSE="a b"
REQUIRED_USE="^^ ( a b )"
RDEPEND="
	a? ( dev-libs/A:= )
	b? ( dev-libs/B:= )
"

Any-of and :* 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 := 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.

Example of typical pattern: tie rebuilds to sub-slot changes

DEPEND="dev-libs/foo:="
RDEPEND="${DEPEND}"

# 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 blockers (!) are primarily meaningful in RDEPEND, where the uninstall of the blocked package may be delayed until after the new package starts installing, allowing file collisions to be replaced. Technically they are allowed in DEPEND, but they do not influence the build environment and are not useful there on their own.
• Strong blockers (!!) must be resolved before the dependency is considered satisfied. They therefore make sense in both DEPEND (before building) and RDEPEND (before installation).
• Remember the general caveat from above: weak blockers should be included in RDEPEND rather than used purely in DEPEND.

# 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.