Dependencies
Automatic dependency resolution is one of the most useful features
provided by emerge
.
CHOST vs CBUILD
In order to avoid ambiguity, we use the following terms to indicate different systems when cross-compiling:
- CBUILD
- The system on which the build is performed. Dependencies that apply to the CBUILD system can be executed during build time. When cross-compiling, they are not installed into the system being built.
- CHOST
- The system on which the package is going to be executed. When cross-compiling, dependencies applying to CHOST can not be executed.
When not cross-compiling, CBUILD and CHOST have the same value and both classes of dependencies are merged.
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.
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.
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.
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.
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="qt3? ( x11-libs/qt:3 )
gtk? ( x11-libs/gtk+:2 )
To depend on a specific version or version-range within a SLOT we use:
DEPEND="qt3? ( ~x11-libs/qt-3.3.8:3 )
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, and 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, and explicitly declares that changes in the slot or sub-slot can be ignored; -
:SLOT=
means that only the 'SLOT' slot is acceptable, and that your package should be rebuilt if the version matching the runtime dependency is updated to another version with this slot but with a different subslot; -
: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:= )"
USE-Conditional Dependencies
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
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? (
gcj? (
gtk? (
x11-libs/libXt
x11-libs/libX11
x11-libs/libXtst
x11-proto/xproto
x11-proto/xextproto
>=x11-libs/gtk+-2.2
x11-libs/pango
)
>=media-libs/libart_lgpl-2.1
)
>=sys-libs/ncurses-5.2-r2
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 ) )"
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 hasfoo
and notbar
installed.foo
is then unmerged, andbar
is installed.fnord
must continue to work correctly. -
A binary package of
fnord
made on a system withfoo
and notbar
can be taken and installed on a system withbar
and notfoo
.
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 new versions, a use
dependency default may be used. Appending a (+)
or (-)
suffix will indicate
whether the absence of the flag from a particular version should indicate its
presence or absence.
>=dev-libs/boost-1.48[threads(+)]
will treat all versions without threads
as having it set.
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 requiresdev-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 requiredev-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 ondev-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 ondev-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.