# Debian packaging manual - chapter 4
Control files and their fields

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.

## 4.1 Syntax of control files

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.

## 4.2 List of fields

### 4.2.1 `Package`

The name of the binary package. Package names consist of the alphanumerics and `+` `-` `.` (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.

### 4.2.2 `Version`

This lists the source or binary package's version number - see Version numbering, chapter 5.

### 4.2.3 `Architecture`

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`.[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`.

### 4.2.4 `Maintainer`

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.

### 4.2.5 `Source`

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

### 4.2.6 Package interrelationship fields: `Depends`, `Pre-Depends`, `Recommends` `Suggests`, `Conflicts`, `Provides`, `Replaces`

These fields describe the package's relationships with other packages. Their syntax and semantics are described in Declaring relationships between packages, chapter 8.

### 4.2.7 `Description`

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.

### 4.2.8 `Essential`

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.

### 4.2.9 `Section` and `Priority`

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

### 4.2.10 `Binary`

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.[17] Currently the packages must be separated using only spaces in the `.changes` file.

### 4.2.11 `Installed-Size`

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.

### 4.2.12 `Files`

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

### 4.2.13 `Standards-Version`

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.

### 4.2.14 `Distribution`

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:

stable
  This is the current `released' version of Debian GNU/Linux. A new version is released approximately every 3 months after the development code has been frozen for a month of testing. Once the distribution is stable only major bug fixes are allowed. When changes are made to this distribution, the minor version number is increased (for example: 1.2 becomes 1.2.1 then 1.2.2, etc).

unstable
  This distribution value refers to the developmental part of the Debian distribution tree. New packages, new upstream versions of packages and bug fixes go into the unstable directory tree. Download from this distribution at your own risk.

contrib
  The packages with this distribution value do not meet the criteria for inclusion in the main Debian distribution as defined by the Policy Manual, but meet the criteria for the contrib Distribution. There is currently no distinction between stable and unstable packages in the contrib or non-free distributions. Use your best judgement in downloading from this Distribution.

non-free
  Like the packages in the contrib seciton, the packages in non-free do not meet the criteria for inclusion in the main Debian distribution as defined by the Policy Manual. Again, use your best judgement in downloading from this Distribution.

experimental
  The packages with this distribution value are deemed by their maintainers to be high risk. Oftentimes they represent early beta or developmental packages from various sources that the maintainers want people to try, but are not ready to be a part of the other parts of the Debian distribution tree. Download at your own risk.

frozen
  From time to time, (currently, every 3 months) the unstable distribution enters a state of `code-freeze' in anticipation of release as a stable version. During this period of testing (usually 4 weeks) only fixes for existing or newly-discovered bugs will be allowed.

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.

### 4.2.15 `Urgency`

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.

### 4.2.16 `Date`

In `.changes` files and parsed changelogs, this gives the date the package was built or last edited.

### 4.2.17 `Format`

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.

### 4.2.18 `Changes`

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

### 4.2.19 `Filename` and `MSDOS-Filename`

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.

### 4.2.20 `Size` and `MD5sum`

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.

### 4.2.21 `Status`

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.

### 4.2.22 `Config-Version`

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.

### 4.2.23 `Conffiles`

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!

### 4.2.24 Obsolete fields

These are still recognised by `dpkg` but should not appear anywhere any more.

`Revision`
`Package-Revision`
`Package_Revision`
  The Debian revision part of the package version was at one point in a separate control file field. This field went through several names.
`Recommended`
  Old name for `Recommends`
`Optional`
  Old name for `Suggests`.
`Class`
  Old name for `Priority`.

Debian packaging manual - Copyright ©1996 Ian Jackson.
Contents; abstract; next; back.