1 # dpkg manual page - dpkg-buildflags(1)
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>
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.
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.
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/>.
24 dpkg-buildflags - returns build flags to use during package build
29 [I<option>...] [I<command>]
33 B<dpkg-buildflags> is a tool to retrieve compilation flags to use during
34 build of Debian packages.
36 The default flags are defined by the vendor but they can be
37 extended/overridden in several ways:
43 system-wide with B<%PKGCONFDIR%/buildflags.conf>;
47 for the current user with B<$XDG_CONFIG_HOME/dpkg/buildflags.conf>
48 where B<$XDG_CONFIG_HOME> defaults to B<$HOME/.config>;
52 temporarily by the user with environment variables (see section
57 dynamically by the package maintainer with environment variables set via
58 B<debian/rules> (see section B<ENVIRONMENT>).
62 The configuration files can contain four types of directives:
66 =item B<SET> I<flag> I<value>
68 Override the flag named I<flag> to have the value I<value>.
70 =item B<STRIP> I<flag> I<value>
72 Strip from the flag named I<flag> all the build flags listed in I<value>.
75 =item B<APPEND> I<flag> I<value>
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.
80 =item B<PREPEND> I<flag> I<value>
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.
88 The configuration files can contain comments on lines starting with a hash
89 (#). Empty lines are also ignored.
97 Print to standard output all compilation flags and their values. It prints
98 one flag per line separated from its value by an equal sign
99 (“I<flag>=I<value>”). This is the default action.
103 Print the list of flags supported by the current vendor
104 (one per line). See the B<SUPPORTED FLAGS> section for more
105 information about them.
109 Display any information that can be useful to explain the behavior of
110 B<dpkg-buildflags> (since dpkg 1.16.5): relevant environment variables,
111 current vendor, state of all feature flags.
112 Also print the resulting compiler flags with their origin.
114 This is intended to be run from B<debian/rules>, so that the build log
115 keeps a clear trace of the build flags used. This can be useful to diagnose
116 problems related to them.
118 =item B<--export=>I<format>
120 Print to standard output commands that can be used to export all the
121 compilation flags for some particular tool. If the I<format> value is not
122 given, B<sh> is assumed. Only compilation flags starting with an
123 upper case character are included, others are assumed to not be suitable
124 for the environment. Supported formats:
130 Shell commands to set and export all the compilation flags in the
131 environment. The flag values are quoted so the output is ready for
132 evaluation by a shell.
136 Arguments to pass to a build program's command line to use all the
137 compilation flags (since dpkg 1.17.0). The flag values are quoted in
142 This is a legacy alias for B<cmdline>.
146 Make directives to set and export all the compilation flags in the
147 environment. Output can be written to a Makefile fragment and
148 evaluated using an B<include> directive.
152 =item B<--get> I<flag>
154 Print the value of the flag on standard output. Exits with 0
155 if the flag is known otherwise exits with 1.
157 =item B<--origin> I<flag>
159 Print the origin of the value that is returned by B<--get>. Exits
160 with 0 if the flag is known otherwise exits with 1. The origin can be one
161 of the following values:
167 the original flag set by the vendor is returned;
171 the flag is set/modified by a system-wide configuration;
175 the flag is set/modified by a user-specific configuration;
179 the flag is set/modified by an environment-specific configuration.
185 Print any information that can be useful to explain the behavior of the
186 program: current vendor, relevant environment variables, feature areas,
187 state of all feature flags, whether a feature is handled as a builtin
188 default by the compiler (since dpkg 1.21.14),
189 and the compiler flags with their origin (since dpkg 1.19.0).
195 DEB_CFLAGS_SET=-O0 -Wall
219 Value: -D_FORTIFY_SOURCE=2
222 =item B<--query-features> I<area>
224 Print the features enabled for a given area (since dpkg 1.16.2).
225 If the feature is handled (even if only on some architectures) as a
226 builtin default by the compiler, then a B<Builtin> field is printed
227 (since dpkg 1.21.14).
228 The only currently recognized
229 areas on Debian and derivatives are B<future>, B<qa>, B<reproducible>,
230 B<sanitize> and B<hardening>, see the B<FEATURE AREAS>
231 section for more details.
232 Exits with 0 if the area is known otherwise exits with 1.
234 The output is in RFC822 format, with one section per feature.
241 Feature: stackprotector
246 Show the usage message and exit.
250 Show the version and exit.
254 =head1 SUPPORTED FLAGS
260 Options for the assembler. Default value: empty. Since dpkg 1.21.0.
264 Options for the C compiler. The default value set by the vendor
265 includes B<-g> and the default optimization level (B<-O2> usually,
266 or B<-O0> if the B<DEB_BUILD_OPTIONS> environment variable defines
271 Options for the C preprocessor. Default value: empty.
275 Options for the C++ compiler. Same as B<CFLAGS>.
279 Options for the Objective C compiler. Same as B<CFLAGS>.
284 Options for the Objective C++ compiler. Same as B<CXXFLAGS>.
289 Options for the GNU Java compiler (gcj). A subset of B<CFLAGS>.
293 Options for the D compiler (ldc or gdc). Since dpkg 1.20.6.
297 Options for the Fortran 77 compiler. A subset of B<CFLAGS>.
301 Options for the Fortran 9x compiler. Same as B<FFLAGS>.
306 Options passed to the compiler when linking executables or shared
307 objects (if the linker is called directly, then
311 have to be stripped from these options). Default value: empty.
315 New flags might be added in the future if the need arises (for example
316 to support other languages).
320 Each area feature can be enabled and disabled in the B<DEB_BUILD_OPTIONS>
321 and B<DEB_BUILD_MAINT_OPTIONS> environment variable's area value with the
322 ‘B<+>’ and ‘B<->’ modifier.
323 For example, to enable the B<hardening> “pie” feature and disable the
324 “fortify” feature you can do this in B<debian/rules>:
326 export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
328 The special feature B<all> (valid in any area) can be used to enable or
329 disable all area features at the same time.
330 Thus disabling everything in the B<hardening> area and enabling only
331 “format” and “fortify” can be achieved with:
333 export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
337 Several compile-time options (detailed below) can be used to enable features
338 that should be enabled by default, but cannot due to backwards compatibility
345 This setting (since dpkg 1.10.0; disabled by default) enables
346 Large File Support on 32-bit architectures where their ABI does
347 not include LFS by default, by adding
348 B<-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64> to B<CPPFLAGS>.
352 This setting (since dpkg 1.22.0; disabled by default) enables 64-bit time_t
353 support on 32-bit architectures where their ABI does not include it by
354 default, by adding B<-D_TIME_BITS=64> to B<CPPFLAGS>.
355 This setting automatically enables the B<lfs> feature as it requires it.
361 Several compile-time options (detailed below) can be used to help detect
362 problems in the source code or build system.
368 This setting (since dpkg 1.17.4; disabled by default) adds any warning
369 option that reliably detects problematic source code.
370 The warnings are fatal.
371 The only currently supported flags are B<CFLAGS> and B<CXXFLAGS>
372 with flags set to B<-Werror=array-bounds>, B<-Werror=clobbered>,
373 B<-Werror=implicit-function-declaration> and
374 B<-Werror=volatile-register-var>.
378 This setting (since dpkg 1.17.14; disabled by default) adds dummy canary
379 options to the build flags, so that the build logs can be checked for how
380 the build flags propagate and to allow finding any omission of normal
382 The only currently supported flags are B<CPPFLAGS>, B<CFLAGS>,
383 B<OBJCFLAGS>, B<CXXFLAGS> and B<OBJCXXFLAGS> with flags set
384 to B<-D__DEB_CANARY_>I<flag>_I<random-id>B<__>, and
385 B<LDFLAGS> set to B<-Wl,-z,deb-canary->I<random-id>.
391 Several compile-time options (detailed below) can be used to help optimize
392 a resulting binary (since dpkg 1.21.0).
393 B<Note>: enabling B<all> these options can result in unreproducible binary
400 This setting (since dpkg 1.21.0; disabled by default) enables
401 Link Time Optimization by adding B<-flto=auto -ffat-lto-objects> to
402 B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, B<GCJFLAGS>,
403 B<FFLAGS>, B<FCFLAGS> and B<LDFLAGS>.
409 Several compile-time options (detailed below) can be used to help sanitize
410 a resulting binary against memory corruptions, memory leaks, use after free,
411 threading data races and undefined behavior bugs.
412 B<Note>: these options should B<not> be used for production builds
413 as they can reduce reliability for conformant code, reduce security or
420 This setting (since dpkg 1.18.0; disabled by default) adds
421 B<-fsanitize=address> to
422 B<LDFLAGS> and B<-fsanitize=address -fno-omit-frame-pointer> to
423 B<CFLAGS> and B<CXXFLAGS>.
427 This setting (since dpkg 1.18.0; disabled by default) adds
428 B<-fsanitize=thread> to
429 B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>.
433 This setting (since dpkg 1.18.0; disabled by default) adds
434 B<-fsanitize=leak> to
435 B<LDFLAGS>. It gets automatically disabled if either the B<address>
436 or the B<thread> features are enabled, as they imply it.
440 This setting (since dpkg 1.18.0; disabled by default) adds
441 B<-fsanitize=undefined> to
442 B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>.
448 Several compile-time options (detailed below) can be used to help harden
449 a resulting binary against memory corruption attacks, or provide
450 additional warning messages during compilation.
451 Except as noted below, these are enabled by default for architectures
458 This setting (since dpkg 1.16.1; enabled by default) adds
459 B<-Wformat -Werror=format-security>
460 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS> and B<OBJCXXFLAGS>.
461 This will warn about improper format
462 string uses, and will fail when format functions are used in a way
463 that represent possible security problems. At present, this warns about
464 calls to B<printf> and B<scanf> functions where the format string is
465 not a string literal and there are no format arguments, as in
466 B<printf(foo);> instead of B<printf("%s", foo);>
467 This may be a security hole if the format string came from untrusted
468 input and contains ‘%n’.
472 This setting (since dpkg 1.16.1; enabled by default) adds
473 B<-D_FORTIFY_SOURCE=2>
474 to B<CPPFLAGS>. During code generation the compiler
475 knows a great deal of information about buffer sizes (where possible), and
476 attempts to replace insecure unlimited length buffer function calls with
477 length-limited ones. This is especially useful for old, crufty code.
478 Additionally, format strings in writable memory that contain ‘%n’ are
479 blocked. If an application depends on such a format string, it will need
482 Note that for this option to have any effect, the source must also
483 be compiled with B<-O1> or higher. If the environment variable
484 B<DEB_BUILD_OPTIONS> contains I<noopt>, then B<fortify>
485 support will be disabled, due to new warnings being issued by
486 glibc 2.16 and later.
488 =item B<stackprotector>
490 This setting (since dpkg 1.16.1; enabled by default if stackprotectorstrong
491 is not in use) adds B<-fstack-protector --param=ssp-buffer-size=4>
492 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
493 B<GCJFLAGS>, B<FFLAGS> and B<FCFLAGS>.
494 This adds safety checks against stack
495 overwrites. This renders many potential code injection attacks into
496 aborting situations. In the best case this turns code injection
497 vulnerabilities into denial of service or into non-issues (depending on
500 This feature requires linking against glibc (or another provider of
501 B<__stack_chk_fail>), so needs to be disabled when building with
502 B<-nostdlib> or B<-ffreestanding> or similar.
504 =item B<stackprotectorstrong>
506 This setting (since dpkg 1.17.11; enabled by default) adds
507 B<-fstack-protector-strong>
508 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
509 B<GCJFLAGS>, B<FFLAGS> and B<FCFLAGS>.
510 This is a stronger variant of B<stackprotector>, but without significant
511 performance penalties.
513 Disabling B<stackprotector> will also disable this setting.
515 This feature has the same requirements as B<stackprotector>, and in
516 addition also requires gcc 4.9 and later.
520 This setting (since dpkg 1.16.1; enabled by default) adds
522 to B<LDFLAGS>. During program load, several ELF memory sections need
523 to be written to by the linker. This flags the loader to turn these
524 sections read-only before turning over control to the program. Most
525 notably this prevents GOT overwrite attacks. If this option is disabled,
526 B<bindnow> will become disabled as well.
530 This setting (since dpkg 1.16.1; disabled by default) adds
532 to B<LDFLAGS>. During program load, all dynamic symbols are resolved,
533 allowing for the entire PLT to be marked read-only (due to B<relro>
534 above). The option cannot become enabled if B<relro> is not enabled.
538 This setting (since dpkg 1.16.1; with no global default since dpkg 1.18.23,
540 by default now by gcc on the amd64, arm64, armel, armhf, hurd-i386, i386,
541 kfreebsd-amd64, kfreebsd-i386, mips, mipsel, mips64el, powerpc, ppc64,
542 ppc64el, riscv64, s390x, sparc and sparc64 Debian architectures) adds
543 the required options to enable or disable PIE via gcc specs files, if
544 needed, depending on whether gcc injects on that architecture the flags
546 When the setting is enabled and gcc injects the flags, it adds nothing.
547 When the setting is enabled and gcc does not inject the flags, it adds
548 B<-fPIE> (via I<%PKGDATADIR%/pie-compiler.specs>) to B<CFLAGS>,
549 B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, B<GCJFLAGS>,
550 B<FFLAGS> and B<FCFLAGS>, and
551 B<-fPIE -pie> (via I<%PKGDATADIR%/pie-link.specs>) to B<LDFLAGS>.
552 When the setting is disabled and gcc injects the flags, it adds
553 B<-fno-PIE> (via I<%PKGDATADIR%/no-pie-compile.specs>) to B<CFLAGS>,
554 B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, B<GCJFLAGS>,
555 B<FFLAGS> and B<FCFLAGS>, and
556 B<-fno-PIE -no-pie> (via I<%PKGDATADIR%/no-pie-link.specs>) to
559 Position Independent Executable (PIE) is needed to take advantage of
560 Address Space Layout Randomization (ASLR), supported by some kernel versions.
561 While ASLR can already be enforced for data areas in the stack and heap
562 (brk and mmap), the code areas must be compiled as position-independent.
563 Shared libraries already do this (B<-fPIC>), so they gain ASLR automatically,
564 but binary .text regions need to be built as PIE to gain ASLR.
565 When this happens, ROP (Return Oriented Programming) attacks are much
566 harder since there are no static locations to bounce off of during a
567 memory corruption attack.
569 PIE is not compatible with B<-fPIC>, so in general care must be taken
570 when building shared objects. But because the PIE flags emitted get injected
571 via gcc specs files, it should always be safe to unconditionally set them
572 regardless of the object type being compiled or linked.
574 Static libraries can be used by programs or other shared libraries.
575 Depending on the flags used to compile all the objects within a static
576 library, these libraries will be usable by different sets of objects:
582 Cannot be linked into a PIE program, nor a shared library.
586 Can be linked into any program, but not a shared library (recommended).
590 Can be linked into any program and shared library.
594 If there is a need to set these flags manually, bypassing the gcc specs
595 injection, there are several things to take into account. Unconditionally
596 and explicitly passing B<-fPIE>, B<-fpie> or B<-pie> to a
597 build-system using libtool is safe as these flags will get stripped
598 when building shared libraries.
599 Otherwise on projects that build both programs and shared libraries you
600 might need to make sure that when building the shared libraries B<-fPIC>
601 is always passed last (so that it overrides any previous B<-PIE>) to
602 compilation flags such as B<CFLAGS>, and B<-shared> is passed last
603 (so that it overrides any previous B<-pie>) to linking flags such as
604 B<LDFLAGS>. B<Note>: This should not be needed with the default
607 Additionally, since PIE is implemented via a general register, some
608 register starved architectures (but not including i386 anymore since
609 optimizations implemented in gcc E<gt>= 5) can see performance losses of up to
610 15% in very text-segment-heavy application workloads; most workloads
611 see less than 1%. Architectures with more general registers (e.g. amd64)
612 do not see as high a worst-case penalty.
618 The compile-time options detailed below can be used to help improve
619 build reproducibility or provide additional warning messages during
620 compilation. Except as noted below, these are enabled by default for
621 architectures that support them.
627 This setting (since dpkg 1.17.14; enabled by default) adds
630 This will cause warnings when the B<__TIME__>, B<__DATE__> and
631 B<__TIMESTAMP__> macros are used.
635 This setting (since dpkg 1.19.1; enabled by default) adds
636 B<-ffile-prefix-map=>I<BUILDPATH>B<=.>
637 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
638 B<GCJFLAGS>, B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is
639 set to the top-level directory of the package being built.
640 This has the effect of removing the build path from any generated file.
642 If both B<fixdebugpath> and B<fixfilepath> are set, this option
643 takes precedence, because it is a superset of the former.
645 B<Note>: If the build process captures the build flags into the resulting
646 built objects, that will make the package unreproducible.
647 And while disabling this option might make some of the objects reproducible
648 again this would also require disabling B<fixdebugpath>, which might make
649 any generated debug symbols objects unreproducible.
650 The ideal fix is to stop capturing build flags.
652 =item B<fixdebugpath>
654 This setting (since dpkg 1.18.5; enabled by default) adds
655 B<-fdebug-prefix-map=>I<BUILDPATH>B<=.>
656 to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>,
657 B<GCJFLAGS>, B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is
658 set to the top-level directory of the package being built.
659 This has the effect of removing the build path from any generated debug
662 B<Note>: This feature has similar reproducible properties as B<fixfilepath>.
668 There are 2 sets of environment variables doing the same operations, the
669 first one (DEB_I<flag>_I<op>) should never be used within
670 B<debian/rules>. It's meant for any user that wants to rebuild the
671 source package with different build flags. The second set
672 (DEB_I<flag>_MAINT_I<op>) should only be used in B<debian/rules>
673 by package maintainers to change the resulting build flags.
677 =item B<DEB_>I<flag>B<_SET>
679 =item B<DEB_>I<flag>B<_MAINT_SET> (since dpkg 1.16.1)
681 This variable can be used to force the value returned for the given
684 =item B<DEB_>I<flag>B<_STRIP> (since dpkg 1.16.1)
686 =item B<DEB_>I<flag>B<_MAINT_STRIP> (since dpkg 1.16.1)
688 This variable can be used to provide a space separated list of options
689 that will be stripped from the set of flags returned for the given
692 =item B<DEB_>I<flag>B<_APPEND>
694 =item B<DEB_>I<flag>B<_MAINT_APPEND> (since dpkg 1.16.1)
696 This variable can be used to append supplementary options to the value
697 returned for the given I<flag>.
699 =item B<DEB_>I<flag>B<_PREPEND> (since dpkg 1.16.1)
701 =item B<DEB_>I<flag>B<_MAINT_PREPEND> (since dpkg 1.16.1)
703 This variable can be used to prepend supplementary options to the value
704 returned for the given I<flag>.
706 =item B<DEB_BUILD_OPTIONS>
708 =item B<DEB_BUILD_MAINT_OPTIONS> (since dpkg 1.16.1)
710 These variables can be used by a user or maintainer to disable/enable
711 various area features that affect build flags.
712 The B<DEB_BUILD_MAINT_OPTIONS> variable overrides any setting in the
713 B<DEB_BUILD_OPTIONS> feature areas.
714 See the B<FEATURE AREAS> section for details.
718 This setting defines the current vendor.
719 If not set, it will discover the current vendor by reading
720 B<%PKGCONFDIR%/origins/default>.
722 =item B<DEB_BUILD_PATH>
724 This variable sets the build path (since dpkg 1.18.8) to use in features
725 such as B<fixdebugpath> so that they can be controlled by the caller.
726 This variable is currently Debian and derivatives-specific.
730 Sets the color mode (since dpkg 1.18.5).
731 The currently accepted values are: B<auto> (default), B<always> and
736 If set, it will be used to decide whether to activate Native Language Support,
737 also known as internationalization (or i18n) support (since dpkg 1.19.0).
738 The accepted values are: B<0> and B<1> (default).
744 =head2 Configuration files
748 =item B<%PKGCONFDIR%/buildflags.conf>
750 System wide configuration file.
752 =item B<$XDG_CONFIG_HOME/dpkg/buildflags.conf> or
754 =item B<$HOME/.config/dpkg/buildflags.conf>
756 User configuration file.
760 =head2 Packaging support
764 =item B<%PKGDATADIR%/buildflags.mk>
766 Makefile snippet that will load (and optionally export) all flags
767 supported by B<dpkg-buildflags> into variables (since dpkg 1.16.1).
773 To pass build flags to a build command in a Makefile:
777 $(MAKE) $(shell dpkg-buildflags --export=cmdline)
779 ./configure $(shell dpkg-buildflags --export=cmdline)
783 To set build flags in a shell script or shell fragment, B<eval> can be
784 used to interpret the output and to export the flags in the environment:
788 eval "$(dpkg-buildflags --export=sh)" && make
792 or to set the positional parameters to pass to a command:
796 eval "set -- $(dpkg-buildflags --export=cmdline)"
797 for dir in a b c; do (cd $dir && ./configure "$@" && make); done
801 =head2 Usage in debian/rules
803 You should call B<dpkg-buildflags> or include B<buildflags.mk>
804 from the B<debian/rules> file to obtain the needed build flags to
805 pass to the build system.
806 Note that older versions of B<dpkg-buildpackage> (before dpkg 1.16.1)
807 exported these flags automatically. However, you should not rely on this,
808 since this breaks manual invocation of B<debian/rules>.
810 For packages with autoconf-like build systems, you can pass the relevant
811 options to configure or B<make>(1) directly, as shown above.
813 For other build systems, or when you need more fine-grained control
814 about which flags are passed where, you can use B<--get>. Or you
815 can include B<buildflags.mk> instead, which takes care of calling
816 B<dpkg-buildflags> and storing the build flags in make variables.
818 If you want to export all buildflags into the environment (where they
819 can be picked up by your build system):
823 DPKG_EXPORT_BUILDFLAGS = 1
824 include %PKGDATADIR%/buildflags.mk
828 For some extra control over what is exported, you can manually export
829 the variables (as none are exported by default):
833 include %PKGDATADIR%/buildflags.mk
834 export CPPFLAGS CFLAGS LDFLAGS
838 And you can of course pass the flags to commands manually:
842 include %PKGDATADIR%/buildflags.mk
844 $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)