man/dpkg-buildflags.pod

   1 # dpkg manual page - dpkg-buildflags(1)
   2 #
   3 # Copyright © 2010-2011 Raphaël Hertzog <hertzog@debian.org>
   4 # Copyright © 2011 Kees Cook <kees@debian.org>
   5 # Copyright © 2011-2015 Guillem Jover <guillem@debian.org>
   6 #
   7 # This is free software; you can redistribute it and/or modify
   8 # it under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 2 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # This is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  19
  20 =encoding utf8
  21
  22 =head1 NAME
  23
  24 dpkg-buildflags - returns build flags to use during package build
  25
  26 =head1 SYNOPSIS
  27
  28 B<dpkg-buildflags>
  29 [I<option>...] [I<command>]
  30
  31 =head1 DESCRIPTION
  32
  33 B<dpkg-buildflags> is a tool to retrieve compilation flags to use during
  34 build of Debian packages.
  35
  36 The default flags are defined by the vendor but they can be
  37 extended/overridden in several ways:
  38
  39 =over
  40
  41 =item 1.
  42
  43 system-wide with B<%PKGCONFDIR%/buildflags.conf>;
  44
  45 =item 2.
  46
  47 for the current user with B<$XDG_CONFIG_HOME/dpkg/buildflags.conf>
  48 where B<$XDG_CONFIG_HOME> defaults to B<$HOME/.config>;
  49
  50 =item 3.
  51
  52 temporarily by the user with environment variables (see section
  53 L</ENVIRONMENT>);
  54
  55 =item 4.
  56
  57 dynamically by the package maintainer with environment variables set via
  58 B<debian/rules> (see section L</ENVIRONMENT>).
  59
  60 =back
  61
  62 The configuration files can contain four types of directives:
  63
  64 =over
  65
  66 =item B<SET> I<flag> I<value>
  67
  68 Override the flag named I<flag> to have the value I<value>.
  69
  70 =item B<STRIP> I<flag> I<value>
  71
  72 Strip from the flag named I<flag> all the build flags listed in I<value>.
  73 Since dpkg 1.16.1.
  74
  75 =item B<APPEND> I<flag> I<value>
  76
  77 Extend the flag named I<flag> by appending the options given in I<value>.
  78 A space is prepended to the appended value if the flag's current value is non-empty.
  79
  80 =item B<PREPEND> I<flag> I<value>
  81
  82 Extend the flag named I<flag> by prepending the options given in I<value>.
  83 A space is appended to the prepended value if the flag's current value is non-empty.
  84 Since dpkg 1.16.1.
  85
  86 =back
  87
  88 The configuration files can contain comments on lines starting with a hash
  89 (#).
  90 Empty lines are also ignored.
  91
  92 This program was introduced in dpkg 1.15.7.
  93
  94 =head1 COMMANDS
  95
  96 =over
  97
  98 =item B<--dump>
  99
 100 Print to standard output all compilation flags and their values.
 101 It prints
 102 one flag per line separated from its value by an equal sign
 103 (“I<flag>=I<value>”).
 104 This is the default action.
 105
 106 =item B<--list>
 107
 108 Print the list of flags supported by the current vendor
 109 (one per line).
 110 See the L</SUPPORTED FLAGS> section for more
 111 information about them.
 112
 113 =item B<--status>
 114
 115 Display any information that can be useful to explain the behavior of
 116 B<dpkg-buildflags> (since dpkg 1.16.5): relevant environment variables,
 117 current vendor, state of all feature flags.
 118 Also print the resulting compiler flags with their origin.
 119
 120 This is intended to be run from B<debian/rules>, so that the build log
 121 keeps a clear trace of the build flags used.
 122 This can be useful to diagnose
 123 problems related to them.
 124
 125 =item B<--export=>I<format>
 126
 127 Print to standard output commands that can be used to export all the
 128 compilation flags for some particular tool.
 129 If the I<format> value is not given, B<sh> is assumed.
 130 Only compilation flags starting with an
 131 upper case character are included, others are assumed to not be suitable
 132 for the environment.
 133 Supported formats:
 134
 135 =over
 136
 137 =item B<sh>
 138
 139 Shell commands to set and export all the compilation flags in the
 140 environment.
 141 The flag values are quoted so the output is ready for
 142 evaluation by a shell.
 143
 144 =item B<cmdline>
 145
 146 Arguments to pass to a build program's command line to use all the
 147 compilation flags (since dpkg 1.17.0).
 148 The flag values are quoted in
 149 shell syntax.
 150
 151 =item B<configure>
 152
 153 This is a legacy alias for B<cmdline>.
 154
 155 =item B<make>
 156
 157 Make directives to set and export all the compilation flags in the
 158 environment.
 159 Output can be written to a Makefile fragment and
 160 evaluated using an B<include> directive.
 161
 162 =back
 163
 164 =item B<--get> I<flag>
 165
 166 Print the value of the flag on standard output.
 167 Exits with 0
 168 if the flag is known otherwise exits with 1.
 169
 170 =item B<--origin> I<flag>
 171
 172 Print the origin of the value that is returned by B<--get>.
 173 Exits with 0 if the flag is known otherwise exits with 1.
 174 The origin can be one
 175 of the following values:
 176
 177 =over
 178
 179 =item B<vendor>
 180
 181 the original flag set by the vendor is returned;
 182
 183 =item B<system>
 184
 185 the flag is set/modified by a system-wide configuration;
 186
 187 =item B<user>
 188
 189 the flag is set/modified by a user-specific configuration;
 190
 191 =item B<env>
 192
 193 the flag is set/modified by an environment-specific configuration.
 194
 195 =back
 196
 197 =item B<--query>
 198
 199 Print any information that can be useful to explain the behavior of the
 200 program: current vendor, relevant environment variables, feature areas,
 201 state of all feature flags, whether a feature is handled as a builtin
 202 default by the compiler (since dpkg 1.21.14),
 203 and the compiler flags with their origin (since dpkg 1.19.0).
 204
 205 For example:
 206
 207  Vendor: Debian
 208  Environment:
 209   DEB_CFLAGS_SET=-O0 -Wall
 210
 211  Area: qa
 212  Features:
 213   bug=no
 214   canary=no
 215  Builtins:
 216
 217  Area: hardening
 218  Features:
 219   pie=no
 220  Builtins:
 221   pie=yes
 222
 223  Area: reproducible
 224  Features:
 225   timeless=no
 226  Builtins:
 227
 228  Flag: CFLAGS
 229  Value: -O0 -Wall
 230  Origin: env
 231
 232  Flag: CPPFLAGS
 233  Value: -D_FORTIFY_SOURCE=2
 234  Origin: vendor
 235
 236 =item B<--query-features> I<area>
 237
 238 Print the features enabled for a given area (since dpkg 1.16.2).
 239 If the feature is handled (even if only on some architectures) as a
 240 builtin default by the compiler, then a B<Builtin> field is printed
 241 (since dpkg 1.21.14).
 242 The only currently recognized
 243 areas on Debian and derivatives are B<future>, B<qa>, B<reproducible>,
 244 B<sanitize> and B<hardening>, see the B<FEATURE AREAS>
 245 section for more details.
 246 Exits with 0 if the area is known otherwise exits with 1.
 247
 248 The output is in RFC822 format, with one section per feature.
 249 For example:
 250
 251  Feature: pie
 252  Enabled: yes
 253  Builtin: yes
 254
 255  Feature: stackprotector
 256  Enabled: yes
 257
 258 =item B<--help>
 259
 260 Show the usage message and exit.
 261
 262 =item B<--version>
 263
 264 Show the version and exit.
 265
 266 =back
 267
 268 =head1 SUPPORTED FLAGS
 269
 270 =over
 271
 272 =item B<ASFLAGS>
 273
 274 Options for the host assembler.
 275 Default value: empty.
 276 Since dpkg 1.21.0.
 277
 278 =item B<CFLAGS>
 279
 280 Options for the host C compiler.
 281 The default value set by the vendor
 282 includes B<-g> and the default optimization level (B<-O2> usually,
 283 or B<-O0> if the B<DEB_BUILD_OPTIONS> environment variable defines
 284 I<noopt>).
 285
 286 =item B<CPPFLAGS>
 287
 288 Options for the host C preprocessor.
 289 Default value: empty.
 290
 291 =item B<CXXFLAGS>
 292
 293 Options for the host C++ compiler.
 294 Same as B<CFLAGS>.
 295
 296 =item B<OBJCFLAGS>
 297
 298 Options for the host Objective C compiler.
 299 Same as B<CFLAGS>.
 300 Since dpkg 1.17.7.
 301
 302 =item B<OBJCXXFLAGS>
 303
 304 Options for the host Objective C++ compiler.
 305 Same as B<CXXFLAGS>.
 306 Since dpkg 1.17.7.
 307
 308 =item B<DFLAGS>
 309
 310 Options for the host D compiler (ldc or gdc).
 311 Since dpkg 1.20.6.
 312
 313 =item B<FFLAGS>
 314
 315 Options for the host Fortran 77 compiler.
 316 A subset of B<CFLAGS>.
 317
 318 =item B<FCFLAGS>
 319
 320 Options for the host Fortran 9x compiler.
 321 Same as B<FFLAGS>.
 322 Since dpkg 1.17.7.
 323
 324 =item B<LDFLAGS>
 325
 326 Options passed to the host compiler when linking executables or shared
 327 objects (if the linker is called directly, then
 328 B<-Wl>
 329 and
 330 B<,>
 331 have to be stripped from these options).
 332 Default value: empty.
 333
 334 =item B<ASFLAGS_FOR_BUILD>
 335
 336 Options for the build assembler.
 337 Default value: empty.
 338 Since dpkg 1.22.1.
 339
 340 =item B<CFLAGS_FOR_BUILD>
 341
 342 Options for the build C compiler.
 343 The default value set by the vendor includes B<-g> and the default
 344 optimization level (B<-O2> usually, or B<-O0> if the B<DEB_BUILD_OPTIONS>
 345 environment variable defines I<noopt>).
 346 Since dpkg 1.22.1.
 347
 348 =item B<CPPFLAGS_FOR_BUILD>
 349
 350 Options for the build C preprocessor.
 351 Default value: empty.
 352 Since dpkg 1.22.1.
 353
 354 =item B<CXXFLAGS_FOR_BUILD>
 355
 356 Options for the build C++ compiler.
 357 Same as B<CFLAGS_FOR_BUILD>.
 358 Since dpkg 1.22.1.
 359
 360 =item B<OBJCFLAGS_FOR_BUILD>
 361
 362 Options for the build Objective C compiler.
 363 Same as B<CFLAGS_FOR_BUILD>.
 364 Since dpkg 1.22.1.
 365
 366 =item B<OBJCXXFLAGS_FOR_BUILD>
 367
 368 Options for the build Objective C++ compiler.
 369 Same as B<CXXFLAGS_FOR_BUILD>.
 370 Since dpkg 1.22.1.
 371
 372 =item B<DFLAGS_FOR_BUILD>
 373
 374 Options for the build D compiler (ldc or gdc).
 375 Since dpkg 1.22.1.
 376
 377 =item B<FFLAGS_FOR_BUILD>
 378
 379 Options for the build Fortran 77 compiler.
 380 A subset of B<CFLAGS_FOR_BUILD>.
 381 Since dpkg 1.22.1.
 382
 383 =item B<FCFLAGS_FOR_BUILD>
 384
 385 Options for the build Fortran 9x compiler.
 386 Same as B<FFLAGS_FOR_BUILD>.
 387 Since dpkg 1.22.1.
 388
 389 =item B<LDFLAGS_FOR_BUILD>
 390
 391 Options passed to the build compiler when linking executables or shared
 392 objects (if the linker is called directly, then B<-Wl> and B<,> have to
 393 be stripped from these options).
 394 Default value: empty.
 395 Since dpkg 1.22.1.
 396
 397 =back
 398
 399 New flags might be added in the future if the need arises (for example
 400 to support other languages).
 401
 402 =head1 FEATURE AREAS
 403
 404 Each area feature can be enabled and disabled in the B<DEB_BUILD_OPTIONS>
 405 and B<DEB_BUILD_MAINT_OPTIONS> environment variable's area value with the
 406 ‘B<+>’ and ‘B<->’ modifier.
 407 For example, to enable the B<hardening> “pie” feature and disable the
 408 “fortify” feature you can do this in B<debian/rules>:
 409
 410     export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
 411
 412 The special feature B<all> (valid in any area) can be used to enable or
 413 disable all area features at the same time.
 414 Thus disabling everything in the B<hardening> area and enabling only
 415 “format” and “fortify” can be achieved with:
 416
 417     export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
 418
 419 =head2 abi
 420
 421 Several compile-time options (detailed below) can be used to enable features
 422 that can change the ABI of a package, but cannot be enabled by default due to
 423 backwards compatibility reasons unless coordinated or checked individually.
 424
 425 =over
 426
 427 =item B<lfs>
 428
 429 This setting (since dpkg 1.22.0; disabled by default) enables
 430 Large File Support on 32-bit architectures where their ABI does
 431 not include LFS by default, by adding
 432 B<-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64> to B<CPPFLAGS>.
 433
 434 When this feature is enabled it will override the value from the same
 435 feature in the B<future> feature area.
 436
 437 =item B<time64>
 438
 439 This setting (since dpkg 1.22.0; disabled by default) enables 64-bit time_t
 440 support on 32-bit architectures where their ABI does not include it by
 441 default, by adding B<-D_TIME_BITS=64> to B<CPPFLAGS>.
 442 This setting automatically enables the B<lfs> feature as it requires it.
 443
 444 =back
 445
 446 =head2 future
 447
 448 Several compile-time options (detailed below) can be used to enable features
 449 that should be enabled by default, but cannot due to backwards compatibility
 450 reasons.
 451
 452 =over
 453
 454 =item B<lfs>
 455
 456 This setting (since dpkg 1.19.0; disabled by default) is now an alias
 457 for the B<lfs> feature in the B<abi> area, use that instead.
 458 The feature from the B<abi> area overrides this setting.
 459
 460 =back
 461
 462 =head2 qa
 463
 464 Several compile-time options (detailed below) can be used to help detect
 465 problems in the source code or build system.
 466
 467 =over
 468
 469 =item B<bug-implicit-func>
 470
 471 This setting (since dpkg 1.22.3; disabled by default) adds
 472 B<-Werror=implicit-function-declaration> to B<CFLAGS>.
 473
 474 =item B<bug>
 475
 476 This setting (since dpkg 1.17.4; disabled by default) adds any warning
 477 option that reliably detects problematic source code.
 478 The warnings are fatal.
 479 The only currently supported flags are B<CFLAGS> and B<CXXFLAGS>
 480 with flags set to B<-Werror=array-bounds>, B<-Werror=clobbered>,
 481 B<-Werror=implicit-function-declaration> and
 482 B<-Werror=volatile-register-var>.
 483
 484 This feature handles B<-Werror=implicit-function-declaration> via
 485 the B<bug-implicit-func> feature, if that has not been specified.
 486
 487 =item B<canary>
 488
 489 This setting (since dpkg 1.17.14; disabled by default) adds dummy canary
 490 options to the build flags, so that the build logs can be checked for how
 491 the build flags propagate and to allow finding any omission of normal
 492 build flag settings.
 493 The only currently supported flags are B<CPPFLAGS>, B<CFLAGS>,
 494 B<OBJCFLAGS>, B<CXXFLAGS> and B<OBJCXXFLAGS> with flags set
 495 to B<-D__DEB_CANARY_>I<flag>_I<random-id>B<__>, and
 496 B<LDFLAGS> set to B<-Wl,-z,deb-canary->I<random-id>.
 497
 498 =back
 499
 500 =head2 optimize
 501
 502 Several compile-time options (detailed below) can be used to help optimize
 503 a resulting binary (since dpkg 1.21.0).
 504 B<Note>: enabling B<all> these options can result in unreproducible binary
 505 artifacts.
 506
 507 =over
 508
 509 =item B<lto>
 510
 511 This setting (since dpkg 1.21.0; disabled by default) enables
 512 Link Time Optimization by adding B<-flto=auto -ffat-lto-objects> to
 513 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 514 B<FFLAGS>, B<FCFLAGS> and B<LDFLAGS>.
 515
 516 =back
 517
 518 =head2 sanitize
 519
 520 Several compile-time options (detailed below) can be used to help sanitize
 521 a resulting binary against memory corruptions, memory leaks, use after free,
 522 threading data races and undefined behavior bugs.
 523 B<Note>: these options should B<not> be used for production builds
 524 as they can reduce reliability for conformant code, reduce security or
 525 even functionality.
 526
 527 =over
 528
 529 =item B<address>
 530
 531 This setting (since dpkg 1.18.0; disabled by default) adds
 532 B<-fsanitize=address> to
 533 B<LDFLAGS> and B<-fsanitize=address -fno-omit-frame-pointer> to
 534 B<CFLAGS> and B<CXXFLAGS>.
 535
 536 =item B<thread>
 537
 538 This setting (since dpkg 1.18.0; disabled by default) adds
 539 B<-fsanitize=thread> to
 540 B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>.
 541
 542 =item B<leak>
 543
 544 This setting (since dpkg 1.18.0; disabled by default) adds
 545 B<-fsanitize=leak> to
 546 B<LDFLAGS>.
 547 It gets automatically disabled if either the B<address>
 548 or the B<thread> features are enabled, as they imply it.
 549
 550 =item B<undefined>
 551
 552 This setting (since dpkg 1.18.0; disabled by default) adds
 553 B<-fsanitize=undefined> to
 554 B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>.
 555
 556 =back
 557
 558 =head2 hardening
 559
 560 Several compile-time options (detailed below) can be used to help harden
 561 a resulting binary against memory corruption attacks, or provide
 562 additional warning messages during compilation.
 563 Except as noted below, these are enabled by default for architectures
 564 that support them.
 565
 566 =over
 567
 568 =item B<format>
 569
 570 This setting (since dpkg 1.16.1; enabled by default) adds
 571 B<-Wformat -Werror=format-security>
 572 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS> and B<OBJCXXFLAGS>.
 573 This will warn about improper format
 574 string uses, and will fail when format functions are used in a way
 575 that represent possible security problems.
 576 At present, this warns about
 577 calls to B<printf> and B<scanf> functions where the format string is
 578 not a string literal and there are no format arguments, as in
 579 B<printf(foo);> instead of B<printf("%s", foo);>
 580 This may be a security hole if the format string came from untrusted
 581 input and contains ‘%n’.
 582
 583 =item B<fortify>
 584
 585 This setting (since dpkg 1.16.1; enabled by default) adds
 586 B<-D_FORTIFY_SOURCE=2>
 587 to B<CPPFLAGS>.
 588 During code generation the compiler
 589 knows a great deal of information about buffer sizes (where possible), and
 590 attempts to replace insecure unlimited length buffer function calls with
 591 length-limited ones.
 592 This is especially useful for old, crufty code.
 593 Additionally, format strings in writable memory that contain ‘%n’ are
 594 blocked.
 595 If an application depends on such a format string, it will need
 596 to be worked around.
 597
 598 Note that for this option to have any effect, the source must also
 599 be compiled with B<-O1> or higher.
 600 If the environment variable
 601 B<DEB_BUILD_OPTIONS> contains I<noopt>, then B<fortify>
 602 support will be disabled, due to new warnings being issued by
 603 glibc 2.16 and later.
 604
 605 =item B<stackprotector>
 606
 607 This setting (since dpkg 1.16.1; enabled by default if stackprotectorstrong
 608 is not in use) adds B<-fstack-protector --param=ssp-buffer-size=4>
 609 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 610 B<FFLAGS> and B<FCFLAGS>.
 611 This adds safety checks against stack
 612 overwrites.
 613 This renders many potential code injection attacks into aborting situations.
 614 In the best case this turns code injection
 615 vulnerabilities into denial of service or into non-issues (depending on
 616 the application).
 617
 618 This feature requires linking against glibc (or another provider of
 619 B<__stack_chk_fail>), so needs to be disabled when building with
 620 B<-nostdlib> or B<-ffreestanding> or similar.
 621
 622 =item B<stackprotectorstrong>
 623
 624 This setting (since dpkg 1.17.11; enabled by default) adds
 625 B<-fstack-protector-strong>
 626 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 627 B<FFLAGS> and B<FCFLAGS>.
 628 This is a stronger variant of B<stackprotector>, but without significant
 629 performance penalties.
 630
 631 Disabling B<stackprotector> will also disable this setting.
 632
 633 This feature has the same requirements as B<stackprotector>, and in
 634 addition also requires gcc 4.9 and later.
 635
 636 =item B<stackclash>
 637
 638 This setting (since dpkg 1.22.0; enabled by default) adds
 639 B<-fstack-clash-protection> on B<amd64>, B<arm64>, B<armhf> and B<armel> to
 640 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 641 B<FFLAGS> and B<FCFLAGS>.
 642 This adds code to prevent stack clash style attacks.
 643
 644 =item B<branch>
 645
 646 This setting (since dpkg 1.22.0; enabled by default) adds B<-fcf-protection>
 647 on B<amd64> and B<-mbranch-protection=standard> on B<arm64> to
 648 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 649 B<FFLAGS> and B<FCFLAGS>.
 650 This adds branch protection to indirect calls, jumps and returns to check
 651 whether these are valid at run-time.
 652
 653 =item B<relro>
 654
 655 This setting (since dpkg 1.16.1; enabled by default) adds
 656 B<-Wl,-z,relro>
 657 to B<LDFLAGS>.
 658 During program load,
 659 several ELF memory sections need to be written to by the linker.
 660 This flags the loader to turn these sections read-only before turning over
 661 control to the program.
 662 Most notably this prevents GOT overwrite attacks.
 663 If this option is disabled,
 664 B<bindnow> will become disabled as well.
 665
 666 =item B<bindnow>
 667
 668 This setting (since dpkg 1.16.1; disabled by default) adds
 669 B<-Wl,-z,now>
 670 to B<LDFLAGS>.
 671 During program load, all dynamic symbols are resolved,
 672 allowing for the entire PLT to be marked read-only (due to B<relro>
 673 above).
 674 The option cannot become enabled if B<relro> is not enabled.
 675
 676 =item B<pie>
 677
 678 This setting (since dpkg 1.16.1; with no global default since dpkg 1.18.23,
 679 as it is enabled
 680 by default now by gcc on the amd64, arm64, armel, armhf, hurd-i386, i386,
 681 kfreebsd-amd64, kfreebsd-i386, mips, mipsel, mips64el, powerpc, ppc64,
 682 ppc64el, riscv64, s390x, sparc and sparc64 Debian architectures) adds
 683 the required options to enable or disable PIE via gcc specs files, if
 684 needed, depending on whether gcc injects on that architecture the flags
 685 by itself or not.
 686 When the setting is enabled and gcc injects the flags, it adds nothing.
 687 When the setting is enabled and gcc does not inject the flags, it adds
 688 B<-fPIE> (via I<%PKGDATADIR%/pie-compiler.specs>) to B<CFLAGS>,
 689 B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 690 B<FFLAGS> and B<FCFLAGS>, and
 691 B<-fPIE -pie> (via I<%PKGDATADIR%/pie-link.specs>) to B<LDFLAGS>.
 692 When the setting is disabled and gcc injects the flags, it adds
 693 B<-fno-PIE> (via I<%PKGDATADIR%/no-pie-compile.specs>) to B<CFLAGS>,
 694 B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 695 B<FFLAGS> and B<FCFLAGS>, and
 696 B<-fno-PIE -no-pie> (via I<%PKGDATADIR%/no-pie-link.specs>) to
 697 B<LDFLAGS>.
 698
 699 Position Independent Executable (PIE) is needed to take advantage of
 700 Address Space Layout Randomization (ASLR), supported by some kernel versions.
 701 While ASLR can already be enforced for data areas in the stack and heap
 702 (brk and mmap), the code areas must be compiled as position-independent.
 703 Shared libraries already do this (B<-fPIC>), so they gain ASLR automatically,
 704 but binary .text regions need to be built as PIE to gain ASLR.
 705 When this happens, ROP (Return Oriented Programming) attacks are much
 706 harder since there are no static locations to bounce off of during a
 707 memory corruption attack.
 708
 709 PIE is not compatible with B<-fPIC>, so in general care must be taken
 710 when building shared objects.
 711 But because the PIE flags emitted get injected
 712 via gcc specs files, it should always be safe to unconditionally set them
 713 regardless of the object type being compiled or linked.
 714
 715 Static libraries can be used by programs or other shared libraries.
 716 Depending on the flags used to compile all the objects within a static
 717 library, these libraries will be usable by different sets of objects:
 718
 719 =over
 720
 721 =item none
 722
 723 Cannot be linked into a PIE program, nor a shared library.
 724
 725 =item B<-fPIE>
 726
 727 Can be linked into any program, but not a shared library (recommended).
 728
 729 =item B<-fPIC>
 730
 731 Can be linked into any program and shared library.
 732
 733 =back
 734
 735 If there is a need to set these flags manually, bypassing the gcc specs
 736 injection, there are several things to take into account.
 737 Unconditionally
 738 and explicitly passing B<-fPIE>, B<-fpie> or B<-pie> to a
 739 build-system using libtool is safe as these flags will get stripped
 740 when building shared libraries.
 741 Otherwise on projects that build both programs and shared libraries you
 742 might need to make sure that when building the shared libraries B<-fPIC>
 743 is always passed last (so that it overrides any previous B<-PIE>) to
 744 compilation flags such as B<CFLAGS>, and B<-shared> is passed last
 745 (so that it overrides any previous B<-pie>) to linking flags such as
 746 B<LDFLAGS>.
 747 B<Note>: This should not be needed with the default
 748 gcc specs machinery.
 749
 750 Additionally, since PIE is implemented via a general register, some
 751 register starved architectures (but not including i386 anymore since
 752 optimizations implemented in gcc E<gt>= 5) can see performance losses of up to
 753 15% in very text-segment-heavy application workloads; most workloads
 754 see less than 1%.
 755 Architectures with more general registers (e.g. amd64)
 756 do not see as high a worst-case penalty.
 757
 758 =back
 759
 760 =head2 reproducible
 761
 762 The compile-time options detailed below can be used to help improve
 763 build reproducibility or provide additional warning messages during
 764 compilation.
 765 Except as noted below, these are enabled by default for
 766 architectures that support them.
 767
 768 =over
 769
 770 =item B<timeless>
 771
 772 This setting (since dpkg 1.17.14; enabled by default) adds
 773 B<-Wdate-time>
 774 to B<CPPFLAGS>.
 775 This will cause warnings when the B<__TIME__>, B<__DATE__> and
 776 B<__TIMESTAMP__> macros are used.
 777
 778 =item B<fixfilepath>
 779
 780 This setting (since dpkg 1.19.1; enabled by default) adds
 781 B<-ffile-prefix-map=>I<BUILDPATH>B<=.>
 782 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 783 B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is
 784 set to the top-level directory of the package being built.
 785 This has the effect of removing the build path from any generated file.
 786
 787 If both B<fixdebugpath> and B<fixfilepath> are set, this option
 788 takes precedence, because it is a superset of the former.
 789
 790 B<Note>: If the build process captures the build flags into the resulting
 791 built objects, that will make the package unreproducible.
 792 And while disabling this option might make some of the objects reproducible
 793 again this would also require disabling B<fixdebugpath>, which might make
 794 any generated debug symbols objects unreproducible.
 795 The ideal fix is to stop capturing build flags.
 796
 797 =item B<fixdebugpath>
 798
 799 This setting (since dpkg 1.18.5; enabled by default) adds
 800 B<-fdebug-prefix-map=>I<BUILDPATH>B<=.>
 801 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 802 B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is
 803 set to the top-level directory of the package being built.
 804 This has the effect of removing the build path from any generated debug
 805 symbols.
 806
 807 B<Note>: This feature has similar reproducible properties as B<fixfilepath>.
 808
 809 =back
 810
 811 =head1 ENVIRONMENT
 812
 813 There are 2 sets of environment variables doing the same operations, the
 814 first one (DEB_I<flag>_I<op>) should never be used within
 815 B<debian/rules>.
 816 It's meant for any user that wants to rebuild the source package with
 817 different build flags.
 818 The second set
 819 (DEB_I<flag>_MAINT_I<op>) should only be used in B<debian/rules>
 820 by package maintainers to change the resulting build flags.
 821
 822 =over
 823
 824 =item B<DEB_>I<flag>B<_SET>
 825
 826 =item B<DEB_>I<flag>B<_MAINT_SET> (since dpkg 1.16.1)
 827
 828 This variable can be used to force the value returned for the given
 829 I<flag>.
 830
 831 =item B<DEB_>I<flag>B<_STRIP> (since dpkg 1.16.1)
 832
 833 =item B<DEB_>I<flag>B<_MAINT_STRIP> (since dpkg 1.16.1)
 834
 835 This variable can be used to provide a space separated list of options
 836 that will be stripped from the set of flags returned for the given
 837 I<flag>.
 838
 839 =item B<DEB_>I<flag>B<_APPEND>
 840
 841 =item B<DEB_>I<flag>B<_MAINT_APPEND> (since dpkg 1.16.1)
 842
 843 This variable can be used to append supplementary options to the value
 844 returned for the given I<flag>.
 845
 846 =item B<DEB_>I<flag>B<_PREPEND> (since dpkg 1.16.1)
 847
 848 =item B<DEB_>I<flag>B<_MAINT_PREPEND> (since dpkg 1.16.1)
 849
 850 This variable can be used to prepend supplementary options to the value
 851 returned for the given I<flag>.
 852
 853 =item B<DEB_BUILD_OPTIONS>
 854
 855 =item B<DEB_BUILD_MAINT_OPTIONS> (since dpkg 1.16.1)
 856
 857 These variables can be used by a user or maintainer to disable/enable
 858 various area features that affect build flags.
 859 The B<DEB_BUILD_MAINT_OPTIONS> variable overrides any setting in the
 860 B<DEB_BUILD_OPTIONS> feature areas.
 861 See the L</FEATURE AREAS> section for details.
 862
 863 =item B<DEB_VENDOR>
 864
 865 This setting defines the current vendor.
 866 If not set, it will discover the current vendor by reading
 867 B<%PKGCONFDIR%/origins/default>.
 868
 869 =item B<DEB_BUILD_PATH>
 870
 871 This variable sets the build path (since dpkg 1.18.8) to use in features
 872 such as B<fixdebugpath> so that they can be controlled by the caller.
 873 This variable is currently Debian and derivatives-specific.
 874
 875 =item B<DPKG_COLORS>
 876
 877 Sets the color mode (since dpkg 1.18.5).
 878 The currently accepted values are: B<auto> (default), B<always> and
 879 B<never>.
 880
 881 =item B<DPKG_NLS>
 882
 883 If set, it will be used to decide whether to activate Native Language Support,
 884 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 885 The accepted values are: B<0> and B<1> (default).
 886
 887 =back
 888
 889 =head1 FILES
 890
 891 =head2 Configuration files
 892
 893 =over
 894
 895 =item B<%PKGCONFDIR%/buildflags.conf>
 896
 897 System wide configuration file.
 898
 899 =item B<$XDG_CONFIG_HOME/dpkg/buildflags.conf> or
 900
 901 =item B<$HOME/.config/dpkg/buildflags.conf>
 902
 903 User configuration file.
 904
 905 =back
 906
 907 =head2 Packaging support
 908
 909 =over
 910
 911 =item B<%PKGDATADIR%/buildflags.mk>
 912
 913 Makefile snippet that will load (and optionally export) all flags
 914 supported by B<dpkg-buildflags> into variables (since dpkg 1.16.1).
 915
 916 =back
 917
 918 =head1 EXAMPLES
 919
 920 To pass build flags to a build command in a Makefile:
 921
 922 =over
 923
 924  $(MAKE) $(shell dpkg-buildflags --export=cmdline)
 925
 926  ./configure $(shell dpkg-buildflags --export=cmdline)
 927
 928 =back
 929
 930 To set build flags in a shell script or shell fragment, B<eval> can be
 931 used to interpret the output and to export the flags in the environment:
 932
 933 =over
 934
 935  eval "$(dpkg-buildflags --export=sh)" && make
 936
 937 =back
 938
 939 or to set the positional parameters to pass to a command:
 940
 941 =over
 942
 943  eval "set -- $(dpkg-buildflags --export=cmdline)"
 944  for dir in a b c; do (cd $dir && ./configure "$@" && make); done
 945
 946 =back
 947
 948 =head2 Usage in debian/rules
 949
 950 You should call B<dpkg-buildflags> or include B<buildflags.mk>
 951 from the B<debian/rules> file to obtain the needed build flags to
 952 pass to the build system.
 953 Note that older versions of B<dpkg-buildpackage> (before dpkg 1.16.1)
 954 exported these flags automatically.
 955 However, you should not rely on this,
 956 since this breaks manual invocation of B<debian/rules>.
 957
 958 For packages with autoconf-like build systems, you can pass the relevant
 959 options to configure or L<make(1)> directly, as shown above.
 960
 961 For other build systems, or when you need more fine-grained control
 962 about which flags are passed where, you can use B<--get>.
 963 Or you
 964 can include B<buildflags.mk> instead, which takes care of calling
 965 B<dpkg-buildflags> and storing the build flags in make variables.
 966
 967 If you want to export all buildflags into the environment (where they
 968 can be picked up by your build system):
 969
 970 =over
 971
 972  DPKG_EXPORT_BUILDFLAGS = 1
 973  include %PKGDATADIR%/buildflags.mk
 974
 975 =back
 976
 977 For some extra control over what is exported, you can manually export
 978 the variables (as none are exported by default):
 979
 980 =over
 981
 982  include %PKGDATADIR%/buildflags.mk
 983  export CPPFLAGS CFLAGS LDFLAGS
 984
 985 =back
 986
 987 And you can of course pass the flags to commands manually:
 988
 989 =over
 990
 991  include %PKGDATADIR%/buildflags.mk
 992  build-arch:
 993         $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
 994
 995 =back