[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]
The package management system manipulates data represented in a common format,
known as control data, stored in control files. Control
files are used for source packages, binary packages and the
.changes files which control the installation of uploaded files[31].
A control file consists of one or more paragraphs of fields[32]. The paragraphs are separated by empty lines. Parsers may accept lines consisting solely of spaces and tabs as paragraph separators, but control files should use empty lines. Some control files allow only one paragraph; others allow several, in which case each paragraph usually refers to a different package. (For example, in source packages, the first paragraph refers to the source package, and later paragraphs refer to binary packages generated from the source.) The ordering of the paragraphs in control files is significant.
Each paragraph consists of a series of data fields. Each field consists of the field name followed by a colon and then the data/value associated with that field. The field name is composed of US-ASCII characters excluding control characters, space, and colon (i.e., characters in the ranges 33-57 and 59-126, inclusive). Field names must not begin with the comment character, #.
The field ends at the end of the line or at the end of the last continuation line (see below). Horizontal whitespace (spaces and tabs) may occur immediately before or after the value and is ignored there; it is conventional to put a single space after the colon. For example, a field might be:
Package: libc6
the field name is Package and the field value libc6.
A paragraph must not contain more than one instance of a particular field name.
There are three types of fields:
The field, including its value, must be a single line. Folding of the field is not permitted. This is the default field type if the definition of the field does not specify a different type.
The value of a folded field is a logical line that may span several lines. The lines after the first are called continuation lines and must start with a space or a tab. Whitespace, including any newlines, is not significant in the field values of folded fields.[33]
The value of a multiline field may comprise multiple continuation lines. The first line of the value, the part on the same line as the field name, often has special significance or may have to be empty. Other lines are added following the same syntax as the continuation lines of the folded fields. Whitespace, including newlines, is significant in the values of multiline fields.
Whitespace must not appear inside names (of packages, architectures, files or anything else) or version numbers, or between the characters of multi-character version relationships.
The presence and purpose of a field, and the syntax of its value may differ between types of control files.
Field names are not case-sensitive, but it is usual to capitalize the field names using mixed case as shown below. Field values are case-sensitive unless the description of the field says otherwise.
Paragraph separators (empty lines) and lines consisting only of spaces and tabs are not allowed within field values or between fields. Empty lines in field values are usually escaped by representing them by a space followed by a dot.
Lines starting with # without any preceding whitespace are comments lines that
are only permitted in source package control files
(debian/control). These comment lines are ignored, even between
two continuation lines. They do not end logical lines.
All control files must be encoded in UTF-8.
debian/control
The debian/control file contains the most vital (and
version-independent) information about the source package and about the binary
packages it creates.
The first paragraph of the control file contains information about the source package in general. The subsequent sets each describe a binary package that the source tree builds.
The fields in the general paragraph (the first one, for the source package) are:
Source (mandatory)
Maintainer (mandatory)
Uploaders
DM-Upload-Allowed
Section (recommended)
Priority (recommended)
Build-Depends et al
Standards-Version (recommended)
Homepage
The fields in the binary package paragraphs are:
Package (mandatory)
Architecture (mandatory)
Section (recommended)
Priority (recommended)
Essential
Depends et al
Description (mandatory)
Homepage
The syntax and semantics of the fields are described below.
These fields are used by dpkg-gencontrol to generate control files
for binary packages (see below), by dpkg-genchanges to generate
the .changes file to accompany the upload, and by
dpkg-source when it creates the .dsc source control
file as part of a source archive. Some fields are folded in
debian/control, but not in any other control file. These tools
are responsible for removing the line breaks from such fields when using fields
from debian/control to generate other control files.
The fields here may contain variable references - their values will be
substituted by dpkg-gencontrol, dpkg-genchanges or
dpkg-source when they generate output control files. See Variable substitutions:
debian/substvars, Section 4.10 for details.
DEBIAN/control
The DEBIAN/control file contains the most vital (and
version-dependent) information about a binary package. It consists of a single
paragraph.
The fields in this file are:
Package (mandatory)
Source
Version (mandatory)
Section (recommended)
Priority (recommended)
Architecture (mandatory)
Essential
Depends et al
Installed-Size
Maintainer (mandatory)
Description (mandatory)
Homepage
This file consists of a single paragraph, possibly surrounded by a PGP signature. The fields of that paragraph are listed below. Their syntax is described above, in Syntax of control files, Section 5.1.
Format (mandatory)
Source (mandatory)
Binary
Architecture
Version (mandatory)
Maintainer (mandatory)
Uploaders
DM-Upload-Allowed
Homepage
Standards-Version (recommended)
Build-Depends et al
Checksums-Sha1 and Checksums-Sha256 (recommended)
Files (mandatory)
The Debian source control file is generated by dpkg-source when it
builds the source archive, from other files in the source package, described
above. When unpacking, it is checked against the files and directories in the
other parts of the source package.
.changes
The .changes files are used by the Debian archive maintenance
software to process updates to packages. They consist of a single paragraph,
possibly surrounded by a PGP signature. That paragraph contains information
from the debian/control file and other data about the source
package gathered via debian/changelog and
debian/rules.
.changes files have a format version that is incremented whenever
the documented fields or their meaning change. This document describes format
1.8.
The fields in this file are:
Format (mandatory)
Date (mandatory)
Source (mandatory)
Binary (mandatory)
Architecture (mandatory)
Version (mandatory)
Distribution (mandatory)
Urgency (recommended)
Maintainer (mandatory)
Changed-By
Description (mandatory)
Closes
Changes (mandatory)
Checksums-Sha1 and Checksums-Sha256 (recommended)
Files (mandatory)
This field identifies the source package name.
In debian/control or a .dsc file, this field must
contain only the name of the source package.
In a binary package control file or a .changes file, the source
package name may be followed by a version number in parentheses[34]. This version number may be
omitted (and is, by dpkg-gencontrol) if it has the same value as
the Version field of the binary package in question. The field
itself may be omitted from a binary package control file when the source
package has the same name and version as the binary package.
Package names (both source and binary, see Package, Section 5.6.7) must consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). They must be at least two characters long and must start with an alphanumeric character.
The package maintainer's name and email address. The name must come first, then the email address inside angle brackets <> (in RFC822 format).
If the maintainer's name contains a full stop then the whole field will not work directly as an email address due to a misfeature in the syntax specified in RFC822; a program using this field as an address must check for this and correct the problem if necessary (for example by putting the name in round brackets and moving it to the end, and bringing the email address forward).
See The maintainer of a package, Section 3.3 for additional requirements and information about package maintainers.
List of the names and email addresses of co-maintainers of the package, if any. If the package has other maintainers besides the one named in the Maintainer field, their names and email addresses should be listed here. The format of each entry is the same as that of the Maintainer field, and multiple entries must be comma separated.
This is normally an optional field, but if the Maintainer control field names a group of people and a shared email address, the Uploaders field must be present and must contain at least one human with their personal email address.
The Uploaders field in debian/control can be folded.
The name and email address of the person who prepared this version of the package, usually a maintainer. The syntax is the same as for the Maintainer field.
This field specifies an application area into which the package has been classified. See Sections, Section 2.4.
When it appears in the debian/control file, it gives the value for
the subfield of the same name in the Files field of the
.changes file. It also gives the default for the same field in
the binary packages.
This field represents how important it is that the user have the package installed. See Priorities, Section 2.5.
When it appears in the debian/control file, it gives the value for
the subfield of the same name in the Files field of the
.changes file. It also gives the default for the same field in
the binary packages.
The name of the binary package.
Binary package names must follow the same syntax and restrictions as source package names. See Source, Section 5.6.1 for the details.
Depending on context and the control file used, the Architecture field can include the following sets of values:
A unique single word identifying a Debian machine architecture as described in Architecture specification strings, Section 11.1.
An architecture wildcard identifying a set of Debian machine architectures, see Architecture wildcards, Section 11.1.1. any matches all Debian machine architectures and is the most frequently used.
all, which indicates an architecture-independent package.
source, which indicates a source package.
In the main debian/control file in the source package, this field
may contain the special value all, the special architecture
wildcard any, or a list of specific and wildcard architectures
separated by spaces. If all or any appears, that
value must be the entire contents of the field. Most packages will use either
all or any.
Specifying a specific list of architectures indicates that the source will build an architecture-dependent package only on architectures included in the list. Specifying a list of architecture wildcards indicates that the source will build an architecture-dependent package on only those architectures that match any of the specified architecture wildcards. Specifying a list of architectures or architecture wildcards other than any is for the minority of cases where a program is not portable or is not useful on some architectures. Where possible, the program should be made portable instead.
In the Debian source control file .dsc, this field contains a list
of architectures and architecture wildcards separated by spaces. When the list
contains the architecture wildcard any, the only other value
allowed in the list is all.
The list may include (or consist solely of) the special value all.
In other words, in .dsc files unlike the
debian/control, all may occur in combination with
specific architectures. The Architecture field in the Debian
source control file .dsc is generally constructed from the
Architecture fields in the debian/control in the
source package.
Specifying only any indicates that the source package isn't dependent on any particular architecture and should compile fine on any one. The produced binary package(s) will be specific to whatever the current build architecture is.
Specifying only all indicates that the source package will only build architecture-independent packages.
Specifying any all indicates that the source package isn't dependent on any particular architecture. The set of produced binary packages will include at least one architecture-dependant package and one architecture-independent package.
Specifying a list of architectures or architecture wildcards indicates that the source will build an architecture-dependent package, and will only work correctly on the listed or matching architectures. If the source package also builds at least one architecture-independent package, all will also be included in the list.
In a .changes file, the Architecture field lists the
architecture(s) of the package(s) currently being uploaded. This will be a
list; if the source for the package is also being uploaded, the special entry
source is also present. all will be present if any
architecture-independent packages are being uploaded. Architecture wildcards
such as any must never occur in the Architecture
field in the .changes file.
See Main building script:
debian/rules, Section 4.9 for information on how to get the
architecture for the build process.
This is a boolean field which may occur only in the control file of a binary package or in a per-package fields paragraph of a source package control file.
If set to yes then the package management system will refuse to remove the package (upgrading and replacing it is still possible). The other possible value is no, which is the same as not having the field at all.
These fields describe the package's relationships with other packages. Their syntax and semantics are described in Declaring relationships between packages, Chapter 7.
The most recent version of the standards (the policy manual and associated texts) with which the package complies.
The version number has four components: major and minor version number and major and minor patch level. When the standards change in a way that requires every package to change the major number will be changed. Significant changes that will require work in many packages will be signaled by a change to the minor number. The major patch level will be changed for any change to the meaning of the standards, however small; the minor patch level will be changed when only cosmetic, typographical or other edits are made which neither change the meaning of the document nor affect the contents of packages.
Thus only the first three components of the policy version are significant in the Standards-Version control field, and so either these three components or all four components may be specified.[35]
The version number of a package. The format is: [epoch:]upstream_version[-debian_revision]
The three components here are:
This is a single (generally small) unsigned integer. It may be omitted, in which case zero is assumed. If it is omitted then the upstream_version may not contain any colons.
It is provided to allow mistakes in the version numbers of older versions of a package, and also a package's previous version numbering schemes, to be left behind.
This is the main part of the version number. It is usually the version number
of the original ("upstream") package from which the .deb
file has been made, if this is applicable. Usually this will be in the same
format as that specified by the upstream author(s); however, it may need to be
reformatted to fit into the package management system's format and comparison
scheme.
The comparison behavior of the package management system with respect to the upstream_version is described below. The upstream_version portion of the version number is mandatory.
The upstream_version may contain only alphanumerics[36] and the characters . + - : ~ (full stop, plus, hyphen, colon, tilde) and should start with a digit. If there is no debian_revision then hyphens are not allowed; if there is no epoch then colons are not allowed.
This part of the version number specifies the version of the Debian package based on the upstream version. It may contain only alphanumerics and the characters + . ~ (plus, full stop, tilde) and is compared in the same way as the upstream_version is.
It is optional; if it isn't present then the upstream_version may not contain a hyphen. This format represents the case where a piece of software was written specifically to be a Debian package, where the Debian package source must always be identical to the pristine source and therefore no revision indication is required.
It is conventional to restart the debian_revision at 1 each time the upstream_version is increased.
The package management system will break the version number apart at the last hyphen in the string (if there is one) to determine the upstream_version and debian_revision. The absence of a debian_revision is equivalent to a debian_revision of 0.
When comparing two version numbers, first the epoch of each are compared, then the upstream_version if epoch is equal, and then debian_revision if upstream_version is also equal. epoch is compared numerically. The upstream_version and debian_revision parts are compared by the package management system using the following algorithm:
The