Automatic dependency resolution is one of the most useful features
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.
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).
- The system on which the build is performed. Dependencies that apply to the CBUILD system can be executed during build time.
- 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 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 specifies dependencies
applicable to CBUILD, i.e. programs that need to be executed during the build,
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
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
Items which are in
RDEPEND but not
DEPEND could in theory be merged
after the target package. Portage does not currently do this.
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.
Sometimes a particular version of a package is needed. Where this is known, it should be specified. A simple example:
This states that at least version 0.9.7d of
openssl is required.
Available version specifiers are:
||Version 1.23 or later is required.|
||A version strictly later than 1.23 is required.|
||Version 1.23 (or any
Exactly version 1.23 is required. If at all possible,
||Version 1.23 or older is required.|
||A version strictly before 1.23 is required.|
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 dependencies should be used (see below).
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:
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
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.
DEPENDdo 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
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:
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.
Specific versions can also be blocked:
Blockers can be optional based upon
USE flags as per normal
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.
To depend on a specific
: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 )
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
:=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.
:SLOTmeans that only the 'SLOT' slot is acceptable, and that changes in the sub-slot can be ignored (like in previous EAPIs).
:SLOT/SUBSLOTmeans 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.
RDEPEND="media-libs/cogl:1.0= gnutls? ( >=net-libs/gnutls-2.8:= )"
means that only the '1.0' slot is acceptable for
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.
:slot dependency syntax continues to behave like in
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.
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
>=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.
To depend upon a certain package if and 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
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
flag to their
use.mask file in the
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 ) )"
To depend on either
DEPEND="|| ( app-misc/foo app-misc/bar )"
To depend on either
bar if the
USE flag is set:
DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )"
fnord can be built against either
bar. Then a
flag is not necessary if and only if all of the following hold:
fnordis merged on a system which has
foois then unmerged, and
fnordmust continue to work correctly.
A binary package of
fnordmade on a system with
barcan be taken and installed on a system with
Available specifiers are:
||foo must have bar enabled.|
||foo must have both bar and baz enabled.|
||foo must have bar disabled and baz enabled.|
There are also shortcuts for conditional situations:
|Compact form||Equivalent expanded form|
If a dependency is introducing or removing a
USE flag in a new package
(-) 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
(-) the opposite.
For example, the following will treat all
boost versions without the
threads flag as having it enabled, and all
gcc versions without
openmp as having it disabled:
DEPEND=" >=dev-libs/boost-1.48[threads(+)] sys-devel/gcc[openmp(-)]"
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_NEEDEDentries. app-portage/iwdevtools and portage's own
qa-unresolved-soname-depsFEATURE can help finding these.
- Look in
Look for checks for packages in here. Things to look out for are pkg-config
AM_*functions that check for a specific version.
- Look at included
A good indication of dependencies is to look at the included
.specfiles 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
INSTALLfor 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
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
- 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.
All packages have an implicit compile-time and runtime dependency upon the
@system set. It is therefore not necessary, nor advisable, to
specify dependencies upon toolchain packages like
so on, except where specific versions or packages (for example,
uclibc) are required. Note that this rule also needs consideration
for packages like
libtool, which aren't in
@system set for every profile. For example, the embedded profile
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
@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
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 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/setuptoolsto build but the latter package requires the former for some runtime functionality. As a result,
dev-python/certifican be installed later than the other package.
PDEPENDis 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
dev-python/setuptoolsrequires a number of packages which require
dev-python/setuptoolsto 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.
dev-util/cmakeused 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.
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 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.