Dpkg::Vendor::Debian: Only enable LFS when time64 is enabled for glibc
[dpkg.git] / man / dpkg-buildflags.pod
blob32988653257986ff3326b8d7b8a7a711b5c50ca5
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/>.
20 =encoding utf8
22 =head1 NAME
24 dpkg-buildflags - returns build flags to use during package build
26 =head1 SYNOPSIS
28 B<dpkg-buildflags>
29 [I<option>...] [I<command>]
31 =head1 DESCRIPTION
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:
39 =over
41 =item 1.
43 system-wide with B<%PKGCONFDIR%/buildflags.conf>;
45 =item 2.
47 for the current user with B<$XDG_CONFIG_HOME/dpkg/buildflags.conf>
48 where B<$XDG_CONFIG_HOME> defaults to B<$HOME/.config>;
50 =item 3.
52 temporarily by the user with environment variables (see section
53 B<ENVIRONMENT>);
55 =item 4.
57 dynamically by the package maintainer with environment variables set via
58 B<debian/rules> (see section B<ENVIRONMENT>).
60 =back
62 The configuration files can contain four types of directives:
64 =over
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>.
73 Since dpkg 1.16.1.
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.
84 Since dpkg 1.16.1.
86 =back
88 The configuration files can contain comments on lines starting with a hash
89 (#). Empty lines are also ignored.
91 =head1 COMMANDS
93 =over
95 =item B<--dump>
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.
101 =item B<--list>
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.
107 =item B<--status>
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:
126 =over
128 =item B<sh>
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.
134 =item B<cmdline>
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
138 shell syntax.
140 =item B<configure>
142 This is a legacy alias for B<cmdline>.
144 =item B<make>
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.
150 =back
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:
163 =over
165 =item B<vendor>
167 the original flag set by the vendor is returned;
169 =item B<system>
171 the flag is set/modified by a system-wide configuration;
173 =item B<user>
175 the flag is set/modified by a user-specific configuration;
177 =item B<env>
179 the flag is set/modified by an environment-specific configuration.
181 =back
183 =item B<--query>
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).
191 For example:
193  Vendor: Debian
194  Environment:
195   DEB_CFLAGS_SET=-O0 -Wall
197  Area: qa
198  Features:
199   bug=no
200   canary=no
201  Builtins:
203  Area: hardening
204  Features:
205   pie=no
206  Builtins:
207   pie=yes
209  Area: reproducible
210  Features:
211   timeless=no
212  Builtins:
214  Flag: CFLAGS
215  Value: -O0 -Wall
216  Origin: env
218  Flag: CPPFLAGS
219  Value: -D_FORTIFY_SOURCE=2
220  Origin: vendor
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.
235 For example:
237  Feature: pie
238  Enabled: yes
239  Builtin: yes
241  Feature: stackprotector
242  Enabled: yes
244 =item B<--help>
246 Show the usage message and exit.
248 =item B<--version>
250 Show the version and exit.
252 =back
254 =head1 SUPPORTED FLAGS
256 =over
258 =item B<ASFLAGS>
260 Options for the assembler. Default value: empty. Since dpkg 1.21.0.
262 =item B<CFLAGS>
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
267 I<noopt>).
269 =item B<CPPFLAGS>
271 Options for the C preprocessor. Default value: empty.
273 =item B<CXXFLAGS>
275 Options for the C++ compiler. Same as B<CFLAGS>.
277 =item B<OBJCFLAGS>
279 Options for the Objective C compiler. Same as B<CFLAGS>.
280 Since dpkg 1.17.7.
282 =item B<OBJCXXFLAGS>
284 Options for the Objective C++ compiler. Same as B<CXXFLAGS>.
285 Since dpkg 1.17.7.
287 =item B<GCJFLAGS>
289 Options for the GNU Java compiler (gcj). A subset of B<CFLAGS>.
291 =item B<DFLAGS>
293 Options for the D compiler (ldc or gdc). Since dpkg 1.20.6.
295 =item B<FFLAGS>
297 Options for the Fortran 77 compiler. A subset of B<CFLAGS>.
299 =item B<FCFLAGS>
301 Options for the Fortran 9x compiler. Same as B<FFLAGS>.
302 Since dpkg 1.17.7.
304 =item B<LDFLAGS>
306 Options passed to the compiler when linking executables or shared
307 objects (if the linker is called directly, then
308 B<-Wl>
310 B<,>
311 have to be stripped from these options). Default value: empty.
313 =back
315 New flags might be added in the future if the need arises (for example
316 to support other languages).
318 =head1 FEATURE AREAS
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
335 =head2 future
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
339 reasons.
341 =over
343 =item B<lfs>
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>.
350 =item B<time64>
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.
357 =back
359 =head2 qa
361 Several compile-time options (detailed below) can be used to help detect
362 problems in the source code or build system.
364 =over
366 =item B<bug>
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>.
376 =item B<canary>
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
381 build flag settings.
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>.
387 =back
389 =head2 optimize
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
394 artifacts.
396 =over
398 =item B<lto>
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>.
405 =back
407 =head2 sanitize
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
414 even functionality.
416 =over
418 =item B<address>
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>.
425 =item B<thread>
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>.
431 =item B<leak>
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.
438 =item B<undefined>
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>.
444 =back
446 =head2 hardening
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
452 that support them.
454 =over
456 =item B<format>
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’.
470 =item B<fortify>
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
480 to be worked around.
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
498 the application).
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.
518 =item B<relro>
520 This setting (since dpkg 1.16.1; enabled by default) adds
521 B<-Wl,-z,relro>
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.
528 =item B<bindnow>
530 This setting (since dpkg 1.16.1; disabled by default) adds
531 B<-Wl,-z,now>
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.
536 =item B<pie>
538 This setting (since dpkg 1.16.1; with no global default since dpkg 1.18.23,
539 as it is enabled
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
545 by itself or not.
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
557 B<LDFLAGS>.
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:
578 =over
580 =item none
582 Cannot be linked into a PIE program, nor a shared library.
584 =item B<-fPIE>
586 Can be linked into any program, but not a shared library (recommended).
588 =item B<-fPIC>
590 Can be linked into any program and shared library.
592 =back
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
605 gcc specs machinery.
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.
614 =back
616 =head2 reproducible
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.
623 =over
625 =item B<timeless>
627 This setting (since dpkg 1.17.14; enabled by default) adds
628 B<-Wdate-time>
629 to B<CPPFLAGS>.
630 This will cause warnings when the B<__TIME__>, B<__DATE__> and
631 B<__TIMESTAMP__> macros are used.
633 =item B<fixfilepath>
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
660 symbols.
662 B<Note>: This feature has similar reproducible properties as B<fixfilepath>.
664 =back
666 =head1 ENVIRONMENT
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.
675 =over
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
682 I<flag>.
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
690 I<flag>.
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.
716 =item B<DEB_VENDOR>
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.
728 =item B<DPKG_COLORS>
730 Sets the color mode (since dpkg 1.18.5).
731 The currently accepted values are: B<auto> (default), B<always> and
732 B<never>.
734 =item B<DPKG_NLS>
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).
740 =back
742 =head1 FILES
744 =head2 Configuration files
746 =over
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.
758 =back
760 =head2 Packaging support
762 =over
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).
769 =back
771 =head1 EXAMPLES
773 To pass build flags to a build command in a Makefile:
775 =over
777  $(MAKE) $(shell dpkg-buildflags --export=cmdline)
779  ./configure $(shell dpkg-buildflags --export=cmdline)
781 =back
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:
786 =over
788  eval "$(dpkg-buildflags --export=sh)" && make
790 =back
792 or to set the positional parameters to pass to a command:
794 =over
796  eval "set -- $(dpkg-buildflags --export=cmdline)"
797  for dir in a b c; do (cd $dir && ./configure "$@" && make); done
799 =back
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):
821 =over
823  DPKG_EXPORT_BUILDFLAGS = 1
824  include %PKGDATADIR%/buildflags.mk
826 =back
828 For some extra control over what is exported, you can manually export
829 the variables (as none are exported by default):
831 =over
833  include %PKGDATADIR%/buildflags.mk
834  export CPPFLAGS CFLAGS LDFLAGS
836 =back
838 And you can of course pass the flags to commands manually:
840 =over
842  include %PKGDATADIR%/buildflags.mk
843  build-arch:
844         $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
846 =back