Many of the tools in the dpkg suite manipulate data in a common
format, known as control files. Binary and source packages have control data
as do the .changes files which control the installation of
uploaded files, and dpkg's internal databases are in a similar
format.
A file consists of one or more paragraphs of fields. The paragraphs are separated by blank lines. Some control files only allow one paragraph; others allow several, in which case each paragraph often refers to a different package.
Each paragraph is a series of fields and values; each field consists of a name, followed by a colon and the value. It ends at the end of the line. Horizontal whitespace (spaces and tabs) may occur before or after the value and is ignored there; it is conventional to put a single space after the colon.
Some fields' values may span several lines; in this case each continuation line must start with a space or tab. Any trailing spaces or tabs at the end of individual lines of a field value are ignored.
Except where otherwise stated only a single line of data is allowed and whitespace is not significant in a field body. Whitespace may never appear inside names (of packages, architectures, files or anything else), version numbers or in between the characters of multi-character version relationships.
Field names are not case-sensitive, but it is usual to capitalise the field names using mixed case as shown below.
Blank lines, or lines consisting only of spaces and tabs, are not allowed within field values or between fields - that would mean a new paragraph.
It is important to note that there are several fields which are optional as far
as dpkg and the related tools are concerned, but which must appear
in every Debian package, or whose omission may cause problems. When writing
the control files for Debian packages you must read the Debian policy
manual in conjuction with the details below and the list of fields for the
particular file.
The name of the binary package. Package names consist of the alphanumerics and + - . (plus, minus and full stop). [74]
They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are sort of case-sensitive[75]; use lowercase package names unless the package you're building (or referring to, in other fields) is already using uppercase.
This lists the source or binary package's version number - see Version numbering, Chapter 4.
This is the architecture string; it is a single word for the Debian architecture.
dpkg will check the declared architecture of a binary package
against its own compiled-in value before it installs it.
The special value all indicates that the package is architecture-independent.
In the main debian/control file in the source package, or in the source package control file .dsc, a list of architectures (separated by spaces) is also allowed, as is the special value any. A list indicates that the source will build an architecture-dependent package, and will only work correctly on the listed architectures. any indicates that though the source package isn't dependent on any particular architecture and should compile fine on any one, the binary package(s) produced are not architecture-independent but will instead be specific to whatever the current build architecture is.
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 being uploaded too the special entry source is also present.
See debian/rules - the main building script, Section C.2.1 for information how to get the architecture for the build process.
The package maintainer's name and email address. The name should 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).
In a .changes file or parsed changelog data this contains the name and email address of the person responsible for the particular version in question - this may not be the package's usual maintainer.
This field is usually optional in as far as the dpkg are
concerned, but its absence when building packages usually generates a warning.
This field identifies the source package name.
In a main source control information or a .changes or .dsc file or parsed changelog data this may contain only the name of the source package.
In the control file of a binary package (or in a Packages file) it
may be followed by a version number in parentheses. [76] 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.
These fields describe the package's relationships with other packages. Their syntax and semantics are described in Declaring relationships between packages, Chapter 7.
In a binary package Packages file or main source control file this field contains a description of the binary package, in a special format. See Descriptions of packages - the Description field, Section 5.7 for details.
In a .changes file it contains a summary of the descriptions for the packages being uploaded. The part of the field before the first newline is empty; thereafter each line has the name of a binary package and the summary description line from that binary package. Each line is indented by one space.
This is a boolean field which may occur only in the control file of a binary package (or in the Packages file) or in a per-package fields paragraph of a main source control data file.
If set to yes then dpkg and dselect will
refuse to remove the package (though it can be upgraded and/or replaced). The
other possible value is no, which is the same as not having the
field at all.
These two fields classify the package. The Priority represents how important that it is that the user have it installed; the Section represents an application area into which the package has been classified.
When they appear in the debian/control file these fields give values for the section and priority subfields of the Files field of the .changes file, and give defaults for the section and priority of the binary packages.
The section and priority are represented, though not as separate fields, in the information for each file in the -Filefield of a .changes file. The section value in a .changes file is used to decide where to install a package in the FTP archive.
These fields are not used by by dpkg proper, but by
dselect when it sorts packages and selects defaults. See the
Debian policy manual for the priorities in use and the criteria for selecting
the priority for a Debian package, and look at the Debian FTP archive for a
list of currently in-use priorities.
These fields may appear in binary package control files, in which case they
provide a default value in case the Packages files are missing the
information. dpkg and dselect will only use the
value from a .deb file if they have no other information; a value
listed in a Packages file will always take precedence. By default
dpkg-gencontrol does not include the section and priority in the
control file of a binary package - use the -isp, -is
or -ip options to achieve this effect.
This field is a list of binary packages.
When it appears in the .dsc file it is the list of binary packages which a source package can produce. It does not necessarily produce all of these binary packages for every architecture. The source control file doesn't contain details of which architectures are appropriate for which of the binary packages.
When it appears in a .changes file it lists the names of the binary packages actually being uploaded.
The syntax is a list of binary packages separated by commas. [77] Currently the packages must be separated using only spaces in the .changes file.
This field appears in the control files of binary packages, and in the Packages files. It gives the total amount of disk space required to install the named package.
The disk space is represented in kilobytes as a simple decimal number.
This field contains a list of files with information about each one. The exact information and syntax varies with the context. In all cases the the part of the field contents on the same line as the field name is empty. The remainder of the field is one line per file, each line being indented by one space and containing a number of sub-fields separated by spaces.
In the .dsc (Debian source control) file each line contains the MD5 checksum, size and filename of the tarfile and (if applicable) diff file which make up the remainder of the source package. [78] The exact forms of the filenames are described in Source packages as archives, Section C.3.
In the .changes file this contains one line per file being uploaded. Each line contains the MD5 checksum, size, section and priority and the filename. The section and priority are the values of the corresponding fields in the main source control file - see Section and Priority, Section D.2.9. If no section or priority is specified then - should be used, though section and priority values must be specified for new packages to be installed properly.
The special value byhand for the section in a .changes file indicates that the file in question is not an ordinary package file and must by installed by hand by the distribution maintainers. If the section is byhand the priority should be -.
If a new Debian revision of a package is being shipped and no new original source archive is being distributed the .dsc must still contain the Files field entry for the original source archive package-upstream-version.orig.tar.gz, but the .changes file should leave it out. In this case the original source archive on the distribution site must match exactly, byte-for-byte, the original source archive which was used to generate the .dsc file and diff which are being uploaded.
The most recent version of the standards (the dpkg programmers'
and policy manuals and associated texts) with which the package complies. This
is updated manually when editing the source package to conform to newer
standards; it can sometimes be used to tell when a package needs attention.
Its format is the same as that of a version number except that no epoch or Debian revision is allowed - see Version numbering, Chapter 4.
In a .changes file or parsed changelog output this contains the (space-separated) name(s) of the distribution(s) where this version of the package should be or was installed. Distribution names follow the rules for package names. (See Package, Section D.2.1).
Current distribution values are:
You should list all distributions that the package should be installed into. Except in unusual circumstances, installations to stable should also go into frozen (if it exists) and unstable. Likewise, installations into frozen should also go into unstable.
This is a description of how important it is to upgrade to this version from previous ones. It consists of a single keyword usually taking one of the values LOW, MEDIUM or HIGH) followed by an optional commentary (separated by a space) which is usually in parentheses. For example:
Urgency: LOW (HIGH for diversions users)
This field appears in the .changes file and in parsed changelogs;
its value appears as the value of the urgency attribute in a
dpkg-style changelog (see debian/changelog,
Section C.2.3).
Urgency keywords are not case-sensitive.
In .changes files and parsed changelogs, this gives the date the package was built or last edited.
This field occurs in .changes files, and specifies a format revision for the file. The format described here is version 1.5. The syntax of the format value is the same as that of a package version number except that no epoch or Debian revision is allowed - see Version numbering, Chapter 4.
In a .changes file or parsed changelog this field contains the human-readable changes data, describing the differences between the last version and the current one.
There should be nothing in this field before the first newline; all the subsequent lines must be indented by at least one space; blank lines must be represented by a line consiting only of a space and a full stop.
Each version's change information should be preceded by a `title' line giving at least the version, distribution(s) and urgency, in a human-readable way.
If data from several versions is being returned the entry for the most recent version should be returned first, and entries should be separated by the representation of a blank line (the `title' line may also be followed by the representation of blank line).
These fields in Packages files give the filename(s) of (the parts of) a package in the distribution directories, relative to the root of the Debian hierarchy. If the package has been split into several parts the parts are all listed in order, separated by spaces.
These fields in Packages files give the size (in bytes, expressed in decimal) and MD5 checksum of the file(s) which make(s) up a binary package in the distribution. If the package is split into several parts the values for the parts are listed in order, separated by spaces.
This field in dpkg's status file records whether the user wants a
package installed, removed or left alone, whether it is broken (requiring
reinstallation) or not and what its current state on the system is. Each of
these pieces of information is a single word.
If a package is not installed or not configured, this field in
dpkg's status file records the last version of the package which
was successfully configured.
This field in dpkg's status file contains information about the
automatically-managed configuration files held by a package. This field should
not appear anywhere in a package!
These are still recognised by dpkg but should not appear anywhere
any more.
Debian Policy Manual
version 3.5.6.1, 2002-03-14ijackson@gnu.ai.mit.eduschwarz@debian.orgbweaver@debian.orgdebian-policy@lists.debian.org