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 fields 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). [14]
They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are sort of case-sensitive[15]; 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 5.
This is the architecture string; it is a single word for the CPU 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.
The current build architecture can be determined using dpkg
--print-architecture.
[16] This value is automatically used by
dpkg-gencontrol
when building the control
file for a binary package for which the source control
information doesn't specify architecture all.
There is a separate option,
--print-installation-architecture, for finding
out what architecture dpkg
is willing to
install. This information is also in the output of
dpkg --version.
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.
[17] 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 8.
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, chapter 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-genchanges
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. [18] 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. [19] The exact forms of the filenames are described in Source packages as archives, section 3.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, subsection 4.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 5.
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, subsection 4.2.1).
Current distribution values are:
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, subsection 3.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 5.
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.