man/deb822.pod

   1 # dpkg manual page - deb822(5)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 # Copyright © 2015 Guillem Jover <guillem@debian.org>
   5 #
   6 # This is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18
  19 =encoding utf8
  20
  21 =head1 NAME
  22
  23 deb822 - Debian RFC822 control data format
  24
  25 =head1 DESCRIPTION
  26
  27 The package management system manipulates data represented in a common
  28 format, known as I<control data>, stored in I<control files>.
  29 Control files are used for source packages, binary packages and the
  30 B<.changes> files which control the installation of uploaded
  31 files (B<dpkg>'s internal databases are in a similar format).
  32
  33 =head1 SYNTAX
  34
  35 A control file consists of one or more stanzas of fields (the stanzas
  36 sometimes used to be referred to as paragraphs).
  37 The stanzas are separated by empty lines.
  38 Parsers may accept lines consisting solely of U+0020 B<SPACE> and
  39 U+0009 B<TAB> as stanza separators, but control files should use
  40 empty lines.
  41 Some control files allow only one stanza; others allow several, in which
  42 case each stanza usually refers to a different package.
  43 (For example, in source packages, the first stanza refers to the source
  44 package, and later stanzas refer to binary packages generated from the
  45 source.)
  46 The ordering of the stanzas in control files is significant.
  47
  48 Each stanza consists of a series of data fields.
  49 Each field consists of the field name followed by a colon
  50 (U+003A ‘B<:>’), and then the data/value associated with that field.
  51 The field name is composed of US-ASCII characters excluding control
  52 characters, space, and colon (i.e., characters in the ranges
  53 U+0021 ‘B<!>’ through U+0039 ‘B<9>’, and
  54 U+003B ‘B<;>’ through U+007E ‘B<~>’, inclusive).
  55 Field names must not begin with the comment character
  56 (U+0023 ‘B<#>’), nor with the hyphen character
  57 (U+002D ‘B<->’).
  58
  59 The field ends at the end of the line or at the end of the last continuation
  60 line (see below).
  61 Horizontal whitespace (U+0020 B<SPACE> and U+0009 B<TAB>) may occur
  62 immediately before or after the value and is ignored there; it is conventional
  63 to put a single space after the colon.
  64 For example, a field might be:
  65
  66 =over
  67
  68  Package: dpkg
  69
  70 =back
  71
  72 the field name is B<Package> and the field value B<dpkg>.
  73
  74 Empty field values are only permitted in source package control files
  75 (I<debian/control>).
  76 Such fields are ignored.
  77
  78 A stanza must not contain more than one instance of a particular field name.
  79
  80 There are three types of fields:
  81
  82 =over
  83
  84 =over
  85
  86 =item B<simple>
  87
  88 The field, including its value, must be a single line.
  89 Folding of the field is not permitted.
  90 This is the default field type if the definition of the field does not
  91 specify a different type.
  92
  93 =item B<folded>
  94
  95 The value of a folded field is a logical line that may span several lines.
  96 The lines after the first are called continuation lines and must start with
  97 a U+0020 B<SPACE> or a U+0009 B<TAB>.
  98 Whitespace, including any newlines, is not significant in the field values
  99 of folded fields.
 100
 101 This folding method is similar to RFC5322, allowing control files that
 102 contain only one stanza and no multiline fields to be read by parsers
 103 written for RFC5322.
 104
 105 =item B<multiline>
 106
 107 The value of a multiline field may comprise multiple continuation lines.
 108 The first line of the value, the part on the same line as the field name,
 109 often has special significance or may have to be empty.
 110 Other lines are added following the same syntax as the continuation lines
 111 of the folded fields.
 112 Whitespace, including newlines, is significant in the values of multiline
 113 fields.
 114
 115 =back
 116
 117 Whitespace must not appear inside names (of packages, architectures, files
 118 or anything else) or version numbers, or between the characters of
 119 multi-character version relationships.
 120
 121 The presence and purpose of a field, and the syntax of its value may differ
 122 between types of control files.
 123
 124 Field names are not case-sensitive, but it is usual to capitalize the field
 125 names using mixed case as shown below.
 126 Field values are case-sensitive unless the description of the field says
 127 otherwise.
 128
 129 Stanza separators (empty lines) and lines consisting only of
 130 U+0020 B<SPACE> and U+0009 B<TAB>, are not allowed within field
 131 values or between fields.
 132 Empty lines in field values are usually escaped by representing them by a
 133 U+0020 B<SPACE> followed by a dot (U+002E ‘B<.>’).
 134
 135 Lines starting with U+0023 ‘B<#>’, without any preceding whitespace
 136 are comments lines that are only permitted in source package control files
 137 (I<debian/control>) and in B<deb-origin>(5) files.
 138 These comment lines are ignored, even between two continuation lines.
 139 They do not end logical lines.
 140
 141 All control files must be encoded in UTF-8.
 142
 143 =back
 144
 145 =head1 SEE ALSO
 146
 147 B<RFC822>,
 148 B<RFC5322>.