deb-control(5): fix Multi-Arch description
[users/hertzog/dpkg.git] / man / deb-control.5
1 .\" Author: Raul Miller
2 .\" Includes text from the debian Guidelines by Ian Jackson, Ian Murdock
3 .TH deb\-control 5 "2011-08-14" "Debian Project" "Debian"
4 .SH NAME
5 deb\-control \- Debian packages' master control file format
6 .
7 .SH SYNOPSIS
8 control
9 .
10 .SH DESCRIPTION
11 Each Debian package contains the master `control' file, which contains
12 a number of fields, or comments when the line starts with \fB'#'\fP. Each
13 field begins with a tag, such as
14 .B Package
15 or
16 .B Version
17 (case insensitive), followed by a colon, and the body of the field.
18 Fields are delimited only by field tags. In other words, field text
19 may be multiple lines in length, but the installation tools will
20 generally join lines when processing the body of the field (except
21 in the case of the
22 .B Description
23 field, see below).
24 .
25 .SH REQUIRED FIELDS
26 .TP
27 .BI Package: " package-name"
28 The value of this field determines the package name, and is used to
29 generate file names by most installation tools.
30 .TP
31 .BI Version: " version-string"
32 Typically, this is the original package's version number in whatever form
33 the program's author uses. It may also include a Debian revision number
34 (for non-native packages). The exact format and sorting algorithm
35 are described in
36 .BR deb\-version (5).
37 .TP
38 .BI Maintainer: " fullname-email"
39 Should be in the format `Joe Bloggs <jbloggs@foo.com>', and is typically
40 the person who created the package, as opposed to the author of the
41 software that was packaged.
42 .TP
43 .BI Description: " short-description"
44 .BI " " "long-description"
45 .br
46 The format for the package description is a short brief summary on the
47 first line (after the "Description" field). The following lines should be
48 used as a longer, more detailed description. Each line of the long description
49 must be preceded by a space, and blank lines in the long description must
50 contain a single '.' following the preceding space.
51 .
52 .SH OPTIONAL FIELDS
53 .TP
54 .BI Section: " section"
55 This is a general field that gives the package a category based on the
56 software that it installs. Some common sections are `utils', `net',
57 `mail', `text', `x11' etc.
58 .TP
59 .BI Priority: " priority"
60 Sets the importance of this package in relation to the system as a whole.
61 Common priorities are `required', `standard', `optional', `extra' etc.
62 .LP
63 In Debian, the
64 .B Section
65 and
66 .B Priority
67 fields have a defined set of accepted values based on the Policy Manual.
68 A list of these values can be obtained from the latest version of the
69 .B debian\-policy
70 package.
71 .TP
72 .BR Essential: " \fByes\fP|\fBno\fP"
73 This field is usually only needed when the answer is \fByes\fP. It denotes
74 a package that is required for proper operation of the system. Dpkg
75 or any other installation tool will not allow an
76 .B Essential
77 package to be removed (at least not without using one of the force options).
78 .TP
79 .BR Architecture: " \fIarch\fP|\fBall\fP"
80 The architecture specifies which type of hardware this package was compiled
81 for. Common architectures are `i386', `m68k', `sparc', `alpha', `powerpc'
82 etc. Note that the
83 .B all
84 option is meant for packages that are architecture independent. Some examples
85 of this are shell and Perl scripts, and documentation.
86 .TP
87 .BI Origin: " name"
88 The name of the distribution this package is originating from.
89 .TP
90 .BI Bugs: " url"
91 The \fIurl\fP of the bug tracking system for this package. The current
92 used format is \fIbts-type\fP\fB://\fP\fIbts-address\fP, like
93 \fBdebbugs://bugs.debian.org\fP.
94 .TP
95 .BI Homepage: " url"
96 The upstream project home page \fIurl\fP.
97 .TP
98 .BI Tag: " tag-list"
99 List of tags describing the qualities of the package. The description and
100 list of supported tags can be found in the \fBdebtags\fP package.
101 .TP
102 .BR Multi\-Arch: " \fBsame\fP|\fBforeign\fP|\fBallowed\fP"
103 This field is used to indicate how this package should behave on a multi-arch
104 installations. The value \fBsame\fP means that the package is co-installable
105 with itself, but it must not be used to satisfy the dependency of any package
106 of a different architecture from itself. The value \fBforeign\fP means that
107 the package is not co-installable with itself, but should be allowed to
108 satisfy the dependency of a package of a different arch from itself. The
109 value \fBallowed\fP allows reverse-dependencies to indicate in their
110 Depends field that they accept a package from a foreign architecture, but
111 has no effect otherwise.
112 .TP
113 .BI Source: " source-name"
114 The name of the source package that this binary package came from, if
115 different than the name of the package itself.
116
117 .TP
118 .PD 0
119 .BI Subarchitecture: " value"
120 .TP
121 .PD 0
122 .BI Kernel\-Version: " value"
123 .TP
124 .PD
125 .BI Installer\-Menu\-Item: " value"
126 These fields are used by the debian\-installer and are usually not needed.
127 See /usr/share/doc/debian\-installer/devel/modules.txt from the
128 .B debian\-installer
129 package for more details about them.
130
131 .TP
132 .BI Depends: " package-list"
133 List of packages that are required for this package to provide a
134 non-trivial amount of functionality. The package maintenance software
135 will not allow a package to be installed if the packages listed in its
136 .B Depends
137 field aren't installed (at least not without using the force options).
138 In an installation, the postinst scripts of packages listed in Depends:
139 fields are run before those of the packages which depend on them. On the
140 opposite, in a removal, the prerm script of a package is run before
141 those of the packages listed in its Depends: field.
142 .TP
143 .BI Pre\-Depends: " package-list"
144 List of packages that must be installed
145 .B and
146 configured before this one can be installed. This is usually used in the
147 case where this package requires another package for running its preinst
148 script.
149 .TP
150 .BI Recommends: " package-list"
151 Lists packages that would be found together with this one in all but
152 unusual installations. The package maintenance software will warn the
153 user if they install a package without those listed in its
154 .B Recommends
155 field.
156 .TP
157 .BI Suggests: " package-list"
158 Lists packages that are related to this one and can perhaps enhance
159 its usefulness, but without which installing this package is perfectly
160 reasonable.
161 .LP
162 The syntax of
163 .BR Depends ,
164 .BR Pre\-Depends ,
165 .B Recommends
166 and
167 .B Suggests
168 fields is a list of groups of alternative packages. Each group is a list
169 of packages separated by vertical bar (or `pipe') symbols, `|'. The
170 groups are separated by commas. Commas are to be read as `AND', and pipes
171 as `OR', with pipes binding more tightly. Each package name is
172 optionally followed by a version number specification in parentheses.
173 .LP
174 A version number may start with a `>>', in which case any later version
175 will match, and may specify or omit the Debian packaging revision (separated
176 by a hyphen). Accepted version relationships are ">>" for greater than,
177 "<<" for less than, ">=" for greater than or equal to, "<=" for less than
178 or equal to, and "=" for equal to.
179 .TP
180 .BI Breaks: " package-list"
181 Lists packages that this one breaks, for example by exposing bugs
182 when the named packages rely on this one. The package maintenance
183 software will not allow broken packages to be configured; generally
184 the resolution is to upgrade the packages named in a
185 .B Breaks
186 field.
187 .TP
188 .BI Conflicts: " package-list"
189 Lists packages that conflict with this one, for example by containing
190 files with the same names. The package maintenance software will not
191 allow conflicting packages to be installed at the same time. Two
192 conflicting packages should each include a
193 .B Conflicts
194 line mentioning the other.
195 .TP
196 .BI Replaces: " package-list"
197 List of packages files from which this one replaces. This is used for
198 allowing this package to overwrite the files of another package and
199 is usually used with the
200 .B Conflicts
201 field to force removal of the other package, if this one also has the
202 same files as the conflicted package.
203 .TP
204 .BI Provides: " package-list"
205 This is a list of virtual packages that this one provides. Usually this is
206 used in the case of several packages all providing the same service.
207 For example, sendmail and exim can serve as a mail server, so they
208 provide a common package (`mail\-transport\-agent') on which other packages
209 can depend. This will allow sendmail or exim to serve as a valid option
210 to satisfy the dependency. This prevents the packages that depend on a mail
211 server from having to know the package names for all of them, and using
212 `|' to separate the list.
213 .LP
214 The syntax of
215 .BR Breaks ,
216 .BR Conflicts ,
217 .B Replaces
218 and
219 .B Provides
220 is a list of package names, separated by commas (and optional whitespace).
221 In the
222 .B Breaks
223 and
224 .B Conflicts
225 fields, the comma should be read as `OR'. An optional version can also be
226 given with the same syntax as above for the
227 .BR Breaks ,
228 .B Conflicts
229 and
230 .B Replaces
231 fields.
232 .
233 .TP
234 .BI Built\-Using: " package-list"
235 This field lists extra source packages that were used during the build of this
236 binary package.  This is an indication to the archive maintenance software that
237 these extra source packages must be kept whilst this binary package is
238 maintained.  This field must be a list of source package names with strict (=)
239 version relationships.  Note that the archive maintenance software is likely to
240 refuse to accept an upload which declares a
241 .B Built\-Using
242 relationship which cannot be satisfied within the archive.
243 .
244 .SH EXAMPLE
245 .\" .RS
246 .nf
247 # Comment
248 Package: grep
249 Essential: yes
250 Priority: required
251 Section: base
252 Maintainer: Wichert Akkerman <wakkerma@debian.org>
253 Architecture: sparc
254 Version: 2.4\-1
255 Pre\-Depends: libc6 (>= 2.0.105)
256 Provides: rgrep
257 Conflicts: rgrep
258 Description: GNU grep, egrep and fgrep.
259  The GNU family of grep utilities may be the "fastest grep in the west".
260  GNU grep is based on a fast lazy-state deterministic matcher (about
261  twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper
262  search for a fixed string that eliminates impossible text from being
263  considered by the full regexp matcher without necessarily having to
264  look at every character. The result is typically many times faster
265  than Unix grep or egrep. (Regular expressions containing backreferencing
266  will run more slowly, however).
267 .fi
268 .\" .RE
269 .
270 .SH SEE ALSO
271 .BR deb (5),
272 .BR deb\-version (5),
273 .BR debtags (1),
274 .BR dpkg (1),
275 .BR dpkg\-deb (1).