1dpkg-buildpackage(1) dpkg suite dpkg-buildpackage(1)
2
6 dpkg-buildpackage - build binary or source packages from sources
7
9 dpkg-buildpackage [option...]
10
12 dpkg-buildpackage is a program that automates the process of building a
13 Debian package. It consists of the following steps:
14 1. It prepares the build environment by setting various environment
16 variables (see ENVIRONMENT), runs the init hook, and calls dpkg-
17 source --before-build (unless -T or --target has been used).
18 2. It checks that the build-dependencies and build-conflicts are
20 satisfied (unless -d or --no-check-builddeps is specified).
21 3. If one or more specific targets have been selected with the -T or
23 --target option, it calls those targets and stops here. Otherwise
24 it runs the preclean hook and calls fakeroot debian/rules clean to
25 clean the build-tree (unless -nc or --no-pre-clean is specified).
26 4. It runs the source hook and calls dpkg-source -b to generate the
28 source package (if a source build has been requested with --build
29 or equivalent options).
30 5. It runs the build hook and calls debian/rules build-target, then
32 runs the binary hook followed by fakeroot debian/rules binary-
33 target (unless a source-only build has been requested with
34 --build=source or equivalent options). Note that build-target and
35 binary-target are either build and binary (default case, or if an
36 any and all build has been requested with --build or equivalent
37 options), or build-arch and binary-arch (if an any and not all
38 build has been requested with --build or equivalent options), or
39 build-indep and binary-indep (if an all and not any build has been
40 requested with --build or equivalent options).
41 6. It runs the buildinfo hook and calls dpkg-genbuildinfo to generate
43 a .buildinfo file. Several dpkg-buildpackage options are forwarded
44 to dpkg-genbuildinfo.
45 7. It runs the changes hook and calls dpkg-genchanges to generate a
47 .changes file. The name of the .changes file will depend on the
48 type of build and will be as specific as necessary but not more;
49 for a build that includes any the name will be source-name_binary-
50 version_arch.changes, or otherwise for a build that includes all
51 the name will be source-name_binary-version_all.changes, or
52 otherwise for a build that includes source the name will be source-
53 name_source-version_source.changes. Many dpkg-buildpackage options
54 are forwarded to dpkg-genchanges.
55 8. It runs the postclean hook and if -tc or --post-clean is specified,
57 it will call fakeroot debian/rules clean again.
58 9. It calls dpkg-source --after-build.
60 10. It runs the check hook and calls a package checker for the .changes
62 file (if a command is specified in DEB_CHECK_COMMAND or with
63 --check-command).
64 11. It runs the sign hook and calls gpg (as long as it is not an
66 UNRELEASED build, or --no-sign is specified) to sign the .dsc file
67 (if any, unless -us or --unsigned-source is specified), the
68 .buildinfo file (unless -ui, --unsigned-buildinfo, -uc or
69 --unsigned-changes is specified) and the .changes file (unless -uc
70 or --unsigned-changes is specified).
71 12. It runs the done hook.
73
75 All long options can be specified both on the command line and in the
76 dpkg-buildpackage system and user configuration files. Each line in
77 the configuration file is either an option (exactly the same as the
78 command line option but without leading hyphens) or a comment (if it
79 starts with a ‘#’).
80 --build=type
82 Specifies the build type from a comma-separated list of components
83 (since dpkg 1.18.5). Passed to dpkg-genchanges.
84 The allowed values are:
86 source
88 Builds the source package.
89 Note: When using this value standalone and if what you want is
91 simply to (re-)build the source package from a clean source
92 tree, using dpkg-source directly is always a better option as
93 it does not require any build dependencies to be installed
94 which are otherwise needed to be able to call the clean target.
95 any Builds the architecture specific binary packages.
97 all Builds the architecture independent binary packages.
99 binary
101 Builds the architecture specific and independent binary
102 packages. This is an alias for any,all.
103 full
105 Builds everything. This is an alias for source,any,all, and
106 the same as the default case when no build option is specified.
107 -g Equivalent to --build=source,all (since dpkg 1.17.11).
109 -G Equivalent to --build=source,any (since dpkg 1.17.11).
111 -b Equivalent to --build=binary or --build=any,all.
113 -B Equivalent to --build=any.
115 -A Equivalent to --build=all.
117 -S Equivalent to --build=source.
119 -F Equivalent to --build=full, --build=source,binary or
121 --build=source,any,all (since dpkg 1.15.8).
122 --target=target[,...]
124 --target target[,...]
125 -T, --rules-target=target[,...]
126 Calls debian/rules target once per target specified, after having
127 setup the build environment (except for calling dpkg-source
128 --before-build), and stops the package build process here (since
129 dpkg 1.15.0, long option since dpkg 1.18.8, multi-target support
130 since dpkg 1.18.16). If --as-root is also given, then the command
131 is executed as root (see --root-command). Note that known targets
132 that are required to be run as root do not need this option (i.e.
133 the clean, binary, binary-arch and binary-indep targets).
134 --as-root
136 Only meaningful together with --target (since dpkg 1.15.0).
137 Requires that the target be run with root rights.
138 -si
140 -sa
141 -sd
142 -vversion
143 -Cchanges-description
144 -m, --release-by=maintainer-address
145 -e, --build-by=maintainer-address
146 Passed unchanged to dpkg-genchanges. See its manual page.
147 -a, --host-arch architecture
149 Specify the Debian architecture we build for (long option since
150 dpkg 1.17.17). The architecture of the machine we build on is
151 determined automatically, and is also the default for the host
152 machine.
153 -t, --host-type gnu-system-type
155 Specify the GNU system type we build for (long option since dpkg
156 1.17.17). It can be used in place of --host-arch or as a
157 complement to override the default GNU system type of the host
158 Debian architecture.
159 --target-arch architecture
161 Specify the Debian architecture the binaries built will build for
162 (since dpkg 1.17.17). The default value is the host machine.
163 --target-type gnu-system-type
165 Specify the GNU system type the binaries built will build for
166 (since dpkg 1.17.17). It can be used in place of --target-arch or
167 as a complement to override the default GNU system type of the
168 target Debian architecture.
169 -P, --build-profiles=profile[,...]
171 Specify the profile(s) we build, as a comma-separated list (since
172 dpkg 1.17.2, long option since dpkg 1.18.8). The default behavior
173 is to build for no specific profile. Also sets them (as a space
174 separated list) as the DEB_BUILD_PROFILES environment variable
175 which allows, for example, debian/rules files to use this
176 information for conditional builds.
177 -j, --jobs[=jobs|auto]
179 Number of jobs allowed to be run simultaneously, number of jobs
180 matching the number of online processors if auto is specified
181 (since dpkg 1.17.10), or unlimited number if jobs is not specified,
182 equivalent to the make(1) option of the same name (since dpkg
183 1.14.7, long option since dpkg 1.18.8). Will add itself to the
184 MAKEFLAGS environment variable, which should cause all subsequent
185 make invocations to inherit the option, thus forcing the parallel
186 setting on the packaging (and possibly the upstream build system if
187 that uses make) regardless of their support for parallel builds,
188 which might cause build failures. Also adds parallel=jobs or
189 parallel to the DEB_BUILD_OPTIONS environment variable which allows
190 debian/rules files to use this information for their own purposes.
191 The -j value will override the parallel=jobs or parallel option in
192 the DEB_BUILD_OPTIONS environment variable. Note that the auto
193 value will get replaced by the actual number of currently active
194 processors, and as such will not get propagated to any child
195 process. If the number of online processors cannot be inferred then
196 the code will fallback to using serial execution (since dpkg
197 1.18.15), although this should only happen on exotic and
198 unsupported systems.
199 -J, --jobs-try[=jobs|auto]
201 This option (since dpkg 1.18.2, long option since dpkg 1.18.8) is
202 equivalent to the -j option except that it does not set the
203 MAKEFLAGS environment variable, and as such it is safer to use with
204 any package including those that are not parallel-build safe.
205 auto is the default behavior (since dpkg 1.18.11). Setting the
207 number of jobs to 1 will restore a serial behavior.
208 -D, --check-builddeps
210 Check build dependencies and conflicts; abort if unsatisfied (long
211 option since dpkg 1.18.8). This is the default behavior.
212 -d, --no-check-builddeps
214 Do not check build dependencies and conflicts (long option since
215 dpkg 1.18.8).
216 --ignore-builtin-builddeps
218 Do not check built-in build dependencies and conflicts (since dpkg
219 1.18.2). These are the distribution specific implicit build
220 dependencies usually required in a build environment, the so called
221 Build-Essential package set.
222 --rules-requires-root
224 Do not honor the Rules-Requires-Root field, falling back to its
225 legacy default value (since dpkg 1.19.1).
226 -nc, --no-pre-clean
228 Do not clean the source tree before building (long option since
229 dpkg 1.18.8). Implies -b if nothing else has been selected among
230 -F, -g, -G, -B, -A or -S. Implies -d with -S (since dpkg 1.18.0).
231 --pre-clean
233 Clean the source tree before building (since dpkg 1.18.8). This is
234 the default behavior.
235 -tc, --post-clean
237 Clean the source tree (using gain-root-command debian/rules clean)
238 after the package has been built (long option since dpkg 1.18.8).
239 --no-post-clean
241 Do not clean the source tree after the package has been built
242 (since dpkg 1.19.1). This is the default behavior.
243 --sanitize-env
245 Sanitize the build environment (since dpkg 1.20.0). This will
246 reset or remove environment variables, umask, and any other process
247 attributes that might otherwise adversely affect the build of
248 packages. Because the official entry point to build packages is
249 debian/rules, packages cannot rely on these settings being in
250 place, and thus should work even when they are not. What to
251 sanitize is vendor specific.
252 -r, --root-command=gain-root-command
254 When dpkg-buildpackage needs to execute part of the build process
255 as root, it prefixes the command it executes with gain-root-command
256 if one has been specified (long option since dpkg 1.18.8).
257 Otherwise, if none has been specified, fakeroot will be used by
258 default, if the command is present. gain-root-command should start
259 with the name of a program on the PATH and will get as arguments
260 the name of the real command to run and the arguments it should
261 take. gain-root-command can include parameters (they must be
262 space-separated) but no shell metacharacters. gain-root-command
263 might typically be fakeroot, sudo, super or really. su is not
264 suitable, since it can only invoke the user's shell with -c instead
265 of passing arguments individually to the command to be run.
266 -R, --rules-file=rules-file
268 Building a Debian package usually involves invoking debian/rules as
269 a command with several standard parameters (since dpkg 1.14.17,
270 long option since dpkg 1.18.8). With this option it's possible to
271 use another program invocation to build the package (it can include
272 space separated parameters). Alternatively it can be used to
273 execute the standard rules file with another make program (for
274 example by using /usr/local/bin/make -f debian/rules as rules-
275 file).
276 --check-command=check-command
278 Command used to check the .changes file itself and any artifact
279 built referenced in the file (since dpkg 1.17.6). The command
280 should take the .changes pathname as an argument. This command will
281 usually be lintian.
282 --check-option=opt
284 Pass option opt to the check-command specified with
285 DEB_CHECK_COMMAND or --check-command (since dpkg 1.17.6). Can be
286 used multiple times.
287 --hook-hook-name=hook-command
289 Set the specified shell code hook-command as the hook hook-name,
290 which will run at the times specified in the run steps (since dpkg
291 1.17.6). The hooks will always be executed even if the following
292 action is not performed (except for the binary hook). All the
293 hooks will run in the unpacked source directory.
294 Note: Hooks can affect the build process, and cause build failures
296 if their commands fail, so watch out for unintended consequences.
297 The current hook-name supported are:
299 init preclean source build binary buildinfo changes postclean check
301 sign done
302 The hook-command supports the following substitution format string,
304 which will get applied to it before execution:
305 %% A single % character.
307 %a A boolean value (0 or 1), representing whether the following
309 action is being performed.
310 %p The source package name.
312 %v The source package version.
314 %s The source package version (without the epoch).
316 %u The upstream version.
318 --buildinfo-file=filename
320 Set the filename for the generated .buildinfo file (since dpkg
321 1.21.0).
322 --buildinfo-option=opt
324 Pass option opt to dpkg-genbuildinfo (since dpkg 1.18.11). Can be
325 used multiple times.
326 -p, --sign-command=sign-command
328 When dpkg-buildpackage needs to execute GPG to sign a source
329 control (.dsc) file or a .changes file it will run sign-command
330 (searching the PATH if necessary) instead of gpg (long option since
331 dpkg 1.18.8). sign-command will get all the arguments that gpg
332 would have gotten. sign-command should not contain spaces or any
333 other shell metacharacters.
334 -k, --sign-key=key-id
336 Specify a key-ID to use when signing packages (long option since
337 dpkg 1.18.8).
338 -us, --unsigned-source
340 Do not sign the source package (long option since dpkg 1.18.8).
341 -ui, --unsigned-buildinfo
343 Do not sign the .buildinfo file (since dpkg 1.18.19).
344 -uc, --unsigned-changes
346 Do not sign the .buildinfo and .changes files (long option since
347 dpkg 1.18.8).
348 --no-sign
350 Do not sign any file, this includes the source package, the
351 .buildinfo file and the .changes file (since dpkg 1.18.20).
352 --force-sign
354 Force the signing of the resulting files (since dpkg 1.17.0),
355 regardless of -us, --unsigned-source, -ui, --unsigned-buildinfo,
356 -uc, --unsigned-changes or other internal heuristics.
357 -sn
359 -ss
360 -sA
361 -sk
362 -su
363 -sr
364 -sK
365 -sU
366 -sR
367 -i, --diff-ignore[=regex]
368 -I, --tar-ignore[=pattern]
369 -z, --compression-level=level
370 -Z, --compression=compressor
371 Passed unchanged to dpkg-source. See its manual page.
372 --source-option=opt
374 Pass option opt to dpkg-source (since dpkg 1.15.6). Can be used
375 multiple times.
376 --changes-file=filename
378 Set the filename for the generated .changes file (since dpkg
379 1.21.0).
380 --changes-option=opt
382 Pass option opt to dpkg-genchanges (since dpkg 1.15.6). Can be
383 used multiple times.
384 --admindir=dir
386 --admindir dir
387 Change the location of the dpkg database (since dpkg 1.14.0). The
388 default location is /var/lib/dpkg.
389 -?, --help
391 Show the usage message and exit.
392 --version
394 Show the version and exit.
395
397 External environment
398 DEB_CHECK_COMMAND
399 If set, it will be used as the command to check the .changes file
400 (since dpkg 1.17.6). Overridden by the --check-command option.
401 DEB_SIGN_KEYID
403 If set, it will be used to sign the .changes and .dsc files (since
404 dpkg 1.17.2). Overridden by the --sign-key option.
405 DEB_BUILD_OPTIONS
407 If set, it will contain a space-separated list of options that
408 might affect the build process in debian/rules, and the behavior of
409 some dpkg commands.
410 With nocheck the DEB_CHECK_COMMAND variable will be ignored. With
412 parallel=N the parallel jobs will be set to N, overridden by the
413 --jobs-try option.
414 DEB_BUILD_PROFILES
416 If set, it will be used as the active build profile(s) for the
417 package being built (since dpkg 1.17.2). It is a space separated
418 list of profile names. Overridden by the -P option.
419 DPKG_COLORS
421 Sets the color mode (since dpkg 1.18.5). The currently accepted
422 values are: auto (default), always and never.
423 DPKG_NLS
425 If set, it will be used to decide whether to activate Native
426 Language Support, also known as internationalization (or i18n)
427 support (since dpkg 1.19.0). The accepted values are: 0 and 1
428 (default).
429 Internal environment
431 Even if dpkg-buildpackage exports some variables, debian/rules should
432 not rely on their presence and should instead use the respective
433 interface to retrieve the needed values, because that file is the main
434 entry point to build packages and running it standalone should be
435 supported.
436 DEB_BUILD_*
438 DEB_HOST_*
439 DEB_TARGET_*
440 dpkg-architecture is called with the -a and -t parameters
441 forwarded. Any variable that is output by its -s option is
442 integrated in the build environment.
443 DEB_RULES_REQUIRES_ROOT
445 This variable is set to the value obtained from the Rules-Requires-
446 Root field or from the command-line. When set, it will be a valid
447 value for the Rules-Requires-Root field. It is used to notify
448 debian/rules whether the rootless-builds.txt specification is
449 supported.
450 DEB_GAIN_ROOT_CMD
452 This variable is set to gain-root-command when the field Rules-
453 Requires-Root is set to a value different to no and binary-targets.
454 SOURCE_DATE_EPOCH
456 This variable is set to the Unix timestamp since the epoch of the
457 latest entry in debian/changelog, if it is not already defined.
458
460 /etc/dpkg/buildpackage.conf
461 System wide configuration file
462 $XDG_CONFIG_HOME/dpkg/buildpackage.conf or
464 $HOME/.config/dpkg/buildpackage.conf
465 User configuration file.
466
468 Compiler flags are no longer exported
469 Between dpkg 1.14.17 and 1.16.1, dpkg-buildpackage exported compiler
470 flags (CFLAGS, CXXFLAGS, FFLAGS, CPPFLAGS and LDFLAGS) with values as
471 returned by dpkg-buildflags. This is no longer the case.
472 Default build targets
474 dpkg-buildpackage is using the build-arch and build-indep targets since
475 dpkg 1.16.2. Those targets are thus mandatory. But to avoid breakages
476 of existing packages, and ease the transition, if the source package
477 does not build both architecture independent and dependent binary
478 packages (since dpkg 1.18.8) it will fallback to use the build target
479 if make -f debian/rules -qn build-target returns 2 as exit code.
480
482 It should be possible to specify spaces and shell metacharacters and
483 initial arguments for gain-root-command and sign-command.
484
486 dpkg-source(1), dpkg-architecture(1), dpkg-buildflags(1), dpkg-
487 genbuildinfo(1), dpkg-genchanges(1), fakeroot(1), lintian(1), gpg(1).
4881.21.8 2022-05-25 dpkg-buildpackage(1)