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 See the L</FEATURE AREAS> section for more details about the currently
 243 recognized areas.
 244 Exits with 0 if the area is known otherwise exits with 1.
 245
 246 The output is in RFC822 format, with one section per feature.
 247 For example:
 248
 249  Feature: pie
 250  Enabled: yes
 251  Builtin: yes
 252
 253  Feature: stackprotector
 254  Enabled: yes
 255
 256 =item B<--help>
 257
 258 Show the usage message and exit.
 259
 260 =item B<--version>
 261
 262 Show the version and exit.
 263
 264 =back
 265
 266 =head1 SUPPORTED FLAGS
 267
 268 =over
 269
 270 =item B<ASFLAGS>
 271
 272 Options for the host assembler.
 273 Default value: empty.
 274 Since dpkg 1.21.0.
 275
 276 =item B<CFLAGS>
 277
 278 Options for the host C compiler.
 279 The default value set by the vendor
 280 includes B<-g> and the default optimization level (B<-O2> usually,
 281 or B<-O0> if the B<DEB_BUILD_OPTIONS> environment variable defines
 282 I<noopt>).
 283
 284 =item B<CPPFLAGS>
 285
 286 Options for the host C preprocessor.
 287 Default value: empty.
 288
 289 =item B<CXXFLAGS>
 290
 291 Options for the host C++ compiler.
 292 Same as B<CFLAGS>.
 293
 294 =item B<OBJCFLAGS>
 295
 296 Options for the host Objective C compiler.
 297 Same as B<CFLAGS>.
 298 Since dpkg 1.17.7.
 299
 300 =item B<OBJCXXFLAGS>
 301
 302 Options for the host Objective C++ compiler.
 303 Same as B<CXXFLAGS>.
 304 Since dpkg 1.17.7.
 305
 306 =item B<DFLAGS>
 307
 308 Options for the host D compiler (ldc or gdc).
 309 Since dpkg 1.20.6.
 310
 311 =item B<FFLAGS>
 312
 313 Options for the host Fortran 77 compiler.
 314 A subset of B<CFLAGS>.
 315
 316 =item B<FCFLAGS>
 317
 318 Options for the host Fortran 9x compiler.
 319 Same as B<FFLAGS>.
 320 Since dpkg 1.17.7.
 321
 322 =item B<LDFLAGS>
 323
 324 Options passed to the host compiler when linking executables or shared
 325 objects (if the linker is called directly, then
 326 B<-Wl>
 327 and
 328 B<,>
 329 have to be stripped from these options).
 330 Default value: empty.
 331
 332 =item B<ASFLAGS_FOR_BUILD>
 333
 334 Options for the build assembler.
 335 Default value: empty.
 336 Since dpkg 1.22.1.
 337
 338 =item B<CFLAGS_FOR_BUILD>
 339
 340 Options for the build C compiler.
 341 The default value set by the vendor includes B<-g> and the default
 342 optimization level (B<-O2> usually, or B<-O0> if the B<DEB_BUILD_OPTIONS>
 343 environment variable defines I<noopt>).
 344 Since dpkg 1.22.1.
 345
 346 =item B<CPPFLAGS_FOR_BUILD>
 347
 348 Options for the build C preprocessor.
 349 Default value: empty.
 350 Since dpkg 1.22.1.
 351
 352 =item B<CXXFLAGS_FOR_BUILD>
 353
 354 Options for the build C++ compiler.
 355 Same as B<CFLAGS_FOR_BUILD>.
 356 Since dpkg 1.22.1.
 357
 358 =item B<OBJCFLAGS_FOR_BUILD>
 359
 360 Options for the build Objective C compiler.
 361 Same as B<CFLAGS_FOR_BUILD>.
 362 Since dpkg 1.22.1.
 363
 364 =item B<OBJCXXFLAGS_FOR_BUILD>
 365
 366 Options for the build Objective C++ compiler.
 367 Same as B<CXXFLAGS_FOR_BUILD>.
 368 Since dpkg 1.22.1.
 369
 370 =item B<DFLAGS_FOR_BUILD>
 371
 372 Options for the build D compiler (ldc or gdc).
 373 Since dpkg 1.22.1.
 374
 375 =item B<FFLAGS_FOR_BUILD>
 376
 377 Options for the build Fortran 77 compiler.
 378 A subset of B<CFLAGS_FOR_BUILD>.
 379 Since dpkg 1.22.1.
 380
 381 =item B<FCFLAGS_FOR_BUILD>
 382
 383 Options for the build Fortran 9x compiler.
 384 Same as B<FFLAGS_FOR_BUILD>.
 385 Since dpkg 1.22.1.
 386
 387 =item B<LDFLAGS_FOR_BUILD>
 388
 389 Options passed to the build compiler when linking executables or shared
 390 objects (if the linker is called directly, then B<-Wl> and B<,> have to
 391 be stripped from these options).
 392 Default value: empty.
 393 Since dpkg 1.22.1.
 394
 395 =back
 396
 397 New flags might be added in the future if the need arises (for example
 398 to support other languages).
 399
 400 =head1 FEATURE AREAS
 401
 402 Feature areas are currently vendor specific,
 403 and the ones described below are only recognized on Debian and derivatives.
 404
 405 Each area feature can be enabled and disabled in the B<DEB_BUILD_OPTIONS>
 406 and B<DEB_BUILD_MAINT_OPTIONS> environment variable's area value with the
 407 ‘B<+>’ and ‘B<->’ modifier.
 408 Following the general syntax of these variables
 409 (described in L<dpkg-buildpackage(1)>),
 410 multiple feature areas can be specified separated by spaces,
 411 where each get feature specifiers as mandatory parameters after an
 412 equal sign (‘B<=>’).
 413 The feature specifiers are comma-separated and parsed from left to right,
 414 where the settings within the same feature specifier override previous ones,
 415 even if the feature specifiers are split across multiple space-separated
 416 feature area settings for the same area.
 417
 418 For example, to enable the B<hardening> “pie” feature and disable the
 419 “fortify” feature you can do this in B<debian/rules>:
 420
 421     export DEB_BUILD_MAINT_OPTIONS = hardening=+pie,-fortify
 422
 423 The special feature B<all> (valid in any area) can be used to enable or
 424 disable all area features at the same time.
 425 Thus disabling everything in the B<hardening> area and enabling only
 426 “format” and “fortify” can be achieved with:
 427
 428     export DEB_BUILD_MAINT_OPTIONS = hardening=-all,+format,+fortify
 429
 430 Multiple feature areas can be set:
 431
 432     export DEB_BUILD_MAINT_OPTIONS = hardening=+pie abi=+lfs
 433
 434 The override behavior applies as much to the B<all> special feature,
 435 as to specific features,
 436 which should allow for composition.
 437 Thus to enable “lfs” in the B<abi> area, and only “pie” and “fortify”
 438 in the B<hardening> area, but “format” only when CONDITION is defined,
 439 this could be done with:
 440
 441     export DEB_BUILD_MAINT_OPTIONS = hardening=-all,+pie,+format abi=+lfs
 442     …
 443     DEB_BUILD_MAINT_OPTIONS += hardening=+fortify
 444     ifdef CONDITION
 445     DEB_BUILD_MAINT_OPTIONS += hardening=-format
 446     endif
 447
 448 =head2 abi
 449
 450 Several compile-time options (detailed below) can be used to enable features
 451 that can change the ABI of a package, but cannot be enabled by default due to
 452 backwards compatibility reasons unless coordinated or checked individually.
 453
 454 =over
 455
 456 =item B<lfs>
 457
 458 This setting (since dpkg 1.22.0; disabled by default) enables
 459 Large File Support on 32-bit architectures where their ABI does
 460 not include LFS by default, by adding
 461 B<-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64> to B<CPPFLAGS>.
 462
 463 When this feature is enabled it will override the value from the same
 464 feature in the B<future> feature area.
 465
 466 =item B<time64>
 467
 468 This setting (since dpkg 1.22.0; enabled by default except for i386,
 469 hurd-i386 and kfreebsd-i386 since dpkg 1.22.5) enables 64-bit time_t support
 470 on 32-bit architectures where their ABI does not include it by default,
 471 by adding B<-D_TIME_BITS=64> to B<CPPFLAGS>.
 472 This setting automatically enables the B<lfs> feature from the B<abi>
 473 feature area.
 474
 475 If the setting is enabled explicitly then it gets enabled on all
 476 architectures including i386 but not hurd-i386 nor kfreebsd-i386
 477 (where the kernel does not have time64 interfaces),
 478 ignoring the binary backwards compatibility default.
 479
 480 It is also enabled by default by gcc on the
 481 armel,
 482 armhf,
 483 hppa,
 484 m68k,
 485 mips,
 486 mipsel,
 487 powerpc
 488 and
 489 sh4
 490 Debian architectures,
 491 where disabling the feature will add instead
 492 B<-U_LARGEFILE_SOURCE -U_FILE_OFFSET_BITS -U_TIME_BITS> to B<CPPFLAGS>.
 493
 494 =back
 495
 496 =head2 future
 497
 498 Several compile-time options (detailed below) can be used to enable features
 499 that should be enabled by default, but cannot due to backwards compatibility
 500 reasons.
 501
 502 =over
 503
 504 =item B<lfs>
 505
 506 This setting (since dpkg 1.19.0; disabled by default) is now an alias
 507 for the B<lfs> feature in the B<abi> area, use that instead.
 508 The feature from the B<abi> area overrides this setting.
 509
 510 =back
 511
 512 =head2 qa
 513
 514 Several compile-time options (detailed below) can be used to help detect
 515 problems in the source code or build system.
 516
 517 =over
 518
 519 =item B<bug-implicit-func>
 520
 521 This setting (since dpkg 1.22.3; enabled by default since dpkg 1.22.6) adds
 522 B<-Werror=implicit-function-declaration> to B<CFLAGS>.
 523
 524 =item B<bug>
 525
 526 This setting (since dpkg 1.17.4; disabled by default) adds any warning
 527 option that reliably detects problematic source code.
 528 The warnings are fatal.
 529 The only currently supported flags are B<CFLAGS> and B<CXXFLAGS>
 530 with flags set to B<-Werror=array-bounds>, B<-Werror=clobbered>,
 531 B<-Werror=implicit-function-declaration> and
 532 B<-Werror=volatile-register-var>.
 533
 534 This feature handles B<-Werror=implicit-function-declaration> via
 535 the B<bug-implicit-func> feature, if that has not been specified.
 536
 537 =item B<canary>
 538
 539 This setting (since dpkg 1.17.14; disabled by default) adds dummy canary
 540 options to the build flags, so that the build logs can be checked for how
 541 the build flags propagate and to allow finding any omission of normal
 542 build flag settings.
 543 The only currently supported flags are B<CPPFLAGS>, B<CFLAGS>,
 544 B<OBJCFLAGS>, B<CXXFLAGS> and B<OBJCXXFLAGS> with flags set
 545 to B<-D__DEB_CANARY_>I<flag>_I<random-id>B<__>, and
 546 B<LDFLAGS> set to B<-Wl,-z,deb-canary->I<random-id>.
 547
 548 =back
 549
 550 =head2 optimize
 551
 552 Several compile-time options (detailed below) can be used to help optimize
 553 a resulting binary (since dpkg 1.21.0).
 554 B<Note>: Enabling B<all> these options can result in unreproducible binary
 555 artifacts.
 556
 557 =over
 558
 559 =item B<lto>
 560
 561 This setting (since dpkg 1.21.0; disabled by default) enables
 562 Link Time Optimization by adding B<-flto=auto -ffat-lto-objects> to
 563 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 564 B<FFLAGS>, B<FCFLAGS> and B<LDFLAGS>.
 565
 566 =back
 567
 568 =head2 sanitize
 569
 570 Several compile-time options (detailed below) can be used to help sanitize
 571 a resulting binary against memory corruptions, memory leaks, use after free,
 572 threading data races and undefined behavior bugs.
 573 B<Note>: These options should B<not> be used for production builds
 574 as they can reduce reliability for conformant code, reduce security or
 575 even functionality.
 576
 577 =over
 578
 579 =item B<address>
 580
 581 This setting (since dpkg 1.18.0; disabled by default) adds
 582 B<-fsanitize=address> to
 583 B<LDFLAGS> and B<-fsanitize=address -fno-omit-frame-pointer> to
 584 B<CFLAGS> and B<CXXFLAGS>.
 585
 586 =item B<thread>
 587
 588 This setting (since dpkg 1.18.0; disabled by default) adds
 589 B<-fsanitize=thread> to
 590 B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>.
 591
 592 =item B<leak>
 593
 594 This setting (since dpkg 1.18.0; disabled by default) adds
 595 B<-fsanitize=leak> to
 596 B<LDFLAGS>.
 597 It gets automatically disabled if either the B<address>
 598 or the B<thread> features are enabled, as they imply it.
 599
 600 =item B<undefined>
 601
 602 This setting (since dpkg 1.18.0; disabled by default) adds
 603 B<-fsanitize=undefined> to
 604 B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>.
 605
 606 =back
 607
 608 =head2 hardening
 609
 610 Several compile-time options (detailed below) can be used to help harden
 611 a resulting binary against memory corruption attacks, or provide
 612 additional warning messages during compilation.
 613 Except as noted below, these are enabled by default for architectures
 614 that support them.
 615
 616 =over
 617
 618 =item B<format>
 619
 620 This setting (since dpkg 1.16.1; enabled by default) adds
 621 B<-Wformat -Werror=format-security>
 622 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS> and B<OBJCXXFLAGS>.
 623 This will warn about improper format
 624 string uses, and will fail when format functions are used in a way
 625 that represent possible security problems.
 626 At present, this warns about
 627 calls to B<printf> and B<scanf> functions where the format string is
 628 not a string literal and there are no format arguments, as in
 629 B<printf(foo);> instead of B<printf("%s", foo);>
 630 This may be a security hole if the format string came from untrusted
 631 input and contains ‘%n’.
 632
 633 =item B<fortify>
 634
 635 This setting (since dpkg 1.16.1; enabled by default) adds
 636 B<-D_FORTIFY_SOURCE=2>
 637 to B<CPPFLAGS>.
 638 During code generation the compiler
 639 knows a great deal of information about buffer sizes (where possible), and
 640 attempts to replace insecure unlimited length buffer function calls with
 641 length-limited ones.
 642 This is especially useful for old, crufty code.
 643 Additionally, format strings in writable memory that contain ‘%n’ are
 644 blocked.
 645 If an application depends on such a format string, it will need
 646 to be worked around.
 647
 648 Note that for this option to have any effect, the source must also
 649 be compiled with B<-O1> or higher.
 650 If the environment variable
 651 B<DEB_BUILD_OPTIONS> contains I<noopt>, then B<fortify>
 652 support will be disabled, due to new warnings being issued by
 653 glibc 2.16 and later.
 654
 655 =item B<stackprotector>
 656
 657 This setting (since dpkg 1.16.1; enabled by default if stackprotectorstrong
 658 is not in use) adds B<-fstack-protector --param=ssp-buffer-size=4>
 659 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 660 B<FFLAGS> and B<FCFLAGS>.
 661 This adds safety checks against stack
 662 overwrites.
 663 This renders many potential code injection attacks into aborting situations.
 664 In the best case this turns code injection
 665 vulnerabilities into denial of service or into non-issues (depending on
 666 the application).
 667
 668 This feature requires linking against glibc (or another provider of
 669 B<__stack_chk_fail>), so needs to be disabled when building with
 670 B<-nostdlib> or B<-ffreestanding> or similar.
 671
 672 =item B<stackprotectorstrong>
 673
 674 This setting (since dpkg 1.17.11; enabled by default) adds
 675 B<-fstack-protector-strong>
 676 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 677 B<FFLAGS> and B<FCFLAGS>.
 678 This is a stronger variant of B<stackprotector>, but without significant
 679 performance penalties.
 680
 681 Disabling B<stackprotector> will also disable this setting.
 682
 683 This feature has the same requirements as B<stackprotector>, and in
 684 addition also requires gcc 4.9 and later.
 685
 686 =item B<stackclash>
 687
 688 This setting (since dpkg 1.22.0; enabled by default) adds
 689 B<-fstack-clash-protection> on B<amd64>, B<arm64>, B<armhf> and B<armel> to
 690 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 691 B<FFLAGS> and B<FCFLAGS>.
 692 This adds code to prevent stack clash style attacks.
 693
 694 =item B<branch>
 695
 696 This setting (since dpkg 1.22.0; enabled by default) adds B<-fcf-protection>
 697 on B<amd64> and B<-mbranch-protection=standard> on B<arm64> to
 698 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 699 B<FFLAGS> and B<FCFLAGS>.
 700 This adds branch protection to indirect calls, jumps and returns to check
 701 whether these are valid at run-time.
 702
 703 =item B<relro>
 704
 705 This setting (since dpkg 1.16.1; enabled by default) adds
 706 B<-Wl,-z,relro>
 707 to B<LDFLAGS>.
 708 During program load,
 709 several ELF memory sections need to be written to by the linker.
 710 This flags the loader to turn these sections read-only before turning over
 711 control to the program.
 712 Most notably this prevents GOT overwrite attacks.
 713 If this option is disabled,
 714 B<bindnow> will become disabled as well.
 715
 716 =item B<bindnow>
 717
 718 This setting (since dpkg 1.16.1; disabled by default) adds
 719 B<-Wl,-z,now>
 720 to B<LDFLAGS>.
 721 During program load, all dynamic symbols are resolved,
 722 allowing for the entire PLT to be marked read-only (due to B<relro>
 723 above).
 724 The option cannot become enabled if B<relro> is not enabled.
 725
 726 =item B<pie>
 727
 728 This setting (since dpkg 1.16.1; with no global default since dpkg 1.18.23,
 729 as it is enabled
 730 by default now by gcc on the amd64, arm64, armel, armhf, hurd-i386, i386,
 731 kfreebsd-amd64, kfreebsd-i386, mips, mipsel, mips64el, powerpc, ppc64,
 732 ppc64el, riscv64, s390x, sparc and sparc64 Debian architectures) adds
 733 the required options to enable or disable PIE via gcc specs files, if
 734 needed, depending on whether gcc injects on that architecture the flags
 735 by itself or not.
 736 When the setting is enabled and gcc injects the flags, it adds nothing.
 737 When the setting is enabled and gcc does not inject the flags, it adds
 738 B<-fPIE> (via I<%PKGDATADIR%/pie-compiler.specs>) to B<CFLAGS>,
 739 B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 740 B<FFLAGS> and B<FCFLAGS>, and
 741 B<-fPIE -pie> (via I<%PKGDATADIR%/pie-link.specs>) to B<LDFLAGS>.
 742 When the setting is disabled and gcc injects the flags, it adds
 743 B<-fno-PIE> (via I<%PKGDATADIR%/no-pie-compile.specs>) to B<CFLAGS>,
 744 B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 745 B<FFLAGS> and B<FCFLAGS>, and
 746 B<-fno-PIE -no-pie> (via I<%PKGDATADIR%/no-pie-link.specs>) to
 747 B<LDFLAGS>.
 748
 749 Position Independent Executable (PIE) is needed to take advantage of
 750 Address Space Layout Randomization (ASLR), supported by some kernel versions.
 751 While ASLR can already be enforced for data areas in the stack and heap
 752 (brk and mmap), the code areas must be compiled as position-independent.
 753 Shared libraries already do this (B<-fPIC>), so they gain ASLR automatically,
 754 but binary .text regions need to be built as PIE to gain ASLR.
 755 When this happens, ROP (Return Oriented Programming) attacks are much
 756 harder since there are no static locations to bounce off of during a
 757 memory corruption attack.
 758
 759 PIE is not compatible with B<-fPIC>, so in general care must be taken
 760 when building shared objects.
 761 But because the PIE flags emitted get injected
 762 via gcc specs files, it should always be safe to unconditionally set them
 763 regardless of the object type being compiled or linked.
 764
 765 Static libraries can be used by programs or other shared libraries.
 766 Depending on the flags used to compile all the objects within a static
 767 library, these libraries will be usable by different sets of objects:
 768
 769 =over
 770
 771 =item none
 772
 773 Cannot be linked into a PIE program, nor a shared library.
 774
 775 =item B<-fPIE>
 776
 777 Can be linked into any program, but not a shared library (recommended).
 778
 779 =item B<-fPIC>
 780
 781 Can be linked into any program and shared library.
 782
 783 =back
 784
 785 If there is a need to set these flags manually, bypassing the gcc specs
 786 injection, there are several things to take into account.
 787 Unconditionally
 788 and explicitly passing B<-fPIE>, B<-fpie> or B<-pie> to a
 789 build-system using libtool is safe as these flags will get stripped
 790 when building shared libraries.
 791 Otherwise on projects that build both programs and shared libraries you
 792 might need to make sure that when building the shared libraries B<-fPIC>
 793 is always passed last (so that it overrides any previous B<-PIE>) to
 794 compilation flags such as B<CFLAGS>, and B<-shared> is passed last
 795 (so that it overrides any previous B<-pie>) to linking flags such as
 796 B<LDFLAGS>.
 797 B<Note>: This should not be needed with the default
 798 gcc specs machinery.
 799
 800 Additionally, since PIE is implemented via a general register, some
 801 register starved architectures (but not including i386 anymore since
 802 optimizations implemented in gcc E<gt>= 5) can see performance losses of up to
 803 15% in very text-segment-heavy application workloads; most workloads
 804 see less than 1%.
 805 Architectures with more general registers (e.g. amd64)
 806 do not see as high a worst-case penalty.
 807
 808 =back
 809
 810 =head2 reproducible
 811
 812 The compile-time options detailed below can be used to help improve
 813 build reproducibility or provide additional warning messages during
 814 compilation.
 815 Except as noted below, these are enabled by default for
 816 architectures that support them.
 817
 818 =over
 819
 820 =item B<timeless>
 821
 822 This setting (since dpkg 1.17.14; enabled by default) adds
 823 B<-Wdate-time>
 824 to B<CPPFLAGS>.
 825 This will cause warnings when the B<__TIME__>, B<__DATE__> and
 826 B<__TIMESTAMP__> macros are used.
 827
 828 =item B<fixfilepath>
 829
 830 This setting (since dpkg 1.19.1; enabled by default) adds
 831 B<-ffile-prefix-map=>I<BUILDPATH>B<=.>
 832 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 833 B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is
 834 set to the top-level directory of the package being built.
 835 This has the effect of removing the build path from any generated file.
 836
 837 If both B<fixdebugpath> and B<fixfilepath> are set, this option
 838 takes precedence, because it is a superset of the former.
 839
 840 B<Note>: If the build process captures the build flags into the resulting
 841 built objects, that will make the package unreproducible.
 842 And while disabling this option might make some of the objects reproducible
 843 again this would also require disabling B<fixdebugpath>, which might make
 844 any generated debug symbols objects unreproducible.
 845 The ideal fix is to stop capturing build flags.
 846
 847 =item B<fixdebugpath>
 848
 849 This setting (since dpkg 1.18.5; enabled by default) adds
 850 B<-fdebug-prefix-map=>I<BUILDPATH>B<=.>
 851 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
 852 B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is
 853 set to the top-level directory of the package being built.
 854 This has the effect of removing the build path from any generated debug
 855 symbols.
 856
 857 B<Note>: This feature has similar reproducible properties as B<fixfilepath>.
 858
 859 =back
 860
 861 =head1 ENVIRONMENT
 862
 863 There are 2 sets of environment variables doing the same operations, the
 864 first one (DEB_I<flag>_I<op>) should never be used within
 865 B<debian/rules>.
 866 It's meant for any user that wants to rebuild the source package with
 867 different build flags.
 868 The second set
 869 (DEB_I<flag>_MAINT_I<op>) should only be used in B<debian/rules>
 870 by package maintainers to change the resulting build flags.
 871
 872 =over
 873
 874 =item B<DEB_>I<flag>B<_SET>
 875
 876 =item B<DEB_>I<flag>B<_MAINT_SET> (since dpkg 1.16.1)
 877
 878 This variable can be used to force the value returned for the given
 879 I<flag>.
 880
 881 =item B<DEB_>I<flag>B<_STRIP> (since dpkg 1.16.1)
 882
 883 =item B<DEB_>I<flag>B<_MAINT_STRIP> (since dpkg 1.16.1)
 884
 885 This variable can be used to provide a space separated list of options
 886 that will be stripped from the set of flags returned for the given
 887 I<flag>.
 888
 889 =item B<DEB_>I<flag>B<_APPEND>
 890
 891 =item B<DEB_>I<flag>B<_MAINT_APPEND> (since dpkg 1.16.1)
 892
 893 This variable can be used to append supplementary options to the value
 894 returned for the given I<flag>.
 895
 896 =item B<DEB_>I<flag>B<_PREPEND> (since dpkg 1.16.1)
 897
 898 =item B<DEB_>I<flag>B<_MAINT_PREPEND> (since dpkg 1.16.1)
 899
 900 This variable can be used to prepend supplementary options to the value
 901 returned for the given I<flag>.
 902
 903 =item B<DEB_BUILD_OPTIONS>
 904
 905 =item B<DEB_BUILD_MAINT_OPTIONS> (since dpkg 1.16.1)
 906
 907 These variables can be used by a user or maintainer to disable/enable
 908 various area features that affect build flags.
 909 The B<DEB_BUILD_MAINT_OPTIONS> variable overrides any setting in the
 910 B<DEB_BUILD_OPTIONS> feature areas.
 911 See the L</FEATURE AREAS> section for details.
 912
 913 =item B<DEB_VENDOR>
 914
 915 This setting defines the current vendor.
 916 If not set, it will discover the current vendor by reading
 917 B<%PKGCONFDIR%/origins/default>.
 918
 919 =item B<DEB_BUILD_PATH>
 920
 921 This variable sets the build path (since dpkg 1.18.8) to use in features
 922 such as B<fixdebugpath> so that they can be controlled by the caller.
 923 This variable is currently Debian and derivatives-specific.
 924
 925 =item B<DEB_HOST_ARCH>
 926
 927 Sets the host architecture.
 928 This affects the build flags that are emitted,
 929 which is typically relevant when cross-compiling,
 930 where B<DEB_HOST_ARCH> is different to B<DEB_BUILD_ARCH>.
 931
 932 =item B<DPKG_COLORS>
 933
 934 Sets the color mode (since dpkg 1.18.5).
 935 The currently accepted values are: B<auto> (default), B<always> and
 936 B<never>.
 937
 938 =item B<DPKG_NLS>
 939
 940 If set, it will be used to decide whether to activate Native Language Support,
 941 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 942 The accepted values are: B<0> and B<1> (default).
 943
 944 =back
 945
 946 =head1 FILES
 947
 948 =head2 Configuration files
 949
 950 =over
 951
 952 =item B<%PKGCONFDIR%/buildflags.conf>
 953
 954 System wide configuration file.
 955
 956 =item B<$XDG_CONFIG_HOME/dpkg/buildflags.conf> or
 957
 958 =item B<$HOME/.config/dpkg/buildflags.conf>
 959
 960 User configuration file.
 961
 962 =back
 963
 964 =head2 Packaging support
 965
 966 =over
 967
 968 =item B<%PKGDATADIR%/buildflags.mk>
 969
 970 Makefile snippet that will load (and optionally export) all flags
 971 supported by B<dpkg-buildflags> into variables (since dpkg 1.16.1).
 972
 973 =back
 974
 975 =head1 EXAMPLES
 976
 977 To pass build flags to a build command in a Makefile:
 978
 979 =over
 980
 981  $(MAKE) $(shell dpkg-buildflags --export=cmdline)
 982
 983  ./configure $(shell dpkg-buildflags --export=cmdline)
 984
 985 =back
 986
 987 To set build flags in a shell script or shell fragment, B<eval> can be
 988 used to interpret the output and to export the flags in the environment:
 989
 990 =over
 991
 992  eval "$(dpkg-buildflags --export=sh)" && make
 993
 994 =back
 995
 996 or to set the positional parameters to pass to a command:
 997
 998 =over
 999
1000  eval "set -- $(dpkg-buildflags --export=cmdline)"
1001  for dir in a b c; do (cd $dir && ./configure "$@" && make); done
1002
1003 =back
1004
1005 =head2 Usage in debian/rules
1006
1007 You should call B<dpkg-buildflags> or include B<buildflags.mk>
1008 from the B<debian/rules> file to obtain the needed build flags to
1009 pass to the build system.
1010 Note that older versions of B<dpkg-buildpackage> (before dpkg 1.16.1)
1011 exported these flags automatically.
1012 However, you should not rely on this,
1013 since this breaks manual invocation of B<debian/rules>.
1014
1015 For packages with autoconf-like build systems, you can pass the relevant
1016 options to configure or L<make(1)> directly, as shown above.
1017
1018 For other build systems, or when you need more fine-grained control
1019 about which flags are passed where, you can use B<--get>.
1020 Or you
1021 can include B<buildflags.mk> instead, which takes care of calling
1022 B<dpkg-buildflags> and storing the build flags in make variables.
1023
1024 If you want to export all buildflags into the environment (where they
1025 can be picked up by your build system):
1026
1027 =over
1028
1029  DPKG_EXPORT_BUILDFLAGS = 1
1030  include %PKGDATADIR%/buildflags.mk
1031
1032 =back
1033
1034 For some extra control over what is exported, you can manually export
1035 the variables (as none are exported by default):
1036
1037 =over
1038
1039  include %PKGDATADIR%/buildflags.mk
1040  export CPPFLAGS CFLAGS LDFLAGS
1041
1042 =back
1043
1044 And you can of course pass the flags to commands manually:
1045
1046 =over
1047
1048  include %PKGDATADIR%/buildflags.mk
1049  build-arch:
1050         $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
1051
1052 =back