Packages can declare in their control file that they have certain relationships to other packages - for example, that they may not be installed at the same time as certain other packages, and/or that they depend on the presence of others, or that they should overwrite files in certain other packages if present.
This is done using the Depends, Pre-Depends, Recommends, Suggests, Enhances, Conflicts, Provides and Replaces control file fields.
Source packages may declare relationships to binary packages, saying that they require certain binary packages to be installed or absent at the time of building the package.
This is done using the Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep control file fields.
These fields all have a uniform syntax. They are a list of package names separated by commas.
In the Depends, Recommends, Suggests, Pre-Depends, Build-Depends and Build-Depends-Indep control file fields of the package, which declare dependencies on other packages, the package names listed may also include lists of alternative package names, separated by vertical bar (pipe) symbols |. In such a case, if any one of the alternative packages is installed, that part of the dependency is considered to be satisfied.
All of the fields except for Provides may restrict their applicability to particular versions of each named package. This is done in parentheses after each individual package name; the parentheses should contain a relation from the list below followed by a version number, in the format described in Version numbering, Chapter 4.
The relations allowed are <<, <=,
=, >= and >> for strictly
earlier, earlier or equal, exactly equal, later or equal and strictly later,
respectively. The deprecated forms < and >
were used to mean earlier/later or equal, rather than strictly earlier/later,
so they should not appear in new packages (though dpkg
still
supports them).
Whitespace may appear at any point in the version specification subject to the
rules in Syntax of control
files, Section 3.1, and must appear where it's necessary to disambiguate;
it is not otherwise significant. For consistency and in case of future changes
to dpkg
it is recommended that a single space be used after a
version relationship and before a version number; it is also conventional to
put a single space after each comma, on either side of each vertical bar, and
before each open parenthesis.
For example, a list of dependencies might appear as:
Package: mutt Version: 1.3.17-1 Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
All fields that specify build-time relationships (Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep) may be restricted to a certain set of architectures. This is indicated in brackets after each individual package name and the optional version specification. The brackets enclose a list of Debian architecture names separated by whitespace. Exclamation marks may be prepended to each of the names. (It is not permitted for some names to be prepended with exclamation marks and others not.) If the current Debian host architecture is not in this list and there are no exclamation marks in the list, or it is in the list with a prepended exclamation mark, the package name and the associated version specification are ignored completely for the purposes of defining the relationships.
For example:
Source: glibc Build-Depends-Indep: texinfo Build-Depends: kernel-headers-2.2.10 [!hurd-i386], hurd-dev [hurd-i386], gnumach-dev [hurd-i386]
Note that the binary package relationship fields such as Depends appear in one of the binary package sections of the control file, whereas the build-time relationships such as Build-Depends appear in the source package section of the control file (which is the first section).
These five fields are used to declare a dependency relationship by one package on another. Except for Enhances, they appear in the depending (binary) package's control file. (Enhances appears in the recommending package's control file.)
A Depends field takes effect only when a package is to be
configured. It does not prevent a package being on the system in an
unconfigured state while its dependencies are unsatisfied, and it is possible
to replace a package whose dependencies are satisfied and which is properly
installed with a different version whose dependencies are not and cannot be
satisfied; when this is done the depending package will be left unconfigured
(since attempts to configure it will give errors) and will not function
properly. If it is necessary, a Pre-Depends field can be used,
which has a partial effect even when a package is being unpacked, as explained
in detail below. (The other three dependency fields, Recommends,
Suggests and Enhances, are only used by the various
front-ends to dpkg
such as dselect
.)
For this reason packages in an installation run are usually all unpacked first and all configured later; this gives later versions of packages with dependencies on later versions of other packages the opportunity to have their dependencies satisfied.
The Depends field thus allows package maintainers to impose an order in which packages should be configured.
The meaning of the five dependency fields is as follows:
The Depends field should be used if the depended-on package is required for the depending package to provide a significant amount of functionality.
The Depends field should also be used if the
postinst
, prerm
or postrm
scripts
require the package to be present in order to run. Note, however, that the
postrm
cannot rely on any non-essential packages to be present
during the purge phase.
The Recommends field should list packages that would be found together with this one in all but unusual installations.
dpkg
to complete installation of the packages named before even
starting the installation of the package which declares the pre-dependency, as
follows:
When a package declaring a pre-dependency is about to be unpacked the pre-dependency can be satisfied if the depended-on package is either fully configured, or even if the depended-on package(s) are only unpacked or half-configured, provided that they have been configured correctly at some point in the past (and not removed or partially removed since). In this case, both the previously-configured and currently unpacked or half-configured versions must satisfy any version clause in the Pre-Depends field.
When the package declaring a pre-dependency is about to be configured, the pre-dependency will be treated as a normal Depends, that is, it will be considered satisfied only if the depended-on package has been correctly configured.
Pre-Depends should be used sparingly, preferably only by packages whose premature upgrade or installation would hamper the ability of the system to continue with any upgrade that might be in progress.
Pre-Depends are also required if the preinst
script
depends on the named package. It is best to avoid this situation if possible.
When selecting which level of dependency to use you should consider how important the depended-on package is to the functionality of the one declaring the dependency. Some packages are composed of components of varying degrees of importance. Such a package should list using Depends the package(s) which are required by the more important components. The other components' requirements may be mentioned as Suggestions or Recommendations, as appropriate to the components' relative importance.
When one binary package declares a conflict with another using a
Conflicts field, dpkg
will refuse to allow them to be
installed on the system at the same time.
If one package is to be installed, the other must be removed first - if the
package being installed is marked as replacing (see Overwriting files and replacing
packages - Replaces, Section 7.5) the one on the system, or
the one on the system is marked as deselected, or both packages are marked
Essential, then dpkg
will automatically remove the
package which is causing the conflict, otherwise it will halt the installation
of the new package with an error. This mechanism is specifically designed to
produce an error when the installed package is Essential, but the
new package is not.
A package will not cause a conflict merely because its configuration files are still installed; it must be at least half-installed.
A special exception is made for packages which declare a conflict with their own package name, or with a virtual package which they provide (see below): this does not prevent their installation, and allows a package to conflict with others providing a replacement for it. You use this feature when you want the package in question to be the only package providing some feature.
A Conflicts entry should almost never have an `earlier than'
version clause. This would prevent dpkg
from upgrading or
installing the package which declared such a conflict until the upgrade or
removal of the conflicted-with package had been completed.
As well as the names of actual (`concrete') packages, the package relationship fields Depends, Recommends, Suggests, Enhances, Pre-Depends, Conflicts, Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep may mention `virtual packages'.
A virtual package is one which appears in the Provides control file field of another package. The effect is as if the package(s) which provide a particular virtual package name had been listed by name everywhere the virtual package name appears.
If there are both a real and a virtual package of the same name then the dependency may be satisfied (or the conflict caused) by either the real package or any of the virtual packages which provide it. This is so that, for example, supposing we have
Package: foo Depends: bar
and someone else releases an enhanced version of the bar package (for example, a non-US variant), they can say:
Package: bar-plus Provides: bar
and the bar-plus package will now also satisfy the dependency for the foo package.
If a dependency or a conflict has a version number attached then only real packages will be considered to see whether the relationship is satisfied (or the prohibition violated, for a conflict) - it is assumed that a real package which provides the virtual package is not of the `right' version. So, a Provides field may not contain version numbers, and the version number of the concrete package which provides a particular virtual package will not be looked at when considering a dependency on or conflict with the virtual package name.
It is likely that the ability will be added in a future release of
dpkg
to specify a version number for each virtual package it
provides. This feature is not yet present, however, and is expected to be used
only infrequently.
If you want to specify which of a set of real packages should be the default to satisfy a particular dependency on a virtual package, you should list the real package as an alternative before the virtual one.
The Replaces control file field has two distinct purposes, which come into play in different situations.
Firstly, as mentioned before, it is usually an error for a package to contain files which are on the system in another package.
However, if the overwriting package declares that it Replaces the
one containing the file being overwritten, then dpkg
will replace
the file from the old package with that from the new. The file will no longer
be listed as `owned' by the old package.
If a package is completely replaced in this way, so that dpkg
does
not know of any files it still contains, it is considered to have
`disappeared'. It will be marked as not wanted on the system (selected for
removal) and not installed. Any conffiles details noted for the
package will be ignored, as they will have been taken over by the overwriting
package. The package's postrm
script will be run with a special
argument to allow the package to do any final cleanup required. See Summary of ways maintainer
scripts are called, Section 6.4.
If an installed package, foo say, declares that it replaces
another, bar, and an attempt is made to install bar,
dpkg
will discard files in the bar package which
would overwrite those already present in foo. This is so that you
can install an older version of a package without problems.
For this usage of Replaces, virtual packages (see Virtual packages - Provides, Section 7.4) are not considered when looking at a Replaces field - the packages declared as being replaced must be mentioned by their real names.
Furthermore, this usage of Replaces only takes effect when both packages are at least partially on the system at once, so that it can only happen if they do not conflict or if the conflict has been overridden.
Secondly, Replaces allows the packaging system to resolve which package should be removed when there is a conflict - see Conflicting binary packages - Conflicts, Section 7.3. This usage only takes effect when the two packages do conflict, so that the two usages of this field do not interfere with each other.
In this situation, the package declared as being replaced can be a virtual package, so for example, all mail transport agents (MTAs) would have the following fields in their control files:
Provides: mail-transport-agent Conflicts: mail-transport-agent Replaces: mail-transport-agent
ensuring that only one MTA can be installed at any one time.
A source package may declare a dependency or a conflict on a binary package, indicating which packages are required to be present on the system in order to build the binary packages from the source package. This is done with the control file fields Build-Depends, Build-Depends-Indep, Build-Conflicts and Build-Conflicts-Indep. The dependencies and conflicts they define must be satisfied (as defined earlier for binary packages) in order to invoke the targets in debian/rules, as follows:
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.edu
schwarz@debian.org
bweaver@debian.org
debian-policy@lists.debian.org