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