man/dpkg-buildpackage.pod

   1 # dpkg manual page - dpkg-buildpackage(1)
   2 #
   3 # Copyright © 1995-1996 Ian Jackson
   4 # Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
   5 # Copyright © 2007-2008 Frank Lichtenheld <djpig@debian.org>
   6 # Copyright © 2008-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 =encoding utf8
  23
  24 =head1 NAME
  25
  26 dpkg-buildpackage - build binary or source packages from sources
  27
  28 =head1 SYNOPSIS
  29
  30 B<dpkg-buildpackage>
  31 [I<option>...]
  32
  33 =head1 DESCRIPTION
  34
  35 B<dpkg-buildpackage>
  36 is a program that automates the process of building a Debian package.
  37 It
  38 consists of the following steps:
  39
  40 =over
  41
  42 =item B<1.>
  43
  44 It runs the B<preinit> hook before reading any source file.
  45 It prepares the build environment by setting various environment
  46 variables (see B<ENVIRONMENT>), runs the B<init> hook, and calls
  47 B<dpkg-source --before-build> (unless B<-T> or B<--target>
  48 has been used).
  49
  50 =item B<2.>
  51
  52 It checks that the build-dependencies and build-conflicts
  53 are satisfied (unless B<-d> or B<--no-check-builddeps> is specified).
  54
  55 =item B<3.>
  56
  57 If one or more specific targets have been selected with the B<-T> or
  58 B<--target> option, it calls those targets and stops here.
  59 Otherwise it
  60 runs the B<preclean> hook and calls B<fakeroot debian/rules clean> to
  61 clean the build-tree (unless B<-nc> or B<--no-pre-clean>
  62 is specified).
  63
  64 =item B<4.>
  65
  66 It runs the B<source> hook and calls B<dpkg-source -b> to generate
  67 the source package (if a B<source> build has been requested with
  68 B<--build> or equivalent options).
  69
  70 =item B<5.>
  71
  72 It runs the B<build> hook and calls B<debian/rules> I<build-target>,
  73 then runs the B<binary> hook followed by B<fakeroot debian/rules>
  74 I<binary-target> (unless a source-only build has been requested with
  75 B<--build=source> or equivalent options).
  76 Note that I<build-target> and I<binary-target> are either B<build>
  77 and B<binary> (default case, or if an B<any> and B<all> build
  78 has been requested with B<--build> or equivalent options), or
  79 B<build-arch> and B<binary-arch> (if an B<any> and not B<all>
  80 build has been requested with B<--build> or equivalent options), or
  81 B<build-indep> and B<binary-indep> (if an B<all> and not B<any>
  82 build has been requested with B<--build> or equivalent options).
  83
  84 =item B<6.>
  85
  86 It runs the B<buildinfo>
  87 hook and calls B<dpkg-genbuildinfo> to generate a B<.buildinfo> file.
  88 Several B<dpkg-buildpackage> options are forwarded to
  89 B<dpkg-genbuildinfo>.
  90
  91 =item B<7.>
  92
  93 It runs the B<changes> hook and calls B<dpkg-genchanges> to
  94 generate a B<.changes> file.
  95 The name of the B<.changes> file will depend on the type of build and
  96 will be as specific as necessary but not more; the name will be:
  97
  98 =over
  99
 100 =item I<source-name>B<_>I<binary-version>B<_>I<arch>B<.changes>
 101
 102 for a build that includes B<any>
 103
 104 =item I<source-name>B<_>I<binary-version>B<_>B<all.changes>
 105
 106 otherwise for a build that includes B<all>
 107
 108 =item I<source-name>B<_>I<source-version>B<_>B<source.changes>.
 109
 110 otherwise for a build that includes B<source>
 111
 112 =back
 113
 114 Many B<dpkg-buildpackage> options are forwarded to
 115 B<dpkg-genchanges>.
 116
 117 =item B<8.>
 118
 119 It runs the B<postclean> hook and if B<-tc> or B<--post-clean>
 120 is specified, it will call B<fakeroot debian/rules clean> again.
 121
 122 =item B<9.>
 123
 124 It calls B<dpkg-source --after-build>.
 125
 126 =item B<10.>
 127
 128 It runs the B<check> hook and calls a package checker for the
 129 B<.changes> file (if a command is specified in B<DEB_CHECK_COMMAND> or
 130 with B<--check-command>).
 131
 132 =item B<11.>
 133
 134 It runs the B<sign> hook and signs using the OpenPGP backend (as long as it
 135 is not an UNRELEASED build, or B<--no-sign> is specified) to sign the
 136 B<.dsc> file (if any, unless
 137 B<-us> or B<--unsigned-source> is specified), the B<.buildinfo>
 138 file (unless B<-ui>, B<--unsigned-buildinfo>,
 139 B<-uc> or B<--unsigned-changes> is specified) and
 140 the B<.changes> file (unless B<-uc> or B<--unsigned-changes>
 141 is specified).
 142
 143 =item B<12.>
 144
 145 It runs the B<done> hook.
 146
 147 =back
 148
 149 =head1 OPTIONS
 150
 151 All long options can be specified both on the command line and in the
 152 B<dpkg-buildpackage> system and user configuration files.
 153 Each line in the configuration file is either an option (exactly the same
 154 as the command line option but without leading hyphens) or a comment (if
 155 it starts with a ‘B<#>’).
 156
 157 =over
 158
 159 =item B<--build=>I<type>
 160
 161 Specifies the build I<type> from a comma-separated list of components
 162 (since dpkg 1.18.5).
 163 All the specified components get combined to select the single build type
 164 to use, which implies a single build run with a single F<.changes> file
 165 generated.
 166 Passed to B<dpkg-genchanges>.
 167
 168 The allowed values are:
 169
 170 =over
 171
 172 =item B<source>
 173
 174 Builds the source package.
 175
 176 B<Note>: When using this value standalone and if what you want is simply to
 177 (re-)build the source package from a clean source tree, using
 178 B<dpkg-source> directly is always a better option as it does not
 179 require any build dependencies to be installed which are otherwise
 180 needed to be able to call the B<clean> target.
 181
 182 =item B<any>
 183
 184 Builds the architecture specific binary packages.
 185
 186 =item B<all>
 187
 188 Builds the architecture independent binary packages.
 189
 190 =item B<binary>
 191
 192 Builds the architecture specific and independent binary packages.
 193 This is an alias for B<any,all>.
 194
 195 =item B<full>
 196
 197 Builds everything.
 198 This is an alias for B<source,any,all>, and the same as the default
 199 case when no build option is specified.
 200
 201 =back
 202
 203 =item B<-g>
 204
 205 Equivalent to B<--build=source,all> (since dpkg 1.17.11).
 206
 207 =item B<-G>
 208
 209 Equivalent to B<--build=source,any> (since dpkg 1.17.11).
 210
 211 =item B<-b>
 212
 213 Equivalent to B<--build=binary> or B<--build=any,all>.
 214
 215 =item B<-B>
 216
 217 Equivalent to B<--build=any>.
 218
 219 =item B<-A>
 220
 221 Equivalent to B<--build=all>.
 222
 223 =item B<-S>
 224
 225 Equivalent to B<--build=source>.
 226
 227 =item B<-F>
 228
 229 Equivalent to B<--build=full>, B<--build=source,binary> or
 230 B<--build=source,any,all> (since dpkg 1.15.8).
 231
 232 =item B<--target=>I<target>[,...]
 233
 234 =item B<--target> I<target>[,...]
 235
 236 =item B<-T>, B<--rules-target=>I<target>[,...]
 237
 238 Calls B<debian/rules> I<target> once per target specified, after
 239 having setup the build environment (except for calling
 240 B<dpkg-source --before-build>), and stops the package build process
 241 here (since dpkg 1.15.0, long option since dpkg 1.18.8, multi-target
 242 support since dpkg 1.18.16).
 243 If B<--as-root> is also given, then the command is executed
 244 as root (see B<--root-command>).
 245 Note that known targets that are required to
 246 be run as root do not need this option (i.e. the B<clean>, B<binary>,
 247 B<binary-arch> and B<binary-indep> targets).
 248
 249 =item B<--as-root>
 250
 251 Only meaningful together with B<--target> (since dpkg 1.15.0).
 252 Requires that the target be run with root rights.
 253
 254 =item B<-si>
 255
 256 =item B<-sa>
 257
 258 =item B<-sd>
 259
 260 =item B<-v>I<version>
 261
 262 =item B<-C>I<changes-description>
 263
 264 =item B<-m>I<maintainer-address>
 265
 266 =item B<-e>I<maintainer-address>
 267
 268 Passed unchanged to B<dpkg-genchanges>.
 269 See its manual page.
 270
 271 =item B<--build-by=>I<maintainer-address>
 272
 273 =item B<--source-by=>I<maintainer-address> (since dpkg 1.21.10)
 274
 275 Pass as B<-m> to B<dpkg-genchanges>.
 276 See its manual page.
 277
 278 =item B<--release-by=>I<maintainer-address>
 279
 280 =item B<--changed-by=>I<maintainer-address> (since dpkg 1.21.10)
 281
 282 Pass as B<-e> to B<dpkg-genchanges>.
 283 See its manual page.
 284
 285 =item B<-a>, B<--host-arch> I<architecture>
 286
 287 Specify the Debian architecture we build for (long option since dpkg 1.17.17).
 288 The architecture of the
 289 machine we build on is determined automatically, and is also the default
 290 for the host machine.
 291
 292 =item B<-t>, B<--host-type> I<gnu-system-type>
 293
 294 Specify the GNU system type we build for (long option since dpkg 1.17.17).
 295 It can be used in place
 296 of B<--host-arch> or as a complement to override the default GNU system type
 297 of the host Debian architecture.
 298
 299 =item B<--target-arch> I<architecture>
 300
 301 Specify the Debian architecture the binaries built will build for
 302 (since dpkg 1.17.17).
 303 The default value is the host machine.
 304
 305 =item B<--target-type> I<gnu-system-type>
 306
 307 Specify the GNU system type the binaries built will build for
 308 (since dpkg 1.17.17).
 309 It can be
 310 used in place of B<--target-arch> or as a complement to override the
 311 default GNU system type of the target Debian architecture.
 312
 313 =item B<-P>, B<--build-profiles=>I<profile>[B<,>...]
 314
 315 Specify the profile(s) we build, as a comma-separated list (since dpkg 1.17.2,
 316 long option since dpkg 1.18.8).
 317 The default
 318 behavior is to build for no specific profile.
 319 Also sets them (as a space
 320 separated list) as the B<DEB_BUILD_PROFILES> environment variable which
 321 allows, for example, B<debian/rules> files to use this information for
 322 conditional builds.
 323
 324 =item B<-j>, B<--jobs>[=I<jobs>|B<auto>]
 325
 326 Specifies the number of jobs allowed to be run simultaneously
 327 (since dpkg 1.14.7, long option since dpkg 1.18.8).
 328 The number of jobs matching the number of online processors if B<auto> is
 329 specified (since dpkg 1.17.10), or unlimited number if I<jobs> is not
 330 specified.
 331 The default behavior is B<auto> (since dpkg 1.18.11) in non-forced mode
 332 (since dpkg 1.21.10), and as such it is always safer to use with any
 333 package including those that are not parallel-build safe.
 334 Setting the number of jobs to B<1> will restore serial execution.
 335
 336 Will add B<parallel=>I<jobs> or B<parallel> to the B<DEB_BUILD_OPTIONS>
 337 environment variable which allows debian/rules files to opt-in to use this
 338 information for their own purposes.
 339 The I<jobs> value will override the B<parallel=>I<jobs> or
 340 B<parallel> option in the B<DEB_BUILD_OPTIONS> environment variable.
 341 Note that the B<auto> value will get replaced by the actual number of
 342 currently active processors, and as such will not get propagated to any
 343 child process.
 344 If the number of online processors cannot be inferred then
 345 the code will fallback to using serial execution (since dpkg 1.18.15),
 346 although this should only happen on exotic and unsupported systems.
 347
 348 =item B<-J>, B<--jobs-try>[=I<jobs>|B<auto>]
 349
 350 This option (since dpkg 1.18.2, long option since dpkg 1.18.8) is equivalent
 351 to the B<-j> above.
 352
 353 Since the behavior for B<-j> changed in dpkg 1.21.10 to the opt-in mode,
 354 you can use this option instead if you need to guarantee semantics across
 355 dpkg release series.
 356
 357 =item B<--jobs-force>[=I<jobs>|B<auto>]
 358
 359 This option (since dpkg 1.21.10) is equivalent to the B<--jobs> option
 360 except that it will enable forced parallel mode, by adding the B<make> B<-j>
 361 option with the computed number of parallel jobs to the B<MAKEFLAGS>
 362 environment variable.
 363
 364 This should cause all subsequent make invocations to inherit the option,
 365 thus forcing the parallel setting on the packaging (and possibly the
 366 upstream build system if that uses L<make(1)>) regardless of their support
 367 for parallel builds, which might cause build failures.
 368
 369 B<Note>: Any Makefile that is not parallel-safe should be considered to be buggy.
 370 These should either be made parallel-safe, or marked as not being safe with
 371 the L<make(1)> B<.NOTPARALLEL> target.
 372
 373 =item B<-D>, B<--check-builddeps>
 374
 375 Check build dependencies and conflicts; abort if unsatisfied (long option
 376 since dpkg 1.18.8).
 377 This is the default behavior.
 378
 379 =item B<-d>, B<--no-check-builddeps>
 380
 381 Do not check build dependencies and conflicts (long option since dpkg 1.18.8).
 382
 383 =item B<--ignore-builtin-builddeps>
 384
 385 Do not check built-in build dependencies and conflicts (since dpkg 1.18.2).
 386 These are the distribution specific implicit build dependencies usually
 387 required in a build environment, the so called Build-Essential package set.
 388
 389 =item B<--rules-requires-root>
 390
 391 Do not honor the B<Rules-Requires-Root> field, falling back to its
 392 legacy default value (since dpkg 1.19.1).
 393
 394 =item B<-nc>, B<--no-pre-clean>
 395
 396 Do not clean the source tree before building (long option since dpkg 1.18.8).
 397 Implies B<-b> if nothing else has been selected among B<-F>,
 398 B<-g>, B<-G>, B<-B>, B<-A> or B<-S>.
 399 Implies B<-d> with B<-S> (since dpkg 1.18.0).
 400
 401 =item B<--pre-clean>
 402
 403 Clean the source tree before building (since dpkg 1.18.8).
 404 This is the default behavior.
 405
 406 =item B<-tc>, B<--post-clean>
 407
 408 Clean the source tree (using
 409 I<gain-root-command>
 410 B<debian/rules clean>)
 411 after the package has been built (long option since dpkg 1.18.8).
 412
 413 =item B<--no-post-clean>
 414
 415 Do not clean the source tree after the package has been built
 416 (since dpkg 1.19.1).
 417 This is the default behavior.
 418
 419 =item B<--sanitize-env>
 420
 421 Sanitize the build environment (since dpkg 1.20.0).
 422 This will reset or remove environment variables, umask, and any other process
 423 attributes that might otherwise adversely affect the build of packages.
 424 Because the official entry point to build packages is B<debian/rules>,
 425 packages cannot rely on these settings being in place, and thus should work
 426 even when they are not.
 427 What to sanitize is vendor specific.
 428
 429 =item B<-r>, B<--root-command=>I<gain-root-command>
 430
 431 When
 432 B<dpkg-buildpackage>
 433 needs to execute part of the build process as root, it prefixes the
 434 command it executes with
 435 I<gain-root-command>
 436 if one has been specified (long option since dpkg 1.18.8).
 437 Otherwise, if none has been specified,
 438 B<fakeroot> will be used by default, if the command is present.
 439 I<gain-root-command>
 440 should start with the name of a program on the
 441 B<PATH>
 442 and will get as arguments the name of the real command to run and the
 443 arguments it should take.
 444 I<gain-root-command>
 445 can include parameters (they must be space-separated) but no shell
 446 metacharacters.
 447 I<gain-root-command>
 448 might typically be
 449 B<fakeroot>, B<sudo>, B<super> or B<really>.
 450 B<su>
 451 is not suitable, since it can only invoke the user's shell with
 452 B<-c>
 453 instead of passing arguments individually to the command to be run.
 454
 455 =item B<-R>, B<--rules-file=>I<rules-file>
 456
 457 Building a Debian package usually involves invoking
 458 B<debian/rules>
 459 as a command with several standard parameters (since dpkg 1.14.17,
 460 long option since dpkg 1.18.8).
 461 With this option it's
 462 possible to use another program invocation to build the package (it can
 463 include space separated parameters).
 464 Alternatively it can be used to execute the standard rules file with
 465 another make program (for example by using
 466 B</usr/local/bin/make -f debian/rules>
 467 as I<rules-file>).
 468
 469 =item B<--check-command=>I<check-command>
 470
 471 Command used to check the B<.changes> file itself and any artifact built
 472 referenced in the file (since dpkg 1.17.6).
 473 The command should take the B<.changes> pathname
 474 as an argument.
 475 This command will usually be B<lintian>.
 476
 477 =item B<--check-option=>I<opt>
 478
 479 Pass option I<opt> to the I<check-command> specified with
 480 B<DEB_CHECK_COMMAND> or B<--check-command> (since dpkg 1.17.6).
 481 Can be used multiple times.
 482
 483 =item B<--hook->I<hook-name>B<=>I<hook-command>
 484
 485 Set the specified shell code I<hook-command> as the hook I<hook-name>,
 486 which will run at the times specified in the run steps (since dpkg 1.17.6).
 487 The hooks will
 488 always be executed even if the following action is not performed (except
 489 for the B<binary> hook).
 490 All the hooks will run in the unpacked source directory.
 491
 492 Some hooks can receive addition information through environment variables
 493 (since dpkg 1.22.0).
 494 All hooks get the hook name in the B<DPKG_BUILDPACKAGE_HOOK_NAME> environment
 495 variable (since dpkg 1.22.0).
 496
 497 B<Note>: Hooks can affect the build process, and cause build failures if
 498 their commands fail, so watch out for unintended consequences.
 499
 500 The current I<hook-name> supported are:
 501
 502 =over
 503
 504 =item B<preinit>
 505
 506 =item B<init>
 507
 508 =item B<preclean>
 509
 510 =item B<source>
 511
 512 Gets B<DPKG_BUILDPACKAGE_HOOK_SOURCE_OPTIONS> with the space-separated lists
 513 of options that will passed to the B<dpkg-source> call.
 514
 515 =item B<build>
 516
 517 Gets B<DPKG_BUILDPACKAGE_HOOK_BUILD_TARGET> with the name of the
 518 B<debian/rules> build target called.
 519 Before dpkg 1.22.7 the variable was only set if the target was called.
 520
 521 =item B<binary>
 522
 523 Gets B<DPKG_BUILDPACKAGE_HOOK_BINARY_TARGET> with the name of the
 524 B<debian/rules> binary target called, but only if called.
 525
 526 =item B<buildinfo>
 527
 528 Gets B<DPKG_BUILDPACKAGE_HOOK_BUILDINFO_OPTIONS> with the space-separated lists
 529 of options that will passed to the B<dpkg-genbuildinfo> call.
 530
 531 =item B<changes>
 532
 533 Gets B<DPKG_BUILDPACKAGE_HOOK_CHANGES_OPTIONS> with the space-separated lists
 534 of options that will passed to the B<dpkg-genchanges> call.
 535
 536 =item B<postclean>
 537
 538 =item B<check>
 539
 540 Gets B<DPKG_BUILDPACKAGE_HOOK_CHECK_OPTIONS> with the space-separated lists
 541 of options that will passed to the check command call.
 542
 543 =item B<sign>
 544
 545 =item B<done>
 546
 547 =back
 548
 549 The I<hook-command> supports the following substitution format string,
 550 which will get applied to it before execution:
 551
 552 =over
 553
 554 =item B<%%>
 555
 556 A single % character.
 557
 558 =item B<%a>
 559
 560 A boolean value (0 or 1), representing whether the following action is
 561 being performed.
 562
 563 =item B<%p>
 564
 565 The source package name.
 566
 567 =item B<%v>
 568
 569 The source package version.
 570
 571 =item B<%s>
 572
 573 The source package version (without the epoch).
 574
 575 =item B<%u>
 576
 577 The upstream version.
 578
 579 =back
 580
 581 =item B<--buildinfo-file=>I<filename>
 582
 583 Set the I<filename> for the generated B<.buildinfo> file (since dpkg 1.21.0).
 584
 585 =item B<--buildinfo-option=>I<opt>
 586
 587 Pass option I<opt> to B<dpkg-genbuildinfo> (since dpkg 1.18.11).
 588 Can be used multiple times.
 589
 590 =item B<--sign-backend=>I<sign-backend>
 591
 592 Specify an OpenPGP backend interface to use when invoking the I<sign-command>
 593 (since dpkg 1.21.10).
 594
 595 The default is B<auto>, where the best current backend available will be used.
 596 The specific OpenPGP backends supported in order of preference are:
 597
 598 =over 4
 599
 600 =item B<sop>
 601
 602 (any conforming Stateless OpenPGP implementation)
 603
 604 =item B<sq>
 605
 606 (from Sequoia-PGP)
 607
 608 =item B<gpg>
 609
 610 (from GnuPG)
 611
 612 =back
 613
 614 =item B<-p>, B<--sign-command=>I<sign-command>
 615
 616 When B<dpkg-buildpackage> needs to execute an OpenPGP backend command to
 617 sign a source control (B<.dsc>) file, a B<.buildinfo> file or a B<.changes>
 618 file it will run
 619 I<sign-command> (searching the B<PATH> if necessary) instead of the
 620 default or auto-detected backend command (long option since dpkg 1.18.8).
 621 I<sign-command> will get all the backend specific arguments according to
 622 the B<--sign-backend> selected.
 623 I<sign-command> should not contain spaces or any other shell metacharacters.
 624
 625 =item B<-k>, B<--sign-keyid=>I<key-id>
 626
 627 =item B<--sign-key=>I<key-id>
 628
 629 Specify an OpenPGP key-ID (either a fingerprint or a user-ID) for the
 630 secret key to use when signing packages (B<--sign-key> since dpkg 1.18.8,
 631 B<--sign-keyid> since dpkg 1.21.10).
 632
 633 =item B<--sign-keyfile=>I<key-file>
 634
 635 Specify an OpenPGP I<key-file> containing the secret key to use when signing
 636 packages (since dpkg 1.21.10).
 637
 638 B<Note>: For security reasons the I<key-file> is best kept locked with a
 639 password.
 640
 641 =item B<-us>, B<--unsigned-source>
 642
 643 Do not sign the source package (long option since dpkg 1.18.8).
 644
 645 =item B<-ui>, B<--unsigned-buildinfo>
 646
 647 Do not sign the B<.buildinfo> file (since dpkg 1.18.19).
 648
 649 =item B<-uc>, B<--unsigned-changes>
 650
 651 Do not sign the B<.buildinfo> and B<.changes> files
 652 (long option since dpkg 1.18.8).
 653
 654 =item B<--no-sign>
 655
 656 Do not sign any file, this includes the source package, the B<.buildinfo>
 657 file and the B<.changes> file (since dpkg 1.18.20).
 658
 659 =item B<--force-sign>
 660
 661 Force the signing of the resulting files (since dpkg 1.17.0), regardless of
 662 B<-us>, B<--unsigned-source>,
 663 B<-ui>, B<--unsigned-buildinfo>,
 664 B<-uc>, B<--unsigned-changes>
 665 or other internal heuristics.
 666
 667 =item B<-sn>
 668
 669 =item B<-ss>
 670
 671 =item B<-sA>
 672
 673 =item B<-sk>
 674
 675 =item B<-su>
 676
 677 =item B<-sr>
 678
 679 =item B<-sK>
 680
 681 =item B<-sU>
 682
 683 =item B<-sR>
 684
 685 =item B<-i>, B<--diff-ignore>[=I<regex>]
 686
 687 =item B<-I>, B<--tar-ignore>[=I<pattern>]
 688
 689 =item B<-z>, B<--compression-level=>I<level>
 690
 691 =item B<-Z>, B<--compression=>I<compressor>
 692
 693 Passed unchanged to B<dpkg-source>.
 694 See its manual page.
 695
 696 =item B<--source-option=>I<opt>
 697
 698 Pass option I<opt> to B<dpkg-source> (since dpkg 1.15.6).
 699 Can be used multiple times.
 700
 701 =item B<--changes-file=>I<filename>
 702
 703 Set the I<filename> for the generated B<.changes> file (since dpkg 1.21.0).
 704
 705 =item B<--changes-option=>I<opt>
 706
 707 Pass option I<opt> to B<dpkg-genchanges> (since dpkg 1.15.6).
 708 Can be used multiple times.
 709
 710 =item B<--admindir=>I<dir>
 711
 712 =item B<--admindir> I<dir>
 713
 714 Change the location of the B<dpkg> database (since dpkg 1.14.0).
 715 The default location is I<%ADMINDIR%>.
 716
 717 =item B<-?>, B<--help>
 718
 719 Show the usage message and exit.
 720
 721 =item B<--version>
 722
 723 Show the version and exit.
 724
 725 =back
 726
 727 =head1 ENVIRONMENT
 728
 729 =head2 External environment
 730
 731 =over
 732
 733 =item B<DEB_CHECK_COMMAND>
 734
 735 If set, it will be used as the command to check the B<.changes> file
 736 (since dpkg 1.17.6).
 737 Overridden by the B<--check-command> option.
 738
 739 =item B<DEB_SIGN_KEYID>
 740
 741 If set, it will be used to sign the B<.changes>, B<.buildinfo> and B<.dsc>
 742 files (since dpkg 1.17.2).
 743 Overridden by the B<--sign-key> option.
 744
 745 =item B<DEB_SIGN_KEYFILE>
 746
 747 If set, it will be used to sign the B<.changes>, B<.buildinfo> and B<.dsc>
 748 files (since dpkg 1.21.10).
 749 Overridden by the B<--sign-keyfile> option.
 750
 751 =item B<DEB_BUILD_OPTIONS>
 752
 753 If set, it will contain a space-separated list of options that affect
 754 the behavior of some dpkg tools involved in package building,
 755 and might affect the package build process if the code in F<debian/rules>
 756 honors them.
 757 These options can have parameters specified immediately after an
 758 equal sign (‘B<=>‘).
 759 For options that support multiple parameters,
 760 these will not be separated by spaces,
 761 as these are reserved to separate options.
 762
 763 The following are the options known and supported by dpkg tools,
 764 other options honored by F<debian/rules> might be defined by distribution
 765 specific policies.
 766
 767 =over
 768
 769 =item B<parallel=>I<N>
 770
 771 The F<debian/rules> in the packaging might use this option to set up
 772 the build process to use I<N> parallel jobs.
 773 It is overridden by the B<--jobs> and B<--jobs-force> options.
 774
 775 =item B<nocheck>
 776
 777 B<dpkg-buildpackage> will ignore the B<DEB_CHECK_COMMAND> variable.
 778 The F<debian/rules> in the packaging is not expected to run test suites
 779 during the build.
 780
 781 =item B<noopt>
 782
 783 If F<debian/rules> calls B<dpkg-buildflags> to set up the build flags,
 784 those will be set to not enable any optimizations.
 785
 786 =item B<nostrip>
 787
 788 The F<debian/rules> in the packaging should ensure that objects do not get
 789 the debugging information stripped.
 790 If F<debian/rules> includes the B<mk/buildtools.mk> make fragment the
 791 B<STRIP> make variable will respect this option.
 792
 793 =item B<terse>
 794
 795 B<dpkg-buildpackage> will append the B<--no-print-directory> L<make(1)>
 796 flag to the B<MAKEFLAGS> environment variable.
 797 The F<debian/rules> in the packaging should reduce verbosity, while not
 798 being completely quiet.
 799
 800 =item B<hardening=>I<feature-spec>
 801
 802 =item B<reproducible=>I<feature-spec>
 803
 804 =item B<abi=>I<feature-spec>
 805
 806 =item B<future=>I<feature-spec>
 807
 808 =item B<qa=>I<feature-spec>
 809
 810 =item B<optimize=>I<feature-spec>
 811
 812 =item B<sanitize=>I<feature-spec>
 813
 814 These are feature areas that control build flag features.
 815 See L<dpkg-buildflags(1)> for further details.
 816
 817 =back
 818
 819 =item B<DEB_BUILD_PROFILES>
 820
 821 If set, it will be used as the active build profile(s) for the package
 822 being built (since dpkg 1.17.2).
 823 It is a space separated list of profile names.
 824 Overridden by the B<-P> option.
 825
 826 =item B<DPKG_COLORS>
 827
 828 Sets the color mode (since dpkg 1.18.5).
 829 The currently accepted values are: B<auto> (default), B<always> and
 830 B<never>.
 831
 832 =item B<DPKG_NLS>
 833
 834 If set, it will be used to decide whether to activate Native Language Support,
 835 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 836 The accepted values are: B<0> and B<1> (default).
 837
 838 =back
 839
 840 =head2 Internal environment
 841
 842 Even if B<dpkg-buildpackage> exports some variables, B<debian/rules>
 843 should not rely on their presence and should instead use the
 844 respective interface to retrieve the needed values, because that
 845 file is the main entry point to build packages and running it
 846 standalone should be supported.
 847
 848 =over
 849
 850 =item B<DEB_BUILD_*>
 851
 852 =item B<DEB_HOST_*>
 853
 854 =item B<DEB_TARGET_*>
 855
 856 B<dpkg-architecture> is called with the B<-a> and B<-t>
 857 parameters forwarded.
 858 Any variable that is output by its B<-s>
 859 option is integrated in the build environment.
 860
 861 =item B<DEB_RULES_REQUIRES_ROOT>
 862
 863 This variable is set to the value obtained from the B<Rules-Requires-Root>
 864 field, the dpkg-build-api level or from the command-line.
 865 When set, it will be a valid value for the B<Rules-Requires-Root> field.
 866 It is used to notify B<debian/rules> whether the B<rootless-builds.txt>
 867 specification is supported.
 868
 869 =item B<DEB_GAIN_ROOT_CMD>
 870
 871 This variable is set to I<gain-root-command> when the field
 872 B<Rules-Requires-Root> is set to a value different to B<no> and
 873 B<binary-targets>.
 874
 875 =item B<SOURCE_DATE_EPOCH>
 876
 877 This variable is set to the Unix timestamp since the epoch of the
 878 latest entry in I<debian/changelog>, if it is not already defined.
 879
 880 =back
 881
 882 =head1 FILES
 883
 884 =over
 885
 886 =item I<%PKGCONFDIR%/buildpackage.conf>
 887
 888 System wide configuration file
 889
 890 =item I<$XDG_CONFIG_HOME/dpkg/buildpackage.conf> or
 891
 892 =item I<$HOME/.config/dpkg/buildpackage.conf>
 893
 894 User configuration file.
 895
 896 =back
 897
 898 =head1 NOTES
 899
 900 =head2 Compiler flags are no longer exported
 901
 902 Between dpkg 1.14.17 and 1.16.1, B<dpkg-buildpackage>
 903 exported compiler flags (B<CFLAGS>, B<CXXFLAGS>, B<FFLAGS>,
 904 B<CPPFLAGS> and B<LDFLAGS>) with values as returned
 905 by B<dpkg-buildflags>.
 906 This is no longer the case.
 907
 908 =head2 Default build targets
 909
 910 B<dpkg-buildpackage> is using the B<build-arch> and
 911 B<build-indep> targets since dpkg 1.16.2.
 912 Before dpkg 1.22.7,
 913 there was code to try to detect the missing targets and fallback on the
 914 B<build> target.
 915 Those targets are thus mandatory.
 916
 917 =head1 SECURITY
 918
 919 Building binary or source packages should only be performed over trusted
 920 source data.
 921
 922 =head1 BUGS
 923
 924 It should be possible to specify spaces and shell metacharacters
 925 and initial arguments for
 926 I<gain-root-command> and I<sign-command>.
 927
 928 =head1 SEE ALSO
 929
 930 I<%PKGDOCDIR%/spec/rootless-builds.txt>,
 931 L<dpkg-source(1)>,
 932 L<dpkg-architecture(1)>,
 933 L<dpkg-buildflags(1)>,
 934 L<dpkg-genbuildinfo(1)>,
 935 L<dpkg-genchanges(1)>,
 936 L<fakeroot(1)>,
 937 L<lintian(1)>,
 938 L<https://datatracker.ietf.org/doc/draft-dkg-openpgp-stateless-cli/>,
 939 L<sq(1)>,
 940 L<gpg(1)>.