7. Declaring relationships between packages

7.1. Syntax of relationship 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, Build-Depends-Indep and Build-Depends-Arch control 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, that part of the dependency can be satisfied by any one of the alternative packages. 1

All of the fields 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.

The relations allowed are <<, <=, =, >= and >> for strictly earlier, earlier or equal, exactly equal, later or equal and strictly later, respectively. The exception is the Provides field, for which only = is allowed. 2

Whitespace may appear at any point in the version specification subject to the rules in Syntax of control files, and must appear where it's necessary to disambiguate; it is not otherwise significant. All of the relationship fields can only be folded in source package control files. 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. When opening a continuation line in a relationship field, it is conventional to do so after a comma and before the space following that comma.

For example, a list of dependencies might appear as:

Package: mutt
Version: 1.3.17-1
Depends: libc6 (>= 2.2.1), default-mta | mail-transport-agent

Relationships 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 non-empty list of Debian architecture names in the format described in Architecture specification strings, 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 while others aren't.)

For build relationship fields (Build-Depends, Build-Depends-Indep, Build-Depends-Arch, Build-Conflicts, Build-Conflicts-Indep and Build-Conflicts-Arch), 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]

requires kernel-headers-2.2.10 on all architectures other than hurd-i386 and requires hurd-dev and gnumach-dev only on hurd-i386. Here is another example showing multiple architectures separated by spaces:

Build-Depends:
 libluajit5.1-dev [i386 amd64 kfreebsd-i386 armel armhf powerpc mips],
 liblua5.1-dev [hurd-i386 ia64 kfreebsd-amd64 s390x sparc],

For binary relationship fields and the Built-Using field, the architecture restriction syntax is only supported in the source package control file debian/control. When the corresponding binary package control file is generated, the relationship will either be omitted or included without the architecture restriction based on the architecture of the binary package. This means that architecture restrictions must not be used in binary relationship fields for architecture-independent packages (Architecture: all).

For example:

Depends: foo [i386], bar [amd64]

becomes Depends: foo when the package is built on the i386 architecture, Depends: bar when the package is built on the amd64 architecture, and omitted entirely in binary packages built on all other architectures.

If the architecture-restricted dependency is part of a set of alternatives using |, that alternative is ignored completely on architectures that do not match the restriction. For example:

Build-Depends: foo [!i386] | bar [!amd64]

is equivalent to bar on the i386 architecture, to foo on the amd64 architecture, and to foo | bar on all other architectures.

Relationships may also be restricted to a certain set of architectures using architecture wildcards in the format described in Architecture wildcards. The syntax for declaring such restrictions is the same as declaring restrictions using a certain set of architectures without architecture wildcards. For example:

Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]

is equivalent to foo on architectures using the Linux kernel and any cpu, bar on architectures using any kernel and an i386 cpu, and baz on any architecture using a kernel other than Linux.

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

7.2. Binary Dependencies - Depends, Recommends, Suggests, Enhances, Pre-Depends

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.

This is done using the Depends, Pre-Depends, Recommends, Suggests, Enhances, Breaks and Conflicts control fields. Breaks is described in Packages which break other packages - Breaks, and Conflicts is described in Conflicting binary packages - Conflicts. The rest are described below.

These seven fields are used to declare a dependency relationship by one package on another. Except for Enhances and Breaks, they appear in the depending (binary) package's control file. (Enhances appears in the recommending package's control file, and Breaks appears in the version of depended-on package which causes the named package to break).

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 apt-get, aptitude, and dselect.)

Since Depends only places requirements on the order in which packages are configured, packages in an installation run are usually all unpacked first and all configured later. 3

If there is a circular dependency among packages being installed or removed, installation or removal order honoring the dependency order is impossible, requiring the dependency loop be broken at some point and the dependency requirements violated for at least one package. Packages involved in circular dependencies may not be able to rely on their dependencies being configured before they themselves are configured, depending on which side of the break of the circular dependency loop they happen to be on. If one of the packages in the loop has no postinst script, then the cycle will be broken at that package; this ensures that all postinst scripts are run with their dependencies properly configured if this is possible. Otherwise the breaking point is arbitrary. Packages should therefore avoid circular dependencies where possible, particularly if they have postinst scripts.

The meaning of the five dependency fields is as follows:

Depends

This declares an absolute dependency. A package will not be configured unless all of the packages listed in its Depends field have been correctly configured (unless there is a circular dependency as described above).

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 or prerm scripts require the depended-on package to be unpacked or configured in order to run. In the case of postinst configure, the depended-on packages will be unpacked and configured first. (If both packages are involved in a dependency loop, this might not work as expected; see the explanation a few paragraphs back.) In the case of prerm or other postinst actions, the package dependencies will normally be at least unpacked, but they may be only "Half-Installed" if a previous upgrade of the dependency failed.

Finally, the Depends field should be used if the depended-on package is needed by the postrm script to fully clean up after the package removal. There is no guarantee that package dependencies will be available when postrm is run, but the depended-on package is more likely to be available if the package declares a dependency (particularly in the case of postrm remove). The postrm script must gracefully skip actions that require a dependency if that dependency isn't available.

Recommends

This declares a strong, but not absolute, dependency.

The Recommends field should list packages that would be found together with this one in all but unusual installations.

Suggests

This is used to declare that one package may be more useful with one or more others. Using this field tells the packaging system and the user that the listed packages are related to this one and can perhaps enhance its usefulness, but that installing this one without them is perfectly reasonable.

Enhances

This field is similar to Suggests but works in the opposite direction. It is used to declare that a package can enhance the functionality of another package.

Pre-Depends

This field is like Depends, except that it also forces 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 in the "Unpacked" or the "Half-Configured" state, 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. It will be considered satisfied only if the depended-on package has been correctly configured. However, unlike with Depends, Pre-Depends does not permit circular dependencies to be broken. If a circular dependency is encountered while attempting to honor Pre-Depends, the installation will be aborted.

Pre-Depends are also required if the preinst script depends on the named package. It is best to avoid this situation if possible.

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.

You should not specify a Pre-Depends entry for a package before this has been discussed on the debian-devel mailing list and a consensus about doing that has been reached. See 依存関係.

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.

7.3. Packages which break other packages - Breaks

When one binary package declares that it breaks another, dpkg will refuse to allow the package which declares Breaks to be unpacked unless the broken package is deconfigured first, and it will refuse to allow the broken package to be reconfigured.

A package will not be regarded as causing breakage merely because its configuration files are still installed; it must be at least "Half-Installed".

A special exception is made for packages which declare that they break their own package name or a virtual package which they provide (see below): this does not count as a real breakage.

Normally a Breaks entry will have an "earlier than" version clause; such a Breaks is introduced in the version of an (implicit or explicit) dependency which violates an assumption or reveals a bug in earlier versions of the broken package, or which takes over a file from earlier versions of the package named in Breaks. This use of Breaks will inform higher-level package management tools that the broken package must be upgraded before the new one.

If the breaking package also overwrites some files from the older package, it should use Replaces to ensure this goes smoothly. See Overwriting files and replacing packages - Replaces for a full discussion of taking over files from other packages, including how to use