Dependencies

Automatic dependency resolution is one of the most useful features provided by emerge.

You are encouraged to sort dependencies alphabetically, with unconditional dependencies grouped together, then all conditional dependencies. There is an exception: you may sort dependencies as per upstream listings if it eases checking for changes. Some projects may have different policies — consult them if you're not sure.

Please also see the following section on Ebuild revisions for how dependencies and revisions interact.

Dependency types

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.

Dependency syntax

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.

Version specifiers

Available version specifiers are:

Specifier	Meaning
`>=app-misc/foo-1.23`	Version 1.23 or later is required.
`>app-misc/foo-1.23`	A version strictly later than 1.23 is required.
`~app-misc/foo-1.23`	Version 1.23 (or any `1.23-r*`) is required.
`=app-misc/foo-1.23`	Exactly version 1.23 is required. If at all possible, use the `~` form to simplify revision bumps.
`<=app-misc/foo-1.23`	Version 1.23 or older is required.
`<app-misc/foo-1.23`	A version strictly before 1.23 is required.

Ranged dependencies

To specify "version 2.x (not 1.x or 3.x)" of a package, it is necessary to use the asterisk postfix. This is most commonly seen in situations like:

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

Note that the equals sign is mandatory, and that there is no dot before the asterisk. Also note that when selecting all versions in a specific SLOT, SLOT dependencies should be used (see below).

Blockers

When two packages (package slots, versions) can not be installed simultaneously, blockers can be used to expose such a conflict to the package manager.

There are two kinds of blockers: weak blockers and strong blockers.

A weak blocker is defined using the following syntax:

RDEPEND="!app-misc/foo"

The package manager will try to resolve this conflict automatically. The package blocked by a weak blocker can be uninstalled after installing the package blocking it. However, it exempts the common files from file collision checks. Weak blockers are usually used to solve file collisions between packages and are meaningful only in RDEPEND.

More specifically, installation of the newer package may overwrite any colliding files that belong to the older package that is explicitly blocked. When such file collisions occur, the colliding files cease to belong to the older package, and they remain installed after the older package is eventually uninstalled. The older package is uninstalled only after any newer blocking packages have been merged on top of it.

Warning: Weak blockers that are pure DEPEND do not work correctly. While Portage seemingly queues the package for removal, it does not exempt their contents from file collision checks. Always include your weak blockers in RDEPEND!

If it is strictly necessary to resolve the blocker before the package is built (installed), a strong blocker must be used instead. In this case, temporary simultaneous installation of the conflicting packages is not allowed. Strong blockers are expressed using the following syntax:

RDEPEND="!!app-misc/foo"

Strong blockers apply accordingly to the dependency type defining them. Blockers defined in RDEPEND are enforced as long as the package is installed (but do not prevent building binary packages). Blockers defined purely in DEPEND are enforced only for building the package from source, and may not apply once the package is installed or when it is installed from a binary package.

The most common use for strong blockers is where another package simply being installed causes a build failure. Strong blockers are not to be used to prevent just file collisions.

Note: If both weak and strong blockers match a given package, the strong blocker takes precedence.

Specific versions can also be blocked:

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

Blockers can be optional based upon USE flags as per normal dependencies.

Blockers added to older ebuilds should not be expected to be retroactive. If the user already has the ebuild installed, any changes to the ebuild should not be expected to make any difference. This means that you should add the blockers to whichever ebuild is the newest (even if it means that logically it would seem backwards). For example, certain versions of Portage don't like some versions of bash, but the blocker was put into bash because that was the newer package that caused the issues.

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 )

Slot operators

In EAPI=5 and higher, you can use slot operators appended to the package name to declare whether or not your package should be rebuilt after the versions satisfying its runtime dependencies are updated to versions with a different slot or sub-slot:

:= means that any slot is acceptable. Additionally indicates that your package should be rebuilt if the version best matching the runtime dependency is updated to a version with a different slot or subslot.
:* means that any slot is acceptable. Furthermore, this slot operator explicitly declares that changes in the slot or sub-slot can be ignored.
:SLOT= means that only the 'SLOT' slot is acceptable. It otherwise behaves identically to the := operator. That is, the package must be rebuilt if the sub-slot of the dependency changes.
:SLOT means that only the 'SLOT' slot is acceptable, and that changes in the sub-slot can be ignored (like in previous EAPIs).
:SLOT/SUBSLOT means a dependency on a specific slot and sub-slot pair, which can be useful for packages installing pre-built binaries that require a library with a particular soname version corresponding to the sub-slot.

For example:

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

means that only the '1.0' slot is acceptable for media-libs/cogl and that sub-slot changes of media-libs/cogl will cause a rebuild of the dependent package. It furthermore means that every slot of net-libs/gnutls is acceptable but any slot change is causing a rebuild.

The :slot dependency syntax continues to behave like in EAPI=4 or earlier, i.e. it indicates that only the specific slot value is acceptable and that the package will not break when the currently installed version of the dependency is replaced by a version with a different sub-slot.

For example:

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

means that the package should be rebuilt when foo:2 or >=bar-0.9 are upgraded to versions with different subslots. On the other hand, changes in slot or sub-slots of baz should be ignored, and sub-slot changes of wombat:0 should be ignored.

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

Note: To ease dependency resolution for Portage, it is recommended that you sort the elements in preferred order first. See this bug for more context.

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 ) )"

Any of many versus USE

Say fnord can be built against either foo or bar. Then a USE flag is not necessary if and only if all of the following hold:

fnord is merged on a system which has foo and not bar installed. foo is then unmerged, and bar is installed. fnord must continue to work correctly.
A binary package of fnord made on a system with foo and not bar can be taken and installed on a system with bar and not foo.

Built with USE dependencies

Available specifiers are:

Specifier	Meaning
`app-misc/foo[bar]`	foo must have bar enabled.
`app-misc/foo[bar,baz]`	foo must have both bar and baz enabled.
`app-misc/foo[-bar,baz]`	foo must have bar disabled and baz enabled.

There are also shortcuts for conditional situations:

Compact form	Equivalent expanded form
`app-misc/foo[bar?]`	`bar? ( app-misc/foo[bar] ) !bar? ( app-misc/foo )`
`app-misc/foo[!bar?]`	`bar? ( app-misc/foo ) !bar? ( app-misc/foo[-bar] )`
`app-misc/foo[bar=]`	`bar? ( app-misc/foo[bar] ) !bar? ( app-misc/foo[-bar] )`
`app-misc/foo[!bar=]`	`bar? ( app-misc/foo[-bar] ) !bar? ( app-misc/foo[bar] )`

Use dependency defaults

If a dependency is introducing or removing a USE flag in a new package version, a (+) or (-) may be added to the use-dependency specification to define a default value in case the flag does not exist in the target package. The (+) indicates that the missing flag is assumed to be enabled, (-) the opposite.

For example, the following will treat all boost versions without the threads flag as having it enabled, and all gcc versions without the openmp as having it disabled:

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

Tips for checking dependencies

It is important to ensure that all the dependencies are complete for your package:

Look at installed binaries/libraries: Use a tool like scanelf -n (from app-misc/pax-utils) or objdump -p (from sys-devel/binutils) to list DT_NEEDED entries. app-portage/iwdevtools and portage's own qa-unresolved-soname-deps FEATURE can help finding these.
Look in configure.ac: Look for checks for packages in here. Things to look out for are pkg-config checks or AM_* functions that check for a specific version.
Look at included .spec files: A good indication of dependencies is to look at the included .spec files for relevant deps. However, do not trust them to be the definitive complete list of dependencies.
Look at the application/library website: Check the application website for possible dependencies that they suggest are needed.
Read the README and INSTALL for the package: They usually also contain useful information about building and installing packages.
Remember non-binary dependencies such as pkg-config, doc generation programs, etc. Such programs would usually belong in BDEPEND.: Usually the build process requires some dependencies such as intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those are clearly stated. Again, such dependencies usually belong in BDEPEND.
Testing in chroots, containers and virtual machines: A sure-way to find missing dependencies is to test your ebuild in a deprived environment. Chroots, containers, virtual machines and dev-util/ebuildtester can achieve this.

Implicit system dependency

All packages have an implicit compile-time and runtime dependency upon the entire @system set. It is therefore not necessary, nor advisable, to specify dependencies upon toolchain packages like gcc, libc and so on, except where specific versions or packages (for example, glibc over uclibc) are required. Note that this rule also needs consideration for packages like flex, zlib and libtool, which aren't in the @system set for every profile. For example, the embedded profile doesn't have zlib in @system, the libtool ABI might change and break building order and flex might get removed from the @system set in future.

However, packages which are included in the @system set, or are dependencies of @system set packages, should generally include a complete dependency list (excluding bootstrap packages). This makes emerge -e @system possible when installing from a stage 1 or stage 2 tarball.

Test dependencies

Packages often have optional dependencies that are needed only when running tests. These should be specified in DEPEND behind a USE flag. Often, the 'test' USE flag is used for this purpose.

Since testing will likely fail when test dependencies are not installed, the test phase should be disabled in this case. This may be accomplished via USE conditionals in the RESTRICT variable.

If other optional features must be enabled/disabled when testing, REQUIRED_USE may be set to express this.

# Define some USE flags
IUSE="debug test"

# Require debug support when tests are enabled
REQUIRED_USE="test? ( debug )"

# Disable test phase when test USE flag is disabled
RESTRICT="!test? ( test )"

# Running tests requires 'foo' to be installed
DEPEND="test? ( dev-util/foo )"

Circular dependencies

Circular dependencies occur if one or more of package's (possibly indirect) dependencies depend on the package itself. This creates a dependency cycle where each of the packages must technically be installed before the other. For example, if package A depends on B, B depends on C and C depends on A, then the package manager cannot install A before C, and C before A.

There are three kinds of circular dependencies:

Circular dependencies that occur if only one of the packages strictly needs to be installed before the other. For example, dev-python/certifi strictly requires dev-python/setuptools to build but the latter package requires the former for some runtime functionality. As a result, dev-python/certifi can be installed later than the other package. PDEPEND is used to express this and automatically resolve the circular dependency.
Circular dependencies that occur if the cycle applies only to some combination of USE flags on one of the packages. For example, running tests in dev-python/setuptools requires a number of packages which require dev-python/setuptools to be installed first. This kind of circular dependency can be resolved by the user by adjusting USE flags on one of the packages, e.g. by disabling tests on dev-python/setuptools, and reenabling them once the dependency is initially installed.
Circular dependencies that cannot be resolved using the regular means. For example, dev-util/cmake used to depend on dev-libs/jsoncpp, while the latter package used the former to build. Resolving this kind of dependency usually requires bundling one of the dependencies conditionally, or providing an alternate bootstrap path.

While circular dependencies should be avoided, an exception can be made for test-only dependencies. Similar to the example above with the tests of dev-python/setuptools, if a package needs itself, directly or indirectly, in order to run its tests, it is usually fine to leave it as-is. You should fix it if you can but don't go to extensive lengths for it.

Indirect dependencies

Always list each direct dependency that your package needs to build and run correctly. Do not rely on dependency chains to meet the dependency requirements. For example, a package needs dep1 and dep2, but dep1 also depends on dep2. You might consider just adding dep1 since it currently pulls dep2 too, but in the future, dep1 might drop dep2 as a dependency, or make it conditional with USE flags. This would then break building your ebuild.