1dpkg-buildflags(1) dpkg suite dpkg-buildflags(1)
2
6 dpkg-buildflags - returns build flags to use during package build
7
9 dpkg-buildflags [option...] [command]
10
12 dpkg-buildflags is a tool to retrieve compilation flags to use during
13 build of Debian packages.
14 The default flags are defined by the vendor but they can be
16 extended/overridden in several ways:
17 1. system-wide with /etc/dpkg/buildflags.conf;
19 2. for the current user with $XDG_CONFIG_HOME/dpkg/buildflags.conf
21 where $XDG_CONFIG_HOME defaults to $HOME/.config;
22 3. temporarily by the user with environment variables (see section
24 ENVIRONMENT);
25 4. dynamically by the package maintainer with environment variables
27 set via debian/rules (see section ENVIRONMENT).
28 The configuration files can contain four types of directives:
30 SET flag value
32 Override the flag named flag to have the value value.
33 STRIP flag value
35 Strip from the flag named flag all the build flags listed in value.
36 APPEND flag value
38 Extend the flag named flag by appending the options given in value.
39 A space is prepended to the appended value if the flag's current
40 value is non-empty.
41 PREPEND flag value
43 Extend the flag named flag by prepending the options given in
44 value. A space is appended to the prepended value if the flag's
45 current value is non-empty.
46 The configuration files can contain comments on lines starting with a
48 hash (#). Empty lines are also ignored.
49
51 --dump
52 Print to standard output all compilation flags and their values. It
53 prints one flag per line separated from its value by an equal sign
54 (“flag=value”). This is the default action.
55 --list
57 Print the list of flags supported by the current vendor (one per
58 line). See the SUPPORTED FLAGS section for more information about
59 them.
60 --status
62 Display any information that can be useful to explain the behaviour
63 of dpkg-buildflags (since dpkg 1.16.5): relevant environment
64 variables, current vendor, state of all feature flags. Also print
65 the resulting compiler flags with their origin.
66 This is intended to be run from debian/rules, so that the build log
68 keeps a clear trace of the build flags used. This can be useful to
69 diagnose problems related to them.
70 --export=format
72 Print to standard output commands that can be used to export all
73 the compilation flags for some particular tool. If the format value
74 is not given, sh is assumed. Only compilation flags starting with
75 an upper case character are included, others are assumed to not be
76 suitable for the environment. Supported formats:
77 sh Shell commands to set and export all the compilation flags in
79 the environment. The flag values are quoted so the output is
80 ready for evaluation by a shell.
81 cmdline
83 Arguments to pass to a build program's command line to use all
84 the compilation flags (since dpkg 1.17.0). The flag values are
85 quoted in shell syntax.
86 configure
88 This is a legacy alias for cmdline.
89 make
91 Make directives to set and export all the compilation flags in
92 the environment. Output can be written to a Makefile fragment
93 and evaluated using an include directive.
94 --get flag
96 Print the value of the flag on standard output. Exits with 0 if the
97 flag is known otherwise exits with 1.
98 --origin flag
100 Print the origin of the value that is returned by --get. Exits with
101 0 if the flag is known otherwise exits with 1. The origin can be
102 one of the following values:
103 vendor
105 the original flag set by the vendor is returned;
106 system
108 the flag is set/modified by a system-wide configuration;
109 user
111 the flag is set/modified by a user-specific configuration;
112 env the flag is set/modified by an environment-specific
114 configuration.
115 --query
117 Print any information that can be useful to explain the behaviour
118 of the program: current vendor, relevant environment variables,
119 feature areas, state of all feature flags, and the compiler flags
120 with their origin (since dpkg 1.19.0).
121 For example:
123 Vendor: Debian
125 Environment:
126 DEB_CFLAGS_SET=-O0 -Wall
127 Area: qa
129 Features:
130 bug=no
131 canary=no
132 Area: reproducible
134 Features:
135 timeless=no
136 Flag: CFLAGS
138 Value: -O0 -Wall
139 Origin: env
140 Flag: CPPFLAGS
142 Value: -D_FORTIFY_SOURCE=2
143 Origin: vendor
144 --query-features area
146 Print the features enabled for a given area (since dpkg 1.16.2).
147 The only currently recognized areas on Debian and derivatives are
148 future, qa, reproducible, sanitize and hardening, see the FEATURE
149 AREAS section for more details. Exits with 0 if the area is known
150 otherwise exits with 1.
151 The output is in RFC822 format, with one section per feature. For
153 example:
154 Feature: pie
156 Enabled: yes
157 Feature: stackprotector
159 Enabled: yes
160 --help
162 Show the usage message and exit.
163 --version
165 Show the version and exit.
166
168 ASFLAGS
169 Options for the assembler. Default value: empty. Since dpkg 1.21.0.
170 CFLAGS
172 Options for the C compiler. The default value set by the vendor
173 includes -g and the default optimization level (-O2 usually, or -O0
174 if the DEB_BUILD_OPTIONS environment variable defines noopt).
175 CPPFLAGS
177 Options for the C preprocessor. Default value: empty.
178 CXXFLAGS
180 Options for the C++ compiler. Same as CFLAGS.
181 OBJCFLAGS
183 Options for the Objective C compiler. Same as CFLAGS.
184 OBJCXXFLAGS
186 Options for the Objective C++ compiler. Same as CXXFLAGS.
187 GCJFLAGS
189 Options for the GNU Java compiler (gcj). A subset of CFLAGS.
190 DFLAGS
192 Options for the D compiler (ldc or gdc). Since dpkg 1.20.6.
193 FFLAGS
195 Options for the Fortran 77 compiler. A subset of CFLAGS.
196 FCFLAGS
198 Options for the Fortran 9x compiler. Same as FFLAGS.
199 LDFLAGS
201 Options passed to the compiler when linking executables or shared
202 objects (if the linker is called directly, then -Wl and , have to
203 be stripped from these options). Default value: empty.
204 New flags might be added in the future if the need arises (for example
206 to support other languages).
207
209 Each area feature can be enabled and disabled in the DEB_BUILD_OPTIONS
210 and DEB_BUILD_MAINT_OPTIONS environment variable's area value with the
211 ‘+’ and ‘-’ modifier. For example, to enable the hardening “pie”
212 feature and disable the “fortify” feature you can do this in
213 debian/rules:
214 export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
216 The special feature all (valid in any area) can be used to enable or
218 disable all area features at the same time. Thus disabling everything
219 in the hardening area and enabling only “format” and “fortify” can be
220 achieved with:
221 export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
223 future
225 Several compile-time options (detailed below) can be used to enable
226 features that should be enabled by default, but cannot due to backwards
227 compatibility reasons.
228 lfs This setting (disabled by default) enables Large File Support on
230 32-bit architectures where their ABI does not include LFS by
231 default, by adding -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 to
232 CPPFLAGS.
233 qa
235 Several compile-time options (detailed below) can be used to help
236 detect problems in the source code or build system.
237 bug This setting (disabled by default) adds any warning option that
239 reliably detects problematic source code. The warnings are fatal.
240 The only currently supported flags are CFLAGS and CXXFLAGS with
241 flags set to -Werror=array-bounds, -Werror=clobbered,
242 -Werror=implicit-function-declaration and
243 -Werror=volatile-register-var.
244 canary
246 This setting (disabled by default) adds dummy canary options to the
247 build flags, so that the build logs can be checked for how the
248 build flags propagate and to allow finding any omission of normal
249 build flag settings. The only currently supported flags are
250 CPPFLAGS, CFLAGS, OBJCFLAGS, CXXFLAGS and OBJCXXFLAGS with flags
251 set to -D__DEB_CANARY_flag_random-id__, and LDFLAGS set to
252 -Wl,-z,deb-canary-random-id.
253 optimize
255 Several compile-time options (detailed below) can be used to help
256 optimize a resulting binary (since dpkg 1.21.0). Note: enabling all
257 these options can result in unreproducible binary artifacts.
258 lto This setting (since dpkg 1.21.0; disabled by default) enables Link
260 Time Optimization by adding -flto=auto -ffat-lto-objects to CFLAGS,
261 CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS, FCFLAGS and
262 LDFLAGS.
263 sanitize
265 Several compile-time options (detailed below) can be used to help
266 sanitize a resulting binary against memory corruptions, memory leaks,
267 use after free, threading data races and undefined behavior bugs.
268 Note: these options should not be used for production builds as they
269 can reduce reliability for conformant code, reduce security or even
270 functionality.
271 address
273 This setting (disabled by default) adds -fsanitize=address to
274 LDFLAGS and -fsanitize=address -fno-omit-frame-pointer to CFLAGS
275 and CXXFLAGS.
276 thread
278 This setting (disabled by default) adds -fsanitize=thread to
279 CFLAGS, CXXFLAGS and LDFLAGS.
280 leak
282 This setting (disabled by default) adds -fsanitize=leak to LDFLAGS.
283 It gets automatically disabled if either the address or the thread
284 features are enabled, as they imply it.
285 undefined
287 This setting (disabled by default) adds -fsanitize=undefined to
288 CFLAGS, CXXFLAGS and LDFLAGS.
289 hardening
291 Several compile-time options (detailed below) can be used to help
292 harden a resulting binary against memory corruption attacks, or provide
293 additional warning messages during compilation. Except as noted below,
294 these are enabled by default for architectures that support them.
295 format
297 This setting (enabled by default) adds -Wformat
298 -Werror=format-security to CFLAGS, CXXFLAGS, OBJCFLAGS and
299 OBJCXXFLAGS. This will warn about improper format string uses, and
300 will fail when format functions are used in a way that represent
301 possible security problems. At present, this warns about calls to
302 printf and scanf functions where the format string is not a string
303 literal and there are no format arguments, as in printf(foo);
304 instead of printf("%s", foo); This may be a security hole if the
305 format string came from untrusted input and contains ‘%n’.
306 fortify
308 This setting (enabled by default) adds -D_FORTIFY_SOURCE=2 to
309 CPPFLAGS. During code generation the compiler knows a great deal of
310 information about buffer sizes (where possible), and attempts to
311 replace insecure unlimited length buffer function calls with
312 length-limited ones. This is especially useful for old, crufty
313 code. Additionally, format strings in writable memory that contain
314 ‘%n’ are blocked. If an application depends on such a format
315 string, it will need to be worked around.
316 Note that for this option to have any effect, the source must also
318 be compiled with -O1 or higher. If the environment variable
319 DEB_BUILD_OPTIONS contains noopt, then fortify support will be
320 disabled, due to new warnings being issued by glibc 2.16 and later.
321 stackprotector
323 This setting (enabled by default if stackprotectorstrong is not in
324 use) adds -fstack-protector --param=ssp-buffer-size=4 to CFLAGS,
325 CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS.
326 This adds safety checks against stack overwrites. This renders many
327 potential code injection attacks into aborting situations. In the
328 best case this turns code injection vulnerabilities into denial of
329 service or into non-issues (depending on the application).
330 This feature requires linking against glibc (or another provider of
332 __stack_chk_fail), so needs to be disabled when building with
333 -nostdlib or -ffreestanding or similar.
334 stackprotectorstrong
336 This setting (enabled by default) adds -fstack-protector-strong to
337 CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and
338 FCFLAGS. This is a stronger variant of stackprotector, but without
339 significant performance penalties.
340 Disabling stackprotector will also disable this setting.
342 This feature has the same requirements as stackprotector, and in
344 addition also requires gcc 4.9 and later.
345 relro
347 This setting (enabled by default) adds -Wl,-z,relro to LDFLAGS.
348 During program load, several ELF memory sections need to be written
349 to by the linker. This flags the loader to turn these sections
350 read-only before turning over control to the program. Most notably
351 this prevents GOT overwrite attacks. If this option is disabled,
352 bindnow will become disabled as well.
353 bindnow
355 This setting (disabled by default) adds -Wl,-z,now to LDFLAGS.
356 During program load, all dynamic symbols are resolved, allowing for
357 the entire PLT to be marked read-only (due to relro above). The
358 option cannot become enabled if relro is not enabled.
359 pie This setting (with no global default since dpkg 1.18.23, as it is
361 enabled by default now by gcc on the amd64, arm64, armel, armhf,
362 hurd-i386, i386, kfreebsd-amd64, kfreebsd-i386, mips, mipsel,
363 mips64el, powerpc, ppc64, ppc64el, riscv64, s390x, sparc and
364 sparc64 Debian architectures) adds the required options to enable
365 or disable PIE via gcc specs files, if needed, depending on whether
366 gcc injects on that architecture the flags by itself or not. When
367 the setting is enabled and gcc injects the flags, it adds nothing.
368 When the setting is enabled and gcc does not inject the flags, it
369 adds -fPIE (via /usr/share/dpkg/pie-compiler.specs) to CFLAGS,
370 CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS, and
371 -fPIE -pie (via /usr/share/dpkg/pie-link.specs) to LDFLAGS. When
372 the setting is disabled and gcc injects the flags, it adds -fno-PIE
373 (via /usr/share/dpkg/no-pie-compile.specs) to CFLAGS, CXXFLAGS,
374 OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS, and -fno-PIE
375 -no-pie (via /usr/share/dpkg/no-pie-link.specs) to LDFLAGS.
376 Position Independent Executable are needed to take advantage of
378 Address Space Layout Randomization, supported by some kernel
379 versions. While ASLR can already be enforced for data areas in the
380 stack and heap (brk and mmap), the code areas must be compiled as
381 position-independent. Shared libraries already do this (-fPIC), so
382 they gain ASLR automatically, but binary .text regions need to be
383 build PIE to gain ASLR. When this happens, ROP (Return Oriented
384 Programming) attacks are much harder since there are no static
385 locations to bounce off of during a memory corruption attack.
386 PIE is not compatible with -fPIC, so in general care must be taken
388 when building shared objects. But because the PIE flags emitted get
389 injected via gcc specs files, it should always be safe to
390 unconditionally set them regardless of the object type being
391 compiled or linked.
392 Static libraries can be used by programs or other shared libraries.
394 Depending on the flags used to compile all the objects within a
395 static library, these libraries will be usable by different sets of
396 objects:
397 none
399 Cannot be linked into a PIE program, nor a shared library.
400 -fPIE
402 Can be linked into any program, but not a shared library
403 (recommended).
404 -fPIC
406 Can be linked into any program and shared library.
407 If there is a need to set these flags manually, bypassing the gcc
409 specs injection, there are several things to take into account.
410 Unconditionally and explicitly passing -fPIE, -fpie or -pie to a
411 build-system using libtool is safe as these flags will get stripped
412 when building shared libraries. Otherwise on projects that build
413 both programs and shared libraries you might need to make sure that
414 when building the shared libraries -fPIC is always passed last (so
415 that it overrides any previous -PIE) to compilation flags such as
416 CFLAGS, and -shared is passed last (so that it overrides any
417 previous -pie) to linking flags such as LDFLAGS. Note: This should
418 not be needed with the default gcc specs machinery.
419 Additionally, since PIE is implemented via a general register, some
421 register starved architectures (but not including i386 anymore
422 since optimizations implemented in gcc >= 5) can see performance
423 losses of up to 15% in very text-segment-heavy application
424 workloads; most workloads see less than 1%. Architectures with more
425 general registers (e.g. amd64) do not see as high a worst-case
426 penalty.
427 reproducible
429 The compile-time options detailed below can be used to help improve
430 build reproducibility or provide additional warning messages during
431 compilation. Except as noted below, these are enabled by default for
432 architectures that support them.
433 timeless
435 This setting (enabled by default) adds -Wdate-time to CPPFLAGS.
436 This will cause warnings when the __TIME__, __DATE__ and
437 __TIMESTAMP__ macros are used.
438 fixfilepath
440 This setting (enabled by default) adds
441 -ffile-prefix-map=BUILDPATH=. to CFLAGS, CXXFLAGS, OBJCFLAGS,
442 OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS where BUILDPATH is set to
443 the top-level directory of the package being built. This has the
444 effect of removing the build path from any generated file.
445 If both fixdebugpath and fixfilepath are set, this option takes
447 precedence, because it is a superset of the former.
448 fixdebugpath
450 This setting (enabled by default) adds
451 -fdebug-prefix-map=BUILDPATH=. to CFLAGS, CXXFLAGS, OBJCFLAGS,
452 OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS where BUILDPATH is set to
453 the top-level directory of the package being built. This has the
454 effect of removing the build path from any generated debug symbols.
455
457 There are 2 sets of environment variables doing the same operations,
458 the first one (DEB_flag_op) should never be used within debian/rules.
459 It's meant for any user that wants to rebuild the source package with
460 different build flags. The second set (DEB_flag_MAINT_op) should only
461 be used in debian/rules by package maintainers to change the resulting
462 build flags.
463 DEB_flag_SET
465 DEB_flag_MAINT_SET
466 This variable can be used to force the value returned for the given
467 flag.
468 DEB_flag_STRIP
470 DEB_flag_MAINT_STRIP
471 This variable can be used to provide a space separated list of
472 options that will be stripped from the set of flags returned for
473 the given flag.
474 DEB_flag_APPEND
476 DEB_flag_MAINT_APPEND
477 This variable can be used to append supplementary options to the
478 value returned for the given flag.
479 DEB_flag_PREPEND
481 DEB_flag_MAINT_PREPEND
482 This variable can be used to prepend supplementary options to the
483 value returned for the given flag.
484 DEB_BUILD_OPTIONS
486 DEB_BUILD_MAINT_OPTIONS
487 These variables can be used by a user or maintainer to
488 disable/enable various area features that affect build flags. The
489 DEB_BUILD_MAINT_OPTIONS variable overrides any setting in the
490 DEB_BUILD_OPTIONS feature areas. See the FEATURE AREAS section for
491 details.
492 DEB_VENDOR
494 This setting defines the current vendor. If not set, it will
495 discover the current vendor by reading /etc/dpkg/origins/default.
496 DEB_BUILD_PATH
498 This variable sets the build path (since dpkg 1.18.8) to use in
499 features such as fixdebugpath so that they can be controlled by the
500 caller. This variable is currently Debian and derivatives-
501 specific.
502 DPKG_COLORS
504 Sets the color mode (since dpkg 1.18.5). The currently accepted
505 values are: auto (default), always and never.
506 DPKG_NLS
508 If set, it will be used to decide whether to activate Native
509 Language Support, also known as internationalization (or i18n)
510 support (since dpkg 1.19.0). The accepted values are: 0 and 1
511 (default).
512
514 Configuration files
515 /etc/dpkg/buildflags.conf
516 System wide configuration file.
517 $XDG_CONFIG_HOME/dpkg/buildflags.conf or
519 $HOME/.config/dpkg/buildflags.conf
520 User configuration file.
521 Packaging support
523 /usr/share/dpkg/buildflags.mk
524 Makefile snippet that will load (and optionally export) all flags
525 supported by dpkg-buildflags into variables (since dpkg 1.16.1).
526
528 To pass build flags to a build command in a Makefile:
529 $(MAKE) $(shell dpkg-buildflags --export=cmdline)
531 ./configure $(shell dpkg-buildflags --export=cmdline)
533 To set build flags in a shell script or shell fragment, eval can be
535 used to interpret the output and to export the flags in the
536 environment:
537 eval "$(dpkg-buildflags --export=sh)" && make
539 or to set the positional parameters to pass to a command:
541 eval "set -- $(dpkg-buildflags --export=cmdline)"
543 for dir in a b c; do (cd $dir && ./configure "$@" && make); done
544 Usage in debian/rules
546 You should call dpkg-buildflags or include buildflags.mk from the
547 debian/rules file to obtain the needed build flags to pass to the build
548 system. Note that older versions of dpkg-buildpackage (before dpkg
549 1.16.1) exported these flags automatically. However, you should not
550 rely on this, since this breaks manual invocation of debian/rules.
551 For packages with autoconf-like build systems, you can pass the
553 relevant options to configure or make(1) directly, as shown above.
554 For other build systems, or when you need more fine-grained control
556 about which flags are passed where, you can use --get. Or you can
557 include buildflags.mk instead, which takes care of calling dpkg-
558 buildflags and storing the build flags in make variables.
559 If you want to export all buildflags into the environment (where they
561 can be picked up by your build system):
562 DPKG_EXPORT_BUILDFLAGS = 1
564 include /usr/share/dpkg/buildflags.mk
565 For some extra control over what is exported, you can manually export
567 the variables (as none are exported by default):
568 include /usr/share/dpkg/buildflags.mk
570 export CPPFLAGS CFLAGS LDFLAGS
571 And you can of course pass the flags to commands manually:
573 include /usr/share/dpkg/buildflags.mk
575 build-arch:
576 $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
5771.21.9 2022-07-01 dpkg-buildflags(1)