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