1deb-src-control(5) dpkg suite deb-src-control(5)
2
6 deb-src-control - Debian source packages' master control file format
7
9 debian/control
10
12 Each Debian source package contains the master «debian/control» file,
13 and its deb822(5) format is a superset of the control file shipped in
14 Debian binary packages, see deb-control(5).
15 This file contains at least 2 stanzas, separated by a blank line. The
17 first stanza lists all information about the source package in general,
18 while each following stanza describes exactly one binary package. Each
19 stanza consists of at least one field. A field starts with a
20 fieldname, such as Package or Section (case insensitive), followed by a
21 colon, the body of the field (case sensitive unless stated otherwise)
22 and a newline. Multi-line fields are also allowed, but each
23 supplementary line, without a fieldname, should start with at least one
24 space. The content of the multi-line fields is generally joined to a
25 single line by the tools (except in the case of the Description field,
26 see below). To insert empty lines into a multi-line field, insert a dot
27 after the space. Lines starting with a ‘#’ are treated as comments.
28
30 Source: source-package-name (required)
31 The value of this field is the name of the source package, and
32 should match the name of the source package in the debian/changelog
33 file. A package name must consist only of lowercase letters (a-z),
34 digits (0-9), plus (+) and minus (-) signs, and periods (.).
35 Package names must be at least two characters long and must start
36 with a lowercase alphanumeric character (a-z0-9).
37 Maintainer: fullname-email (recommended)
39 Should be in the format «Joe Bloggs <jbloggs@foo.com>», and
40 references the person who currently maintains the package, as
41 opposed to the author of the software or the original packager.
42 Uploaders: fullname-email
44 Lists all the names and email addresses of co-maintainers of the
45 package, in the same format as the Maintainer field. Multiple co-
46 maintainers should be separated by a comma.
47 Standards-Version: version-string
49 This documents the most recent version of the distribution policy
50 standards this package complies with.
51 Description short-description
53 long-description
54 The format for the source package description is a short brief
55 summary on the first line (after the Description field). The
56 following lines should be used as a longer, more detailed
57 description. Each line of the long description must be preceded by
58 a space, and blank lines in the long description must contain a
59 single ‘.’ following the preceding space.
60 Homepage: url
62 The upstream project home page URL.
63 Bugs: url
65 The url of the bug tracking system for this package. The current
66 used format is bts-type://bts-address, like
67 debbugs://bugs.debian.org. This field is usually not needed.
68 Rules-Requires-Root: no|binary-targets|impl-keywords
70 This field is used to indicate whether the debian/rules file
71 requires (fake)root privileges to run some of its targets, and if
72 so when.
73 no The binary targets will not require (fake)root at all.
75 binary-targets
77 The binary targets must always be run under (fake)root. This
78 value is the default when the field is omitted; adding the
79 field with an explicit binary-targets while not strictly
80 needed, marks it as having been analyzed for this requirement.
81 impl-keywords
83 This is a space-separated list of keywords which define when
84 (fake)root is required.
85 Keywords consist of namespace/cases. The namespace part cannot
87 contain "/" or whitespace. The cases part cannot contain
88 whitespace. Furthermore, both parts must consist entirely of
89 printable ASCII characters.
90 Each tool/package will define a namespace named after itself
92 and provide a number of cases where (fake)root is required.
93 (See "Implementation provided keywords" in
94 rootless-builds.txt).
95 When the field is set to one of the impl-keywords, the builder
97 will expose an interface that is used to run a command under
98 (fake)root. (See "Gain Root API" in rootless-builds.txt.)
99 Testsuite: name-list
101 Testsuite-Triggers: package-list
102 These fields are described in the dsc(5) manual page, as they are
103 generated from information inferred from debian/tests/control or
104 copied literally to the source control file.
105 Vcs-Arch: url
107 Vcs-Bzr: url
108 Vcs-Cvs: url
109 Vcs-Darcs: url
110 Vcs-Git: url
111 Vcs-Hg: url
112 Vcs-Mtn: url
113 Vcs-Svn: url
114 The url of the Version Control System repository used to maintain
115 this package. Currently supported are Arch, Bzr (Bazaar), Cvs,
116 Darcs, Git, Hg (Mercurial), Mtn (Monotone) and Svn (Subversion).
117 Usually this field points to the latest version of the package,
118 such as the main branch or the trunk.
119 Vcs-Browser: url
121 The url of a webinterface to browse the Version Control System
122 repository.
123 Origin: name
125 The name of the distribution this package is originating from. This
126 field is usually not needed.
127 Section: section
129 This is a general field that gives the package a category based on
130 the software that it installs. Some common sections are utils,
131 net, mail, text, x11, etc.
132 Priority: priority
134 Sets the importance of this package in relation to the system as a
135 whole. Common priorities are required, standard, optional, extra,
136 etc.
137 The Section and Priority fields usually have a defined set of
139 accepted values based on the specific distribution policy.
140 Build-Depends: package-list
142 A list of packages that need to be installed and configured to be
143 able to build from source package. These dependencies need to be
144 satisfied when building binary architecture dependent or
145 independent packages and source packages. Including a dependency
146 in this field does not have the exact same effect as including it
147 in both Build-Depends-Arch and Build-Depends-Indep, because the
148 dependency also needs to be satisfied when building the source
149 package.
150 Build-Depends-Arch: package-list
152 Same as Build-Depends, but they are only needed when building the
153 architecture dependent packages. The Build-Depends are also
154 installed in this case. This field is supported since dpkg 1.16.4;
155 in order to build with older dpkg versions, Build-Depends should be
156 used instead.
157 Build-Depends-Indep: package-list
159 Same as Build-Depends, but they are only needed when building the
160 architecture independent packages. The Build-Depends are also
161 installed in this case.
162 Build-Conflicts: package-list
164 A list of packages that should not be installed when the package is
165 built, for example because they interfere with the build system
166 used. Including a dependency in this list has the same effect as
167 including it in both Build-Conflicts-Arch and Build-Conflicts-
168 Indep, with the additional effect of being used for source-only
169 builds.
170 Build-Conflicts-Arch: package-list
172 Same as Build-Conflicts, 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, Build-Conflicts should be
175 used instead.
176 Build-Conflicts-Indep: package-list
178 Same as Build-Conflicts, but only when building the architecture
179 independent packages.
180 The syntax of the Build-Depends, Build-Depends-Arch and Build-Depends-
182 Indep fields is a list of groups of alternative packages. Each group
183 is a list of packages separated by vertical bar (or “pipe”) symbols,
184 ‘|’. The groups are separated by commas ‘,’, and can end with a
185 trailing comma that will be eliminated when generating the fields for
186 deb-control(5) (since dpkg 1.10.14). Commas are to be read as “AND”,
187 and pipes as “OR”, with pipes binding more tightly. Each package name
188 is optionally followed by an architecture qualifier appended after a
189 colon ‘:’, optionally followed by a version number specification in
190 parentheses ‘(’ and ‘)’, an architecture specification in square
191 brackets ‘[’ and ‘]’, and a restriction formula consisting of one or
192 more lists of profile names in angle brackets ‘<’ and ‘>’.
193 The syntax of the Build-Conflicts, Build-Conflicts-Arch and Build-
195 Conflicts-Indep fields is a list of comma-separated package names,
196 where the comma is read as an “AND”, and where the list can end with a
197 trailing comma that will be eliminated when generating the fields for
198 deb-control(5) (since dpkg 1.10.14). Specifying alternative packages
199 using a “pipe” is not supported. Each package name is optionally
200 followed by a version number specification in parentheses, an
201 architecture specification in square brackets, and a restriction
202 formula consisting of one or more lists of profile names in angle
203 brackets.
204 An architecture qualifier name can be a real Debian architecture name
206 (since dpkg 1.16.5), any (since dpkg 1.16.2) or native (since dpkg
207 1.16.5). If omitted, the default for Build-Depends fields is the
208 current host architecture, the default for Build-Conflicts fields is
209 any. A real Debian architecture name will match exactly that
210 architecture for that package name, any will match any architecture for
211 that package name if the package is marked with Multi-Arch: allowed,
212 and native will match the current build architecture if the package is
213 not marked with Multi-Arch: foreign.
214 A version number may start with a ‘>>’, in which case any later version
216 will match, and may specify or omit the Debian packaging revision
217 (separated by a hyphen). Accepted version relationships are ‘>>’ for
218 greater than, ‘<<’ for less than, ‘>=’ for greater than or equal to,
219 ‘<=’ for less than or equal to, and ‘=’ for equal to.
220 An architecture specification consists of one or more architecture
222 names, separated by whitespace. Exclamation marks may be prepended to
223 each of the names, meaning “NOT”.
224 A restriction formula consists of one or more restriction lists,
226 separated by whitespace. Each restriction list is enclosed in angle
227 brackets. Items in the restriction list are build profile names,
228 separated by whitespace and can be prefixed with an exclamation mark,
229 meaning “NOT”. A restriction formula represents a disjunctive normal
230 form expression.
231 Note that dependencies on packages in the build-essential set can be
233 omitted and that declaring build conflicts against them is impossible.
234 A list of these packages is in the build-essential package.
235
237 Note that the Priority, Section and Homepage fields can also be in a
238 binary stanza to override the global value from the source package.
239 Package: binary-package-name (required)
241 This field is used to name the binary package name. The same
242 restrictions as to a source package name apply.
243 Package-Type: deb|udeb|type
245 This field defines the type of the package. udeb is for size-
246 constrained packages used by the debian installer. deb is the
247 default value, it is assumed if the field is absent. More types
248 might be added in the future.
249 Architecture: arch|all|any (required)
251 The architecture specifies on which type of hardware this package
252 runs. For packages that run on all architectures, use the any
253 value. For packages that are architecture independent, such as
254 shell and Perl scripts or documentation, use the all value. To
255 restrict the packages to a certain set of architectures, specify
256 the architecture names, separated by a space. It's also possible to
257 put architecture wildcards in that list (see dpkg-architecture(1)
258 for more information about them).
259 Build-Profiles: restriction-formula
261 This field specifies the conditions for which this binary package
262 does or does not build. To express that condition, the same
263 restriction formula syntax from the Build-Depends field is used
264 (including the angle brackets).
265 If a binary package stanza does not contain this field, then it
267 implicitly means that it builds with all build profiles (including
268 none at all).
269 In other words, if a binary package stanza is annotated with a non-
271 empty Build-Profiles field, then this binary package is generated
272 if and only if the condition expressed by the conjunctive normal
273 form expression evaluates to true.
274 Protected: yes|no
276 Essential: yes|no
277 Build-Essential: yes|no
278 Multi-Arch: same|foreign|allowed|no
279 Tag: tag-list
280 Description: short-description (recommended)
281 These fields are described in the deb-control(5) manual page, as
282 they are copied literally to the control file of the binary
283 package.
284 Depends: package-list
286 Pre-Depends: package-list
287 Recommends: package-list
288 Suggests: package-list
289 Breaks: package-list
290 Enhances: package-list
291 Replaces: package-list
292 Conflicts: package-list
293 Provides: package-list
294 Built-Using: package-list
295 Static-Built-Using: package-list
296 These fields declare relationships between packages. They are
297 discussed in the deb-control(5) manpage. When these fields are
298 found in debian/control they can also end with a trailing comma
299 (since dpkg 1.10.14), have architecture specifications and
300 restriction formulas which will all get reduced when generating the
301 fields for deb-control(5).
302 Subarchitecture: value
304 Kernel-Version: value
305 Installer-Menu-Item: value
306 These fields are used by the debian-installer in udebs and are
307 usually not needed. For more details about them, see
308 <https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt>.
309
311 It is allowed to add additional user-defined fields to the control
312 file. The tools will ignore these fields. If you want the fields to be
313 copied over to the output files, such as the binary packages, you need
314 to use a custom naming scheme: the fields should start with an X,
315 followed by zero or more of the letters SBC and a hyphen.
316 S The field will appear in the source package control file, see
318 dsc(5).
319 B The field will appear in the control file in the binary package,
321 see deb-control(5).
322 C The field will appear in the upload control (.changes) file, see
324 deb-changes(5).
325 Note that the X[SBC]- prefixes are stripped when the fields are copied
327 over to the output files. A field XC-Approved-By will appear as
328 Approved-By in the changes file and will not appear in the binary or
329 source package control files.
330 Take into account that these user-defined fields will be using the
332 global namespace, which might at some point in the future collide with
333 officially recognized fields. To avoid such potential situation you can
334 prefix those fields with Private-, such as XB-Private-New-Field.
335
337 # Comment
338 Source: dpkg
339 Section: admin
340 Priority: required
341 Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
342 # this field is copied to the binary and source packages
343 XBS-Upstream-Release-Status: stable
344 Homepage: https://wiki.debian.org/Teams/Dpkg
345 Vcs-Browser: https://git.dpkg.org/cgit/dpkg/dpkg.git
346 Vcs-Git: https://git.dpkg.org/git/dpkg/dpkg.git
347 Standards-Version: 3.7.3
348 Build-Depends: pkg-config, debhelper (>= 4.1.81),
349 libselinux1-dev (>= 1.28-4) [!linux-any]
350 Package: dpkg-dev
352 Section: utils
353 Priority: optional
354 Architecture: all
355 # this is a custom field in the binary package
356 XB-Mentoring-Contact: Raphael Hertzog <hertzog@debian.org>
357 Depends: dpkg (>= 1.14.6), perl5, perl-modules, cpio (>= 2.4.2-2),
358 bzip2, lzma, patch (>= 2.2-1), make, binutils, libtimedate-perl
359 Recommends: gcc | c-compiler, build-essential
360 Suggests: gnupg, debian-keyring
361 Conflicts: dpkg-cross (<< 2.0.0), devscripts (<< 2.10.26)
362 Replaces: manpages-pl (<= 20051117-1)
363 Description: Debian package development tools
364 This package provides the development tools (including dpkg-source)
365 required to unpack, build and upload Debian source packages.
366 .
367 Most Debian source packages will require additional tools to build;
368 for example, most packages need make and the C compiler gcc.
369
371 /usr/share/doc/dpkg/spec/rootless-builds.txt, deb822(5), deb-
372 control(5), deb-version(7), dpkg-source(1)
3731.21.21 2023-02-25 deb-src-control(5)