[ previous ] [ Abstract ] [ Copyright Notice ] [ Contents ] [ next ]

Debian Policy Manual
Chapter 3 Control files and their fields


Many of the tools in the package management 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.


3.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 immediately 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 capitalize 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 conjunction with the details below and the list of fields for the particular file.


3.2 List of fields

This list here is not supposed to be exhaustive. Typically only fields for whom policy exists are mentioned here.


3.2.1 Package

The name of the binary package. Package names consist of the alphanumerics and + - . (plus, minus and full stop).

They must be at least two characters long and must start with an alphanumeric character. The use lowercase package names is strongly recommended unless the package you're building (or referring to, in other fields) is already using uppercase.


3.2.2 Version

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


3.2.3 Standards-Version

The most recent version of the standards (the packaging 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.


3.2.4 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, Section 3.2.1).

[7]


[ previous ] [ Abstract ] [ Copyright Notice ] [ Contents ] [ next ]
Debian Policy Manual
version 3.5.0.0, 2001-01-28
Ian Jackson ijackson@gnu.ai.mit.edu
Christian Schwarz schwarz@debian.org
revised: David A. Morris bweaver@debian.org
The Debian Policy mailing List debian-policy@lists.debian.org