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-features area
114 Print the features enabled for a given area (since dpkg 1.16.2).
115 The only currently recognized areas on Debian and derivatives
116 are qa, reproducible, sanitize and hardening, see the FEATURE
117 AREAS section for more details. Exits with 0 if the area is
118 known otherwise exits with 1.
119 The output is in RFC822 format, with one section per feature.
121 For example:
122 Feature: pie
124 Enabled: yes
125 Feature: stackprotector
127 Enabled: yes
128 --help Show the usage message and exit.
130 --version
132 Show the version and exit.
133
135 CFLAGS Options for the C compiler. The default value set by the vendor
136 includes -g and the default optimization level (-O2 usually, or
137 -O0 if the DEB_BUILD_OPTIONS environment variable defines
138 noopt).
139 CPPFLAGS
141 Options for the C preprocessor. Default value: empty.
142 CXXFLAGS
144 Options for the C++ compiler. Same as CFLAGS.
145 OBJCFLAGS
147 Options for the Objective C compiler. Same as CFLAGS.
148 OBJCXXFLAGS
150 Options for the Objective C++ compiler. Same as CXXFLAGS.
151 GCJFLAGS
153 Options for the GNU Java compiler (gcj). A subset of CFLAGS.
154 FFLAGS Options for the Fortran 77 compiler. A subset of CFLAGS.
156 FCFLAGS
158 Options for the Fortran 9x compiler. Same as FFLAGS.
159 LDFLAGS
161 Options passed to the compiler when linking executables or
162 shared objects (if the linker is called directly, then -Wl and ,
163 have to be stripped from these options). Default value: empty.
164 New flags might be added in the future if the need arises (for example
166 to support other languages).
167
169 Each area feature can be enabled and disabled in the DEB_BUILD_OPTIONS
170 and DEB_BUILD_MAINT_OPTIONS environment variable's area value with the
171 ‘+’ and ‘-’ modifier. For example, to enable the hardening “pie”
172 feature and disable the “fortify” feature you can do this in
173 debian/rules:
174 export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
176 The special feature all (valid in any area) can be used to enable or
178 disable all area features at the same time. Thus disabling everything
179 in the hardening area and enabling only “format” and “fortify” can be
180 achieved with:
181 export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
183 qa
185 Several compile-time options (detailed below) can be used to help
186 detect problems in the source code or build system.
187 bug This setting (disabled by default) adds any warning option that
189 reliably detects problematic source code. The warnings are
190 fatal. The only currently supported flags are CFLAGS and
191 CXXFLAGS with flags set to -Werror=array-bounds,
192 -Werror=clobbered, -Werror=implicit-function-declaration and
193 -Werror=volatile-register-var.
194 canary This setting (disabled by default) adds dummy canary options to
196 the build flags, so that the build logs can be checked for how
197 the build flags propagate and to allow finding any omission of
198 normal build flag settings. The only currently supported flags
199 are CPPFLAGS, CFLAGS, OBJCFLAGS, CXXFLAGS and OBJCXXFLAGS with
200 flags set to -D__DEB_CANARY_flag_random-id__, and LDFLAGS set to
201 -Wl,-z,deb-canary-random-id.
202 sanitize
204 Several compile-time options (detailed below) can be used to help
205 sanitize a resulting binary against memory corruptions, memory leaks,
206 use after free, threading data races and undefined behavior bugs.
207 address
209 This setting (disabled by default) adds -fsanitize=address to
210 LDFLAGS and -fsanitize=address -fno-omit-frame-pointer to CFLAGS
211 and CXXFLAGS.
212 thread This setting (disabled by default) adds -fsanitize=thread to
214 CFLAGS, CXXFLAGS and LDFLAGS.
215 leak This setting (disabled by default) adds -fsanitize=leak to
217 LDFLAGS. It gets automatically disabled if either the address or
218 the thread features are enabled, as they imply it.
219 undefined
221 This setting (disabled by default) adds -fsanitize=undefined to
222 CFLAGS, CXXFLAGS and LDFLAGS.
223 hardening
225 Several compile-time options (detailed below) can be used to help
226 harden a resulting binary against memory corruption attacks, or provide
227 additional warning messages during compilation. Except as noted below,
228 these are enabled by default for architectures that support them.
229 format This setting (enabled by default) adds -Wformat
231 -Werror=format-security to CFLAGS, CXXFLAGS, OBJCFLAGS and
232 OBJCXXFLAGS. This will warn about improper format string uses,
233 and will fail when format functions are used in a way that
234 represent possible security problems. At present, this warns
235 about calls to printf and scanf functions where the format
236 string is not a string literal and there are no format
237 arguments, as in printf(foo); instead of printf("%s", foo); This
238 may be a security hole if the format string came from untrusted
239 input and contains ‘%n’.
240 fortify
242 This setting (enabled by default) adds -D_FORTIFY_SOURCE=2 to
243 CPPFLAGS. During code generation the compiler knows a great deal
244 of information about buffer sizes (where possible), and attempts
245 to replace insecure unlimited length buffer function calls with
246 length-limited ones. This is especially useful for old, crufty
247 code. Additionally, format strings in writable memory that
248 contain ‘%n’ are blocked. If an application depends on such a
249 format string, it will need to be worked around.
250 Note that for this option to have any effect, the source must
252 also be compiled with -O1 or higher. If the environment variable
253 DEB_BUILD_OPTIONS contains noopt, then fortify support will be
254 disabled, due to new warnings being issued by glibc 2.16 and
255 later.
256 stackprotector
258 This setting (enabled by default if stackprotectorstrong is not
259 in use) adds -fstack-protector --param=ssp-buffer-size=4 to
260 CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and
261 FCFLAGS. This adds safety checks against stack overwrites. This
262 renders many potential code injection attacks into aborting
263 situations. In the best case this turns code injection
264 vulnerabilities into denial of service or into non-issues
265 (depending on the application).
266 This feature requires linking against glibc (or another provider
268 of __stack_chk_fail), so needs to be disabled when building with
269 -nostdlib or -ffreestanding or similar.
270 stackprotectorstrong
272 This setting (enabled by default) adds -fstack-protector-strong
273 to CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS
274 and FCFLAGS. This is a stronger variant of stackprotector, but
275 without significant performance penalties.
276 Disabling stackprotector will also disable this setting.
278 This feature has the same requirements as stackprotector, and in
280 addition also requires gcc 4.9 and later.
281 relro This setting (enabled by default) adds -Wl,-z,relro to LDFLAGS.
283 During program load, several ELF memory sections need to be
284 written to by the linker. This flags the loader to turn these
285 sections read-only before turning over control to the program.
286 Most notably this prevents GOT overwrite attacks. If this option
287 is disabled, bindnow will become disabled as well.
288 bindnow
290 This setting (disabled by default) adds -Wl,-z,now to LDFLAGS.
291 During program load, all dynamic symbols are resolved, allowing
292 for the entire PLT to be marked read-only (due to relro above).
293 The option cannot become enabled if relro is not enabled.
294 pie This setting (with no default since dpkg 1.18.23, and injected
296 by default by gcc on the amd64, arm64, armel, armhf, i386,
297 kfreebsd-amd64, kfreebsd-i386, mips, mipsel, mips64el, ppc64el,
298 s390x, sparc and sparc64 Debian architectures) adds the required
299 options via gcc specs files if needed to enable or disable PIE.
300 When enabled and injected by gcc, adds nothing. When enabled and
301 not injected by gcc, adds -fPIE to CFLAGS, CXXFLAGS, OBJCFLAGS,
302 OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS, and -fPIE -pie to
303 LDFLAGS. When disabled and injected by gcc, adds -fno-PIE to
304 CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS and
305 FCFLAGS, and -fno-PIE -no-pie to LDFLAGS.
306 Position Independent Executable are needed to take advantage of
308 Address Space Layout Randomization, supported by some kernel
309 versions. While ASLR can already be enforced for data areas in
310 the stack and heap (brk and mmap), the code areas must be
311 compiled as position-independent. Shared libraries already do
312 this (-fPIC), so they gain ASLR automatically, but binary .text
313 regions need to be build PIE to gain ASLR. When this happens,
314 ROP (Return Oriented Programming) attacks are much harder since
315 there are no static locations to bounce off of during a memory
316 corruption attack.
317 PIE is not compatible with -fPIC, so in general care must be
319 taken when building shared objects. But because the PIE flags
320 emitted get injected via gcc specs files, it should always be
321 safe to unconditionally set them regardless of the object type
322 being compiled or linked.
323 Static libraries can be used by programs or other shared
325 libraries. Depending on the flags used to compile all the
326 objects within a static library, these libraries will be usable
327 by different sets of objects:
328 none Cannot be linked into a PIE program, nor a shared
331 library.
332 -fPIE Can be linked into any program, but not a shared library
334 (recommended).
335 -fPIC Can be linked into any program and shared library.
337 If there is a need to set these flags manually, bypassing the
340 gcc specs injection, there are several things to take into
341 account. Unconditionally and explicitly passing -fPIE, -fpie or
342 -pie to a build-system using libtool is safe as these flags will
343 get stripped when building shared libraries. Otherwise on
344 projects that build both programs and shared libraries you might
345 need to make sure that when building the shared libraries -fPIC
346 is always passed last (so that it overrides any previous -PIE)
347 to compilation flags such as CFLAGS, and -shared is passed last
348 (so that it overrides any previous -pie) to linking flags such
349 as LDFLAGS. Note: This should not be needed with the default gcc
350 specs machinery.
351 Additionally, since PIE is implemented via a general register,
354 some register starved architectures (but not including i386
355 anymore since optimizations implemented in gcc >= 5) can see
356 performance losses of up to 15% in very text-segment-heavy
357 application workloads; most workloads see less than 1%.
358 Architectures with more general registers (e.g. amd64) do not
359 see as high a worst-case penalty.
360 reproducible
362 The compile-time options detailed below can be used to help improve
363 build reproducibility or provide additional warning messages during
364 compilation. Except as noted below, these are enabled by default for
365 architectures that support them.
366 timeless
368 This setting (enabled by default) adds -Wdate-time to CPPFLAGS.
369 This will cause warnings when the __TIME__, __DATE__ and
370 __TIMESTAMP__ macros are used.
371 fixdebugpath
373 This setting (enabled by default) adds
374 -fdebug-prefix-map=BUILDPATH=. to CFLAGS, CXXFLAGS, OBJCFLAGS,
375 OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS where BUILDPATH is set
376 to the top-level directory of the package being built. This has
377 the effect of removing the build path from any generated debug
378 symbols.
379
381 There are 2 sets of environment variables doing the same operations,
382 the first one (DEB_flag_op) should never be used within debian/rules.
383 It's meant for any user that wants to rebuild the source package with
384 different build flags. The second set (DEB_flag_MAINT_op) should only
385 be used in debian/rules by package maintainers to change the resulting
386 build flags.
387 DEB_flag_SET
389 DEB_flag_MAINT_SET
390 This variable can be used to force the value returned for the
391 given flag.
392 DEB_flag_STRIP
394 DEB_flag_MAINT_STRIP
395 This variable can be used to provide a space separated list of
396 options that will be stripped from the set of flags returned for
397 the given flag.
398 DEB_flag_APPEND
400 DEB_flag_MAINT_APPEND
401 This variable can be used to append supplementary options to the
402 value returned for the given flag.
403 DEB_flag_PREPEND
405 DEB_flag_MAINT_PREPEND
406 This variable can be used to prepend supplementary options to
407 the value returned for the given flag.
408 DEB_BUILD_OPTIONS
410 DEB_BUILD_MAINT_OPTIONS
411 These variables can be used by a user or maintainer to
412 disable/enable various area features that affect build flags.
413 The DEB_BUILD_MAINT_OPTIONS variable overrides any setting in
414 the DEB_BUILD_OPTIONS feature areas. See the FEATURE AREAS
415 section for details.
416 DEB_VENDOR
418 This setting defines the current vendor. If not set, it will
419 discover the current vendor by reading
420 /etc/dpkg/origins/default.
421 DEB_BUILD_PATH
423 This variable sets the build path (since dpkg 1.18.8) to use in
424 features such as fixdebugpath so that they can be controlled by
425 the caller. This variable is currently Debian and derivatives-
426 specific.
427
429 Configuration files
430 /etc/dpkg/buildflags.conf
431 System wide configuration file.
432 $XDG_CONFIG_HOME/dpkg/buildflags.conf or
434 $HOME/.config/dpkg/buildflags.conf
435 User configuration file.
436 Packaging support
438 /usr/share/dpkg/buildflags.mk
439 Makefile snippet that will load (and optionally export) all
440 flags supported by dpkg-buildflags into variables (since dpkg
441 1.16.1).
442
444 To pass build flags to a build command in a makefile:
445 $(MAKE) $(shell dpkg-buildflags --export=cmdline)
447 ./configure $(shell dpkg-buildflags --export=cmdline)
449 To set build flags in a shell script or shell fragment, eval can be
451 used to interpret the output and to export the flags in the
452 environment:
453 eval "$(dpkg-buildflags --export=sh)" && make
455 or to set the positional parameters to pass to a command:
457 eval "set -- $(dpkg-buildflags --export=cmdline)"
459 for dir in a b c; do (cd $dir && ./configure "$@" && make); done
460 Usage in debian/rules
462 You should call dpkg-buildflags or include buildflags.mk from the
463 debian/rules file to obtain the needed build flags to pass to the build
464 system. Note that older versions of dpkg-buildpackage (before dpkg
465 1.16.1) exported these flags automatically. However, you should not
466 rely on this, since this breaks manual invocation of debian/rules.
467 For packages with autoconf-like build systems, you can pass the
469 relevant options to configure or make(1) directly, as shown above.
470 For other build systems, or when you need more fine-grained control
472 about which flags are passed where, you can use --get. Or you can
473 include buildflags.mk instead, which takes care of calling
474 dpkg-buildflags and storing the build flags in make variables.
475 If you want to export all buildflags into the environment (where they
477 can be picked up by your build system):
478 DPKG_EXPORT_BUILDFLAGS = 1
480 include /usr/share/dpkg/buildflags.mk
481 For some extra control over what is exported, you can manually export
483 the variables (as none are exported by default):
484 include /usr/share/dpkg/buildflags.mk
486 export CPPFLAGS CFLAGS LDFLAGS
487 And you can of course pass the flags to commands manually:
489 include /usr/share/dpkg/buildflags.mk
491 build-arch:
492 $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
4931.18.25 2018-06-26 dpkg-buildflags(1)