.changes
files which control the
installation of uploaded files, and dpkg's internal databases
are in a similar format.
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.
Package
+
-
.
(plus, minus and full
stop).[13]They must be at least two characters and must start with an alphanumeric. In current versions of dpkg they are sort of case-sensitive[14]; use lowercase package names unless the package you're building (or referring to, in other fields) is already using uppercase.
Version
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
.[15]
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
.
Maintainer
<>
(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.
Source
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.[16] 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.
Depends
, Pre-Depends
, Recommends
Suggests
, Conflicts
, Provides
, Replaces
Description
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.
Essential
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.
Section
and Priority
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 Files
field 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.
Binary
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.[17]
Currently the packages must be separated using only spaces in the
.changes
file.
Installed-Size
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.
Files
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.[18] 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.
Standards-Version
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.
Distribution
.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 stable
, unstable
,
contrib
, non-free
and experimental
.
Urgency
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.
Date
.changes
files and parsed changelogs, this gives the date the
package was built or last edited.
Format
.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.
Changes
.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).
Filename
and MSDOS-Filename
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.
Size
and MD5sum
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.
Status
Config-Version
Conffiles
Revision
Package-Revision
Package_Revision
Recommended
Recommends
Optional
Suggests
.
Class
Priority
.