(debian-policy.info)Syntax of control files

---

Next: Source package control files – debian/control Up: Control files and their fields

---

Enter node , (file) or (file)node

5.1 Syntax of control files
===========================

A control file consists of one or more paragraphs of fields.  (1) The
paragraphs are separated by empty lines.  Parsers may accept lines
consisting solely of spaces and tabs as paragraph separators, but
control files should use empty lines.  Some control files allow only one
paragraph; others allow several, in which case each paragraph usually
refers to a different package.  (For example, in source packages, the
first paragraph refers to the source package, and later paragraphs refer
to binary packages generated from the source.)  The ordering of the
paragraphs in control files is significant.

Each paragraph consists of a series of data fields.  Each field consists
of the field name followed by a colon and then the data/value associated
with that field.  The field name is composed of US-ASCII characters
excluding control characters, space, and colon (i.e., characters in the
ranges U+0021 (‘!’) through U+0039 (‘9’), and U+003B (‘;’) through
U+007E (‘~’), inclusive).  Field names must not begin with the comment
character (U+0023 ‘#’), nor with the hyphen character (U+002D ‘-’).

The field ends at the end of the line or at the end of the last
continuation line (see below).  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.  For example, a
field might be:

     Package: libc6

the field name is ‘Package’ and the field value ‘libc6’.

Empty field values are only permitted in source package control files
(‘debian/control’).  Such fields are ignored.

A paragraph must not contain more than one instance of a particular
field name.

There are three types of fields:

simple

     The field, including its value, must be a single line.  Folding of
     the field is not permitted.  This is the default field type if the
     definition of the field does not specify a different type.

folded

     The value of a folded field is a logical line that may span several
     lines.  The lines after the first are called continuation lines and
     must start with a space or a tab.  Whitespace, including any
     newlines, is not significant in the field values of folded fields.
     (2)

multiline

     The value of a multiline field may comprise multiple continuation
     lines.  The first line of the value, the part on the same line as
     the field name, often has special significance or may have to be
     empty.  Other lines are added following the same syntax as the
     continuation lines of the folded fields.  Whitespace, including
     newlines, is significant in the values of multiline fields.

Whitespace must not appear inside names (of packages, architectures,
files or anything else) or version numbers, or between the characters of
multi-character version relationships.

The presence and purpose of a field, and the syntax of its value may
differ between types of control files.

Field names are not case-sensitive, but it is usual to capitalize the
field names using mixed case as shown below.  Field values are
case-sensitive unless the description of the field says otherwise.

Paragraph separators (empty lines), and lines consisting only of U+0020
SPACE and U+0009 TAB, are not allowed within field values or between
fields.  Empty lines in field values are usually escaped by representing
them by a U+0020 SPACE followed by a U+002E (‘.’).

Lines starting with U+0023 (‘#’), without any preceding whitespace, are
comment lines that are only permitted in source package control files
(‘debian/control’).  These comment lines are ignored, even between two
continuation lines.  They do not end logical lines.

All control files must be encoded in UTF-8.

   ---------- Footnotes ----------

   (1) The paragraphs are also sometimes referred to as stanzas.

   (2) This folding method is similar to RFC 5322, allowing control
files that contain only one paragraph and no multiline fields to be read
by parsers written for RFC 5322.