Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | .\" dpkg manual page - deb-control(5) |
2 | .\" | |
3 | .\" Copyright © 1995 Raul Miller, Ian Jackson, Ian Murdock | |
4 | .\" Copyright © 1999 Ben Collins <bcollins@debian.org> | |
5 | .\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org> | |
6 | .\" Copyright © 2007-2011, 2013-2015 Guillem Jover <guillem@debian.org> | |
7 | .\" Copyright © 2008-2012 Raphaël Hertzog <hertzog@debian.org> | |
8 | .\" | |
9 | .\" This is free software; you can redistribute it and/or modify | |
10 | .\" it under the terms of the GNU General Public License as published by | |
11 | .\" the Free Software Foundation; either version 2 of the License, or | |
12 | .\" (at your option) any later version. | |
13 | .\" | |
14 | .\" This is distributed in the hope that it will be useful, | |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public License | |
20 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
21 | . | |
22 | .TH deb\-control 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite" | |
23 | .nh | |
24 | .SH NAME | |
25 | deb\-control \- Debian binary packages' master control file format | |
26 | . | |
27 | .SH SYNOPSIS | |
28 | control | |
29 | . | |
30 | .SH DESCRIPTION | |
31 | Each Debian binary package contains the master \fIcontrol\fP file, which | |
32 | contains a number of fields. | |
33 | Each field begins with a tag, such as | |
34 | .B Package | |
35 | or | |
36 | .B Version | |
37 | (case insensitive), followed by a colon, and the body of the field. | |
38 | Fields are delimited only by field tags. In other words, field text | |
39 | may be multiple lines in length, but the installation tools will | |
40 | generally join lines when processing the body of the field (except | |
41 | in the case of the | |
42 | .B Description | |
43 | field, see below). | |
44 | . | |
45 | .SH FIELDS | |
46 | .TP | |
47 | .BR Package: " \fIpackage-name\fP (required)" | |
48 | The value of this field determines the package name, and is used to | |
49 | generate file names by most installation tools. | |
50 | .TP | |
51 | .BR Version: " \fIversion-string\fP (required)" | |
52 | Typically, this is the original package's version number in whatever form | |
53 | the program's author uses. It may also include a Debian revision number | |
54 | (for non-native packages). The exact format and sorting algorithm | |
55 | are described in | |
56 | .BR deb\-version (5). | |
57 | .TP | |
58 | .BR Maintainer: " \fIfullname-email\fP (recommended)" | |
59 | Should be in the format “Joe Bloggs <jbloggs@foo.com>”, and is typically | |
60 | the person who created the package, as opposed to the author of the | |
61 | software that was packaged. | |
62 | .TP | |
63 | .BR Description: " \fIshort-description\fP (recommended)" | |
64 | .TQ | |
65 | .BI " " "long-description" | |
66 | .br | |
67 | The format for the package description is a short brief summary on the | |
68 | first line (after the \fBDescription\fP field). The following lines should be | |
69 | used as a longer, more detailed description. Each line of the long description | |
70 | must be preceded by a space, and blank lines in the long description must | |
71 | contain a single ‘\fB.\fP’ following the preceding space. | |
72 | .TP | |
73 | .BI Section: " section" | |
74 | This is a general field that gives the package a category based on the | |
75 | software that it installs. | |
76 | Some common sections are \fButils\fP, \fBnet\fP, \fBmail\fP, \fBtext\fP, | |
77 | \fBx11\fP, etc. | |
78 | .TP | |
79 | .BI Priority: " priority" | |
80 | Sets the importance of this package in relation to the system as a whole. | |
81 | Common priorities are \fBrequired\fP, \fBstandard\fP, \fBoptional\fP, | |
82 | \fBextra\fP, etc. | |
83 | .LP | |
84 | The | |
85 | .B Section | |
86 | and | |
87 | .B Priority | |
88 | fields usually have a defined set of accepted values based on the specific | |
89 | distribution policy. | |
90 | . | |
91 | .TP | |
92 | .BR Installed\-Size: " size" | |
93 | The approximate total size of the package's installed files, in KiB units. | |
94 | . | |
95 | .TP | |
96 | .BR Essential: " \fByes\fP|\fBno\fP" | |
97 | This field is usually only needed when the answer is \fByes\fP. It denotes | |
98 | a package that is required for proper operation of the system. Dpkg | |
99 | or any other installation tool will not allow an | |
100 | .B Essential | |
101 | package to be removed (at least not without using one of the force options). | |
102 | .TP | |
103 | .BR Build\-Essential: " \fByes\fP|\fBno\fP" | |
104 | This field is usually only needed when the answer is \fByes\fP, and is | |
105 | commonly injected by the archive software. | |
106 | It denotes a package that is required when building other packages. | |
107 | .TP | |
108 | .BR Architecture: " \fIarch\fP|\fBall\fP (recommended)" | |
109 | The architecture specifies which type of hardware this package was compiled | |
110 | for. | |
111 | Common architectures are \fBamd64\fP, \fBarmel\fP, \fBi386\fP, \fBpowerpc\fP, | |
112 | etc. | |
113 | Note that the | |
114 | .B all | |
115 | value is meant for packages that are architecture independent. | |
116 | Some examples of this are shell and Perl scripts, and documentation. | |
117 | .TP | |
118 | .BI Origin: " name" | |
119 | The name of the distribution this package is originating from. | |
120 | .TP | |
121 | .BI Bugs: " url" | |
122 | The \fIurl\fP of the bug tracking system for this package. The current | |
123 | used format is \fIbts-type\fP\fB://\fP\fIbts-address\fP, like | |
124 | \fBdebbugs://bugs.debian.org\fP. | |
125 | .TP | |
126 | .BI Homepage: " url" | |
127 | The upstream project home page \fIurl\fP. | |
128 | .TP | |
129 | .BI Tag: " tag-list" | |
130 | List of tags describing the qualities of the package. The description and | |
131 | list of supported tags can be found in the \fBdebtags\fP package. | |
132 | .TP | |
133 | .BR Multi\-Arch: " \fBno\fP|\fBsame\fP|\fBforeign\fP|\fBallowed\fP" | |
134 | This field is used to indicate how this package should behave on a multi-arch | |
135 | installations. | |
136 | .RS | |
137 | .TP | |
138 | .B no | |
139 | This value is the default when the field is omitted, in which case | |
140 | adding the field with an explicit \fBno\fP value is generally not needed. | |
141 | .TP | |
142 | .B same | |
143 | This package is co-installable with itself, but it must not be used to | |
144 | satisfy the dependency of any package of a different architecture from | |
145 | itself. | |
146 | .TP | |
147 | .B foreign | |
148 | This package is not co-installable with itself, but should be allowed to | |
149 | satisfy a non-arch-qualified dependency of a package of a different arch | |
150 | from itself (if a dependency has an explicit arch-qualifier then the | |
151 | value \fBforeign\fP is ignored). | |
152 | .TP | |
153 | .B allowed | |
154 | This allows reverse-dependencies to indicate in their \fBDepends\fP | |
155 | field that they accept this package from a foreign architecture by | |
156 | qualifying the package name with \fB:any\fP, but has no effect otherwise. | |
157 | .RE | |
158 | .TP | |
159 | .BR Source: " \fIsource-name\fP [\fB(\fP\fIsource-version\fP\fB)\fP]" | |
160 | The name of the source package that this binary package came from, if it is | |
161 | different than the name of the package itself. | |
162 | If the source version differs from the binary version, then the | |
163 | \fIsource-name\fP will be followed by a \fIsource-version\fP in parenthesis. | |
164 | This can happen for example on a binary-only non-maintainer upload, or when | |
165 | setting a different binary version via «\fBdpkg\-gencontrol \-v\fP». | |
166 | .TP | |
167 | .BI Subarchitecture: " value" | |
168 | .TQ | |
169 | .BI Kernel\-Version: " value" | |
170 | .TQ | |
171 | .BI Installer\-Menu\-Item: " value" | |
172 | These fields are used by the debian\-installer and are usually not needed. | |
173 | See /usr/share/doc/debian\-installer/devel/modules.txt from the | |
174 | .B debian\-installer | |
175 | package for more details about them. | |
176 | ||
177 | .TP | |
178 | .BI Depends: " package-list" | |
179 | List of packages that are required for this package to provide a | |
180 | non-trivial amount of functionality. The package maintenance software | |
181 | will not allow a package to be installed if the packages listed in its | |
182 | .B Depends | |
183 | field aren't installed (at least not without using the force options). | |
184 | In an installation, the postinst scripts of packages listed in \fBDepends\fP | |
185 | fields are run before those of the packages which depend on them. On the | |
186 | opposite, in a removal, the prerm script of a package is run before | |
187 | those of the packages listed in its \fBDepends\fP field. | |
188 | .TP | |
189 | .BI Pre\-Depends: " package-list" | |
190 | List of packages that must be installed | |
191 | .B and | |
192 | configured before this one can be installed. This is usually used in the | |
193 | case where this package requires another package for running its preinst | |
194 | script. | |
195 | .TP | |
196 | .BI Recommends: " package-list" | |
197 | Lists packages that would be found together with this one in all but | |
198 | unusual installations. The package maintenance software will warn the | |
199 | user if they install a package without those listed in its | |
200 | .B Recommends | |
201 | field. | |
202 | .TP | |
203 | .BI Suggests: " package-list" | |
204 | Lists packages that are related to this one and can perhaps enhance | |
205 | its usefulness, but without which installing this package is perfectly | |
206 | reasonable. | |
207 | .LP | |
208 | The syntax of | |
209 | .BR Depends , | |
210 | .BR Pre\-Depends , | |
211 | .B Recommends | |
212 | and | |
213 | .B Suggests | |
214 | fields is a list of groups of alternative packages. Each group is a list | |
215 | of packages separated by vertical bar (or “pipe”) symbols, | |
216 | ‘\fB|\fP’. | |
217 | The groups are separated by commas. | |
218 | Commas are to be read as “AND”, and pipes as “OR”, with pipes | |
219 | binding more tightly. | |
220 | Each package name is optionally followed by an architecture qualifier | |
221 | appended after a colon ‘\fB:\fP’, optionally followed by a version | |
222 | number specification in parentheses. | |
223 | .LP | |
224 | An architecture qualifier name can be a real Debian architecture name | |
225 | (since dpkg 1.16.5) or \fBany\fP (since dpkg 1.16.2). | |
226 | If omitted, the default is the current binary package architecture. | |
227 | A real Debian architecture name will match exactly that architecture for | |
228 | that package name, \fBany\fP will match any architecture for that package | |
229 | name if the package has been marked as \fBMulti\-Arch: allowed\fP. | |
230 | .LP | |
231 | A version number may start with a ‘\fB>>\fP’, in which case any later | |
232 | version will match, and may specify or omit the Debian packaging revision | |
233 | (separated by a hyphen). | |
234 | Accepted version relationships are ‘\fB>>\fP’ for greater than, | |
235 | ‘\fB<<\fP’ for less than, ‘\fB>=\fP’ for greater than or | |
236 | equal to, ‘\fB<=\fP’ for less than or equal to, and ‘\fB=\fP’ | |
237 | for equal to. | |
238 | .TP | |
239 | .BI Breaks: " package-list" | |
240 | Lists packages that this one breaks, for example by exposing bugs | |
241 | when the named packages rely on this one. The package maintenance | |
242 | software will not allow broken packages to be configured; generally | |
243 | the resolution is to upgrade the packages named in a | |
244 | .B Breaks | |
245 | field. | |
246 | .TP | |
247 | .BI Conflicts: " package-list" | |
248 | Lists packages that conflict with this one, for example by containing | |
249 | files with the same names. The package maintenance software will not | |
250 | allow conflicting packages to be installed at the same time. Two | |
251 | conflicting packages should each include a | |
252 | .B Conflicts | |
253 | line mentioning the other. | |
254 | .TP | |
255 | .BI Replaces: " package-list" | |
256 | List of packages files from which this one replaces. This is used for | |
257 | allowing this package to overwrite the files of another package and | |
258 | is usually used with the | |
259 | .B Conflicts | |
260 | field to force removal of the other package, if this one also has the | |
261 | same files as the conflicted package. | |
262 | .LP | |
263 | The syntax of | |
264 | .BR Breaks , | |
265 | .B Conflicts | |
266 | and | |
267 | .B Replaces | |
268 | is a list of package names, separated by commas (and optional whitespace). | |
269 | In the | |
270 | .B Breaks | |
271 | and | |
272 | .B Conflicts | |
273 | fields, the comma should be read as “OR”. | |
274 | An optional architecture qualifier can also be appended to the package name | |
275 | with the same syntax as above, but the default is \fBany\fP instead of the | |
276 | binary package architecture. | |
277 | An optional version can also be given with the same syntax as above for the | |
278 | .BR Breaks , | |
279 | .B Conflicts | |
280 | and | |
281 | .B Replaces | |
282 | fields. | |
283 | . | |
284 | .TP | |
285 | .BI Provides: " package-list" | |
286 | This is a list of virtual packages that this one provides. | |
287 | Usually this is used in the case of several packages all providing the | |
288 | same service. | |
289 | For example, sendmail and exim can serve as a mail server, so they | |
290 | provide a common package (“mail\-transport\-agent”) on which | |
291 | other packages can depend. | |
292 | This will allow sendmail or exim to serve as a valid option to satisfy | |
293 | the dependency. | |
294 | This prevents the packages that depend on a mail server from having to | |
295 | know the package names for all of them, and using ‘\fB|\fP’ to | |
296 | separate the list. | |
297 | .LP | |
298 | The syntax of | |
299 | .B Provides | |
300 | is a list of package names, separated by commas (and optional whitespace). | |
301 | An optional architecture qualifier can also be appended to the package | |
302 | name with the same syntax as above. | |
303 | If omitted, the default is the current binary package architecture. | |
304 | An optional exact (equal to) version can also be given with the same | |
305 | syntax as above (honored since dpkg 1.17.11). | |
306 | . | |
307 | .TP | |
308 | .BI Built\-Using: " package-list" | |
309 | This field lists extra source packages that were used during the build of this | |
310 | binary package. This is an indication to the archive maintenance software that | |
311 | these extra source packages must be kept whilst this binary package is | |
312 | maintained. | |
313 | This field must be a list of source package names with strict ‘\fB=\fP’ | |
314 | version relationships. Note that the archive maintenance software is likely to | |
315 | refuse to accept an upload which declares a | |
316 | .B Built\-Using | |
317 | relationship which cannot be satisfied within the archive. | |
318 | . | |
319 | .TP | |
320 | .BI Built\-For\-Profiles: " profile-list (obsolete)" | |
321 | This field used to specify a whitespace separated list of build profiles that | |
322 | this binary packages was built with (since dpkg 1.17.2 until 1.18.18). | |
323 | The information previously found in this field can now be found in the | |
324 | \fB.buildinfo\fP file, which supersedes it. | |
325 | . | |
326 | .TP | |
327 | .BI Auto\-Built\-Package: " reason-list" | |
328 | This field specifies a whitespace separated list of reasons why this package | |
329 | was auto-generated. | |
330 | Binary packages marked with this field will not appear in the | |
331 | \fIdebian/control\fP master source control file. | |
332 | The only currently used reason is \fBdebug\-symbols\fP. | |
333 | . | |
334 | .SH EXAMPLE | |
335 | .\" .RS | |
336 | .nf | |
337 | # Comment | |
338 | Package: grep | |
339 | Essential: yes | |
340 | Priority: required | |
341 | Section: base | |
342 | Maintainer: Wichert Akkerman <wakkerma@debian.org> | |
343 | Architecture: sparc | |
344 | Version: 2.4\-1 | |
345 | Pre\-Depends: libc6 (>= 2.0.105) | |
346 | Provides: rgrep | |
347 | Conflicts: rgrep | |
348 | Description: GNU grep, egrep and fgrep. | |
349 | The GNU family of grep utilities may be the "fastest grep in the west". | |
350 | GNU grep is based on a fast lazy-state deterministic matcher (about | |
351 | twice as fast as stock Unix egrep) hybridized with a Boyer-Moore-Gosper | |
352 | search for a fixed string that eliminates impossible text from being | |
353 | considered by the full regexp matcher without necessarily having to | |
354 | look at every character. The result is typically many times faster | |
355 | than Unix grep or egrep. (Regular expressions containing backreferencing | |
356 | will run more slowly, however). | |
357 | .fi | |
358 | .\" .RE | |
359 | . | |
360 | .SH SEE ALSO | |
361 | .BR deb (5), | |
362 | .BR deb\-version (5), | |
363 | .BR debtags (1), | |
364 | .BR dpkg (1), | |
365 | .BR dpkg\-deb (1). |