148 lines
5.2 KiB
Text
148 lines
5.2 KiB
Text
# dpkg manual page - deb822(5)
|
||
#
|
||
# Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
|
||
# Copyright © 2015 Guillem Jover <guillem@debian.org>
|
||
#
|
||
# This is free software; you can redistribute it and/or modify
|
||
# it under the terms of the GNU General Public License as published by
|
||
# the Free Software Foundation; either version 2 of the License, or
|
||
# (at your option) any later version.
|
||
#
|
||
# This is distributed in the hope that it will be useful,
|
||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
# GNU General Public License for more details.
|
||
#
|
||
# You should have received a copy of the GNU General Public License
|
||
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||
|
||
=encoding utf8
|
||
|
||
=head1 NAME
|
||
|
||
deb822 - Debian RFC822 control data format
|
||
|
||
=head1 DESCRIPTION
|
||
|
||
The package management system manipulates data represented in a common
|
||
format, known as I<control data>, stored in I<control files>.
|
||
Control files are used for source packages, binary packages and the
|
||
B<.changes> files which control the installation of uploaded
|
||
files (B<dpkg>'s internal databases are in a similar format).
|
||
|
||
=head1 SYNTAX
|
||
|
||
A control file consists of one or more stanzas of fields (the stanzas
|
||
sometimes used to be referred to as paragraphs).
|
||
The stanzas are separated by empty lines.
|
||
Parsers may accept lines consisting solely of U+0020 B<SPACE> and
|
||
U+0009 B<TAB> as stanza separators, but control files should use
|
||
empty lines.
|
||
Some control files allow only one stanza; others allow several, in which
|
||
case each stanza usually refers to a different package.
|
||
(For example, in source packages, the first stanza refers to the source
|
||
package, and later stanzas refer to binary packages generated from the
|
||
source.)
|
||
The ordering of the stanzas in control files is significant.
|
||
|
||
Each stanza consists of a series of data fields.
|
||
Each field consists of the field name followed by a colon
|
||
(U+003A ‘B<:>’), 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 ‘B<!>’ through U+0039 ‘B<9>’, and
|
||
U+003B ‘B<;>’ through U+007E ‘B<~>’, inclusive).
|
||
Field names must not begin with the comment character
|
||
(U+0023 ‘B<#>’), nor with the hyphen character
|
||
(U+002D ‘B<->’).
|
||
|
||
The field ends at the end of the line or at the end of the last continuation
|
||
line (see below).
|
||
Horizontal whitespace (U+0020 B<SPACE> and U+0009 B<TAB>) 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:
|
||
|
||
=over
|
||
|
||
Package: dpkg
|
||
|
||
=back
|
||
|
||
the field name is B<Package> and the field value B<dpkg>.
|
||
|
||
Empty field values are only permitted in source package control files
|
||
(I<debian/control>).
|
||
Such fields are ignored.
|
||
|
||
A stanza must not contain more than one instance of a particular field name.
|
||
|
||
There are three types of fields:
|
||
|
||
=over
|
||
|
||
=over
|
||
|
||
=item B<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.
|
||
|
||
=item B<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 U+0020 B<SPACE> or a U+0009 B<TAB>.
|
||
Whitespace, including any newlines, is not significant in the field values
|
||
of folded fields.
|
||
|
||
This folding method is similar to RFC5322, allowing control files that
|
||
contain only one stanza and no multiline fields to be read by parsers
|
||
written for RFC5322.
|
||
|
||
=item B<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.
|
||
|
||
=back
|
||
|
||
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.
|
||
|
||
Stanza separators (empty lines) and lines consisting only of
|
||
U+0020 B<SPACE> and U+0009 B<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 B<SPACE> followed by a dot (U+002E ‘B<.>’).
|
||
|
||
Lines starting with U+0023 ‘B<#>’, without any preceding whitespace
|
||
are comments lines that are only permitted in source package control files
|
||
(I<debian/control>) and in L<deb-origin(5)> files.
|
||
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.
|
||
|
||
=back
|
||
|
||
=head1 SEE ALSO
|
||
|
||
B<RFC822>,
|
||
B<RFC5322>.
|