Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | .\" dpkg manual page - deb-src-control(5) |
2 | .\" | |
3 | .\" Copyright © 2010 Oxan van Leeuwen <oxan@oxanvanleeuwen.nl> | |
4 | .\" Copyright © 2011 Raphaël Hertzog <hertzog@debian.org> | |
5 | .\" Copyright © 2011-2015 Guillem Jover <guillem@debian.org> | |
6 | .\" | |
7 | .\" This is free software; you can redistribute it and/or modify | |
8 | .\" it under the terms of the GNU General Public License as published by | |
9 | .\" the Free Software Foundation; either version 2 of the License, or | |
10 | .\" (at your option) any later version. | |
11 | .\" | |
12 | .\" This is distributed in the hope that it will be useful, | |
13 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | .\" GNU General Public License for more details. | |
16 | .\" | |
17 | .\" You should have received a copy of the GNU General Public License | |
18 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
19 | . | |
20 | .TH deb\-src\-control 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite" | |
21 | .nh | |
22 | .SH NAME | |
23 | deb\-src\-control \- Debian source packages' master control file format | |
24 | . | |
25 | .SH SYNOPSIS | |
26 | debian/control | |
27 | . | |
28 | .SH DESCRIPTION | |
29 | Each Debian source package contains the master «control» file, | |
30 | which contains at least 2 paragraphs, separated by a blank line. | |
31 | The first paragraph lists | |
32 | all information about the source package in general, while each following | |
33 | paragraph describes exactly one binary package. Each paragraph consists of at | |
34 | least one field. A field starts with a fieldname, such as | |
35 | .B Package | |
36 | or | |
37 | .B Section | |
38 | (case insensitive), followed by a colon, the body of the field and a newline. | |
39 | Multi-line fields are also allowed, but each supplementary line, without a | |
40 | fieldname, should start with at least one space. The content of the multi-line | |
41 | fields is generally joined to a single line by the tools (except in the case of | |
42 | the | |
43 | .B Description | |
44 | field, see below). To insert empty lines into a multi-line | |
45 | field, insert a dot after the space. | |
46 | Lines starting with a ‘\fB#\fP’ are treated as comments. | |
47 | . | |
48 | .SH SOURCE FIELDS | |
49 | .TP | |
50 | .BR Source: " \fIsource-package-name\fP (required)" | |
51 | The value of this field is the name of the source package, and should | |
52 | match the name of the source package in the debian/changelog file. A package | |
53 | name must consist only of lower case letters (a-z), digits (0-9), plus (+) and | |
54 | minus (-) signs, and periods (.). Package names must be at least two characters | |
55 | long and must start with an alphanumeric character. | |
56 | ||
57 | .TP | |
58 | .BR Maintainer: " \fIfullname-email\fP (recommended)" | |
59 | Should be in the format «Joe Bloggs <jbloggs@foo.com>», and references the | |
60 | person who currently maintains the package, as opposed to the author of the | |
61 | software or the original packager. | |
62 | ||
63 | .TP | |
64 | .BI Uploaders: " fullname-email" | |
65 | Lists all the names and email addresses of co-maintainers of the package, in | |
66 | the same format as the \fBMaintainer\fP field. | |
67 | Multiple co-maintainers should be separated by a comma. | |
68 | ||
69 | .TP | |
70 | .BI Standards\-Version: " version-string" | |
71 | This documents the most recent version of the distribution policy standards | |
72 | this package complies with. | |
73 | ||
74 | .TP | |
75 | .BI Homepage: " url" | |
76 | The upstream project home page URL. | |
77 | ||
78 | .TP | |
79 | .BI Bugs: " url" | |
80 | The \fIurl\fP of the bug tracking system for this package. The current | |
81 | used format is \fIbts-type\fP\fB://\fP\fIbts-address\fP, like | |
82 | \fBdebbugs://bugs.debian.org\fP. This field is usually not needed. | |
83 | ||
84 | .TP | |
85 | .BI Vcs\-Arch: " url" | |
86 | .TQ | |
87 | .BI Vcs\-Bzr: " url" | |
88 | .TQ | |
89 | .BI Vcs\-Cvs: " url" | |
90 | .TQ | |
91 | .BI Vcs\-Darcs: " url" | |
92 | .TQ | |
93 | .BI Vcs\-Git: " url" | |
94 | .TQ | |
95 | .BI Vcs\-Hg: " url" | |
96 | .TQ | |
97 | .BI Vcs\-Mtn: " url" | |
98 | .TQ | |
99 | .BI Vcs\-Svn: " url" | |
100 | The \fIurl\fP of the Version Control System repository used to maintain this | |
101 | package. Currently supported are \fBArch\fP, \fBBzr\fP (Bazaar), \fBCvs\fP, | |
102 | \fBDarcs\fP, \fBGit\fP, \fBHg\fP (Mercurial), \fBMtn\fP (Monotone) and | |
103 | \fBSvn\fP (Subversion). Usually this field points to the latest version | |
104 | of the package, such as the main branch or the trunk. | |
105 | ||
106 | .TP | |
107 | .BI Vcs\-Browser: " url" | |
108 | The \fIurl\fP of a webinterface to browse the Version Control System | |
109 | repository. | |
110 | ||
111 | .TP | |
112 | .BI Origin: " name" | |
113 | The name of the distribution this package is originating from. This field is | |
114 | usually not needed. | |
115 | ||
116 | .TP | |
117 | .BI Section: " section" | |
118 | This is a general field that gives the package a category based on the | |
119 | software that it installs. | |
120 | Some common sections are \fButils\fP, \fBnet\fP, \fBmail\fP, \fBtext\fP, | |
121 | \fBx11\fP, etc. | |
122 | ||
123 | .TP | |
124 | .BI Priority: " priority" | |
125 | Sets the importance of this package in relation to the system as a whole. | |
126 | Common priorities are \fBrequired\fP, \fBstandard\fP, \fBoptional\fP, | |
127 | \fBextra\fP, etc. | |
128 | ||
129 | The | |
130 | .B Section | |
131 | and | |
132 | .B Priority | |
133 | fields usually have a defined set of accepted values based on the specific | |
134 | distribution policy. | |
135 | ||
136 | .TP | |
137 | .BI Build\-Depends: " package-list" | |
138 | A list of packages that need to be installed and configured to be able | |
139 | to build from source package. | |
140 | These dependencies need to be satisfied when building binary architecture | |
141 | dependent or independent packages and source packages. | |
142 | Including a dependency in this field does not have the exact same effect as | |
143 | including it in both \fBBuild\-Depends\-Arch\fP and \fBBuild\-Depends\-Indep\fP, | |
144 | because the dependency also needs to be satisfied when building the source | |
145 | package. | |
146 | . | |
147 | .TP | |
148 | .BI Build\-Depends\-Arch: " package-list" | |
149 | Same as \fBBuild\-Depends\fP, but they are only needed when building the | |
150 | architecture dependent packages. The \fBBuild\-Depends\fP are also | |
151 | installed in this case. This field is supported since dpkg 1.16.4; in | |
152 | order to build with older dpkg versions, \fBBuild\-Depends\fP | |
153 | should be used instead. | |
154 | ||
155 | .TP | |
156 | .BI Build\-Depends\-Indep: " package-list" | |
157 | Same as \fBBuild\-Depends\fP, but they are only needed when building the | |
158 | architecture independent packages. The \fBBuild\-Depends\fP are also | |
159 | installed in this case. | |
160 | ||
161 | .TP | |
162 | .BI Build\-Conflicts: " package-list" | |
163 | A list of packages that should not be installed when the package is | |
164 | built, for example because they interfere with the build system used. | |
165 | Including a dependency in this list has the same effect as including | |
166 | it in both \fBBuild\-Conflicts\-Arch\fP and | |
167 | \fBBuild\-Conflicts\-Indep\fP, with the additional effect of being | |
168 | used for source-only builds. | |
169 | ||
170 | .TP | |
171 | .BI Build\-Conflicts\-Arch: " package-list" | |
172 | Same as \fBBuild\-Conflicts\fP, but only when building the architecture | |
173 | dependent packages. This field is supported since dpkg 1.16.4; in | |
174 | order to build with older dpkg versions, \fBBuild\-Conflicts\fP should | |
175 | be used instead. | |
176 | ||
177 | .TP | |
178 | .BI Build\-Conflicts\-Indep: " package-list" | |
179 | Same as \fBBuild\-Conflicts\fP, but only when building the architecture | |
180 | independent packages. | |
181 | ||
182 | .PP | |
183 | The syntax of the | |
184 | .BR Build\-Depends , | |
185 | .B Build\-Depends\-Arch | |
186 | and | |
187 | .B Build\-Depends\-Indep | |
188 | fields is a list of groups of alternative packages. | |
189 | Each group is a list of packages separated by vertical bar (or “pipe”) | |
190 | symbols, ‘\fB|\fP’. | |
191 | The groups are separated by commas. | |
192 | Commas are to be read as “AND”, and pipes as “OR”, with pipes | |
193 | binding more tightly. | |
194 | Each package name is optionally followed by an architecture qualifier | |
195 | appended after a colon ‘\fB:\fP’, | |
196 | optionally followed by a version number specification in parentheses, an | |
197 | architecture specification in square brackets, and a restriction formula | |
198 | consisting of one or more lists of profile names in angle brackets. | |
199 | ||
200 | The syntax of the | |
201 | .BR Build\-Conflicts , | |
202 | .B Build\-Conflicts\-Arch | |
203 | and | |
204 | .B Build\-Conflicts\-Indep | |
205 | fields is a list of comma-separated package names, where the comma is read | |
206 | as an “AND”. | |
207 | Specifying alternative packages using a “pipe” is not supported. | |
208 | Each package name is optionally followed by a version number specification in | |
209 | parentheses, an architecture specification in square brackets, and a | |
210 | restriction formula consisting of one or more lists of profile names in | |
211 | angle brackets. | |
212 | ||
213 | An architecture qualifier name can be a real Debian architecture name | |
214 | (since dpkg 1.16.5), \fBany\fP (since dpkg 1.16.2) or \fBnative\fP | |
215 | (since dpkg 1.16.5). | |
216 | If omitted, the default for \fBBuild\-Depends\fP fields is the current host | |
217 | architecture, the default for \fBBuild\-Conflicts\fP fields is \fBany\fP. | |
218 | A real Debian architecture name will match exactly that architecture for | |
219 | that package name, \fBany\fP will match any architecture for that package | |
220 | name if the package is marked with \fBMulti\-Arch: allowed\fP, and | |
221 | \fBnative\fP will match the current build architecture if the package | |
222 | is not marked with \fBMulti\-Arch: foreign\fP. | |
223 | ||
224 | A version number may start with a ‘\fB>>\fP’, in which case any | |
225 | later version will match, and may specify or omit the Debian packaging | |
226 | revision (separated by a hyphen). | |
227 | Accepted version relationships are ‘\fB>>\fP’ for greater than, | |
228 | ‘\fB<<\fP’ for less than, ‘\fB>=\fP’ for greater than or | |
229 | equal to, ‘\fB<=\fP’ for less than or equal to, and ‘\fB=\fP’ | |
230 | for equal to. | |
231 | ||
232 | An architecture specification consists of one or more architecture names, | |
233 | separated by whitespace. Exclamation marks may be prepended to each of the | |
234 | names, meaning “NOT”. | |
235 | ||
236 | A restriction formula consists of one or more restriction lists, separated | |
237 | by whitespace. Each restriction list is enclosed in angle brackets. Items | |
238 | in the restriction list are build profile names, separated by whitespace | |
239 | and can be prefixed with an exclamation mark, meaning “NOT”. | |
240 | A restriction formula represents a disjunctive normal form expression. | |
241 | ||
242 | Note that dependencies on packages in the | |
243 | .B build\-essential | |
244 | set can be omitted and that declaring build conflicts against them is | |
245 | impossible. A list of these packages is in the build\-essential package. | |
246 | ||
247 | ||
248 | .SH BINARY FIELDS | |
249 | ||
250 | .LP | |
251 | Note that the | |
252 | .BR Priority ", " Section | |
253 | and | |
254 | .B Homepage | |
255 | fields can also be in a binary paragraph to override the global value from the | |
256 | source package. | |
257 | ||
258 | .TP | |
259 | .BR Package: " \fIbinary-package-name\fP (required)" | |
260 | This field is used to name the binary package name. The same restrictions as | |
261 | to a source package name apply. | |
262 | ||
263 | .TP | |
264 | .BR Architecture: " \fIarch\fP|\fBall\fP|\fBany\fP (required)" | |
265 | The architecture specifies on which type of hardware this package runs. For | |
266 | packages that run on all architectures, use the | |
267 | .B any | |
268 | value. For packages that are architecture independent, such as shell and Perl | |
269 | scripts or documentation, use the | |
270 | .B all | |
271 | value. To restrict the packages to a certain set of architectures, specify the | |
272 | architecture names, separated by a space. It's also possible to put | |
273 | architecture wildcards in that list (see | |
274 | .BR dpkg\-architecture (1) | |
275 | for more information about them). | |
276 | ||
277 | .TP | |
278 | .BR Build\-Profiles: " \fIrestriction-formula\fP" | |
279 | This field specifies the conditions for which this binary package does or | |
280 | does not build. | |
281 | To express that condition, the same restriction formula syntax from the | |
282 | \fBBuild\-Depends\fP field is used. | |
283 | ||
284 | If a binary package paragraph does not contain this field, then it implicitly | |
285 | means that it builds with all build profiles (including none at all). | |
286 | ||
287 | In other words, if a binary package paragraph is annotated with a non-empty | |
288 | \fBBuild\-Profiles\fP field, then this binary package is generated if and | |
289 | only if the condition expressed by the conjunctive normal form expression | |
290 | evaluates to true. | |
291 | ||
292 | .TP | |
293 | .BR Package\-Type: " \fBdeb\fP|\fBudeb\fP" | |
294 | This field defines the type of the package. | |
295 | \fBudeb\fP is for size-constrained packages used by the debian installer. | |
296 | \fBdeb\fP is the default value, it is assumed if the field is absent. | |
297 | More types might be added in the future. | |
298 | ||
299 | .TP | |
300 | .BI Subarchitecture: " value" | |
301 | .TQ | |
302 | .BI Kernel\-Version: " value" | |
303 | .TQ | |
304 | .BI Installer\-Menu\-Item: " value" | |
305 | These fields are used by the debian\-installer and are usually not needed. | |
306 | See /usr/share/doc/debian\-installer/devel/modules.txt from the | |
307 | .B debian\-installer | |
308 | package for more details about them. | |
309 | ||
310 | .TP | |
311 | .BR Essential: " \fByes\fP|\fBno\fP" | |
312 | .TQ | |
313 | .BR Build\-Essential: " \fByes\fP|\fBno\fP" | |
314 | .TQ | |
315 | .BR Multi\-Arch: " \fBsame\fP|\fBforeign\fP|\fBallowed\fP|\fBno\fP" | |
316 | .TQ | |
317 | .BI Tag: " tag-list" | |
318 | .TQ | |
319 | .BR Description: " \fIshort-description\fP (recommended)" | |
320 | These fields are described in the | |
321 | .BR deb\-control (5) | |
322 | manual page, as they are copied literally to the control file of the binary | |
323 | package. | |
324 | ||
325 | .TP | |
326 | .BI Depends: " package-list" | |
327 | .TQ | |
328 | .BI Pre\-Depends: " package-list" | |
329 | .TQ | |
330 | .BI Recommends: " package-list" | |
331 | .TQ | |
332 | .BI Suggests: " package-list" | |
333 | .TQ | |
334 | .BI Breaks: " package-list" | |
335 | .TQ | |
336 | .BI Enhances: " package-list" | |
337 | .TQ | |
338 | .BI Replaces: " package-list" | |
339 | .TQ | |
340 | .BI Conflicts: " package-list" | |
341 | .TQ | |
342 | .BI Provides: " package-list" | |
343 | .TQ | |
344 | .BI Built\-Using: " package-list" | |
345 | These fields declare relationships between packages. They are discussed in | |
346 | the | |
347 | .BR deb\-control (5) | |
348 | manpage. | |
349 | ||
350 | .SH USER-DEFINED FIELDS | |
351 | It is allowed to add additional user-defined fields to the control file. The | |
352 | tools will ignore these fields. If you want the fields to be copied over to | |
353 | the output files, such as the binary packages, you need to use a custom naming | |
354 | scheme: the fields should start with an \fBX\fP, followed by zero or more of | |
355 | the letters \fBBCS\fP and a hyphen. | |
356 | ||
357 | .TP | |
358 | .B B | |
359 | The field will appear in the control file in the binary package, see | |
360 | \fBdeb\-control\fP(5). | |
361 | .TP | |
362 | .B S | |
363 | The field will appear in the source package control file, see \fBdsc\fP(5). | |
364 | .TP | |
365 | .B C | |
366 | The field will appear in the upload control (.changes) file, see | |
367 | \fBdeb\-changes\fP(5). | |
368 | ||
369 | .P | |
370 | Note that the \fBX\fP[\fBBCS\fP]\fB\-\fP prefixes are stripped when the | |
371 | fields are copied over to the output files. A field \fBXC\-Approved\-By\fP | |
372 | will appear as \fBApproved\-By\fP in the changes file and will not appear | |
373 | in the binary or source package control files. | |
374 | ||
375 | Take into account that these user-defined fields will be using the global | |
376 | namespace, which might at some point in the future collide with officially | |
377 | recognized fields. To avoid such potential situation you can prefix those | |
378 | fields with \fBPrivate\-\fP, such as \fBXB\-Private\-New\-Field\fP. | |
379 | ||
380 | .SH EXAMPLE | |
381 | .\" .RS | |
382 | .nf | |
383 | # Comment | |
384 | Source: dpkg | |
385 | Section: admin | |
386 | Priority: required | |
387 | Maintainer: Dpkg Developers <debian\-dpkg@lists.debian.org> | |
388 | # this field is copied to the binary and source packages | |
389 | XBS\-Upstream\-Release\-Status: stable | |
390 | Homepage: https://wiki.debian.org/Teams/Dpkg | |
391 | Vcs\-Browser: https://git.dpkg.org/cgit/dpkg/dpkg.git | |
392 | Vcs\-Git: https://git.dpkg.org/git/dpkg/dpkg.git | |
393 | Standards\-Version: 3.7.3 | |
394 | Build\-Depends: pkg\-config, debhelper (>= 4.1.81), | |
395 | libselinux1\-dev (>= 1.28\-4) [!linux\-any] | |
396 | ||
397 | Package: dpkg\-dev | |
398 | Section: utils | |
399 | Priority: optional | |
400 | Architecture: all | |
401 | # this is a custom field in the binary package | |
402 | XB\-Mentoring\-Contact: Raphael Hertzog <hertzog@debian.org> | |
403 | Depends: dpkg (>= 1.14.6), perl5, perl\-modules, cpio (>= 2.4.2\-2), | |
404 | bzip2, lzma, patch (>= 2.2\-1), make, binutils, libtimedate\-perl | |
405 | Recommends: gcc | c\-compiler, build\-essential | |
406 | Suggests: gnupg, debian\-keyring | |
407 | Conflicts: dpkg\-cross (<< 2.0.0), devscripts (<< 2.10.26) | |
408 | Replaces: manpages\-pl (<= 20051117\-1) | |
409 | Description: Debian package development tools | |
410 | This package provides the development tools (including dpkg\-source) | |
411 | required to unpack, build and upload Debian source packages. | |
412 | . | |
413 | Most Debian source packages will require additional tools to build; | |
414 | for example, most packages need make and the C compiler gcc. | |
415 | .fi | |
416 | .\" .RE | |
417 | ||
418 | ||
419 | .SH SEE ALSO | |
420 | .BR deb\-control (5), | |
421 | .BR deb\-version (5), | |
422 | .BR dpkg\-source (1) |