diff options
Diffstat (limited to 'man/dpkg-buildflags.pod')
| -rw-r--r-- | man/dpkg-buildflags.pod | 995 |
1 files changed, 995 insertions, 0 deletions
diff --git a/man/dpkg-buildflags.pod b/man/dpkg-buildflags.pod new file mode 100644 index 0000000..6673a65 --- /dev/null +++ b/man/dpkg-buildflags.pod @@ -0,0 +1,995 @@ +# dpkg manual page - dpkg-buildflags(1) +# +# Copyright © 2010-2011 Raphaël Hertzog <hertzog@debian.org> +# Copyright © 2011 Kees Cook <kees@debian.org> +# Copyright © 2011-2015 Guillem Jover <guillem@debian.org> +# +# This is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <https://www.gnu.org/licenses/>. + +=encoding utf8 + +=head1 NAME + +dpkg-buildflags - returns build flags to use during package build + +=head1 SYNOPSIS + +B<dpkg-buildflags> +[I<option>...] [I<command>] + +=head1 DESCRIPTION + +B<dpkg-buildflags> is a tool to retrieve compilation flags to use during +build of Debian packages. + +The default flags are defined by the vendor but they can be +extended/overridden in several ways: + +=over + +=item 1. + +system-wide with B<%PKGCONFDIR%/buildflags.conf>; + +=item 2. + +for the current user with B<$XDG_CONFIG_HOME/dpkg/buildflags.conf> +where B<$XDG_CONFIG_HOME> defaults to B<$HOME/.config>; + +=item 3. + +temporarily by the user with environment variables (see section +L</ENVIRONMENT>); + +=item 4. + +dynamically by the package maintainer with environment variables set via +B<debian/rules> (see section L</ENVIRONMENT>). + +=back + +The configuration files can contain four types of directives: + +=over + +=item B<SET> I<flag> I<value> + +Override the flag named I<flag> to have the value I<value>. + +=item B<STRIP> I<flag> I<value> + +Strip from the flag named I<flag> all the build flags listed in I<value>. +Since dpkg 1.16.1. + +=item B<APPEND> I<flag> I<value> + +Extend the flag named I<flag> by appending the options given in I<value>. +A space is prepended to the appended value if the flag's current value is non-empty. + +=item B<PREPEND> I<flag> I<value> + +Extend the flag named I<flag> by prepending the options given in I<value>. +A space is appended to the prepended value if the flag's current value is non-empty. +Since dpkg 1.16.1. + +=back + +The configuration files can contain comments on lines starting with a hash +(#). +Empty lines are also ignored. + +This program was introduced in dpkg 1.15.7. + +=head1 COMMANDS + +=over + +=item B<--dump> + +Print to standard output all compilation flags and their values. +It prints +one flag per line separated from its value by an equal sign +(“I<flag>=I<value>”). +This is the default action. + +=item B<--list> + +Print the list of flags supported by the current vendor +(one per line). +See the L</SUPPORTED FLAGS> section for more +information about them. + +=item B<--status> + +Display any information that can be useful to explain the behavior of +B<dpkg-buildflags> (since dpkg 1.16.5): relevant environment variables, +current vendor, state of all feature flags. +Also print the resulting compiler flags with their origin. + +This is intended to be run from B<debian/rules>, so that the build log +keeps a clear trace of the build flags used. +This can be useful to diagnose +problems related to them. + +=item B<--export=>I<format> + +Print to standard output commands that can be used to export all the +compilation flags for some particular tool. +If the I<format> value is not given, B<sh> is assumed. +Only compilation flags starting with an +upper case character are included, others are assumed to not be suitable +for the environment. +Supported formats: + +=over + +=item B<sh> + +Shell commands to set and export all the compilation flags in the +environment. +The flag values are quoted so the output is ready for +evaluation by a shell. + +=item B<cmdline> + +Arguments to pass to a build program's command line to use all the +compilation flags (since dpkg 1.17.0). +The flag values are quoted in +shell syntax. + +=item B<configure> + +This is a legacy alias for B<cmdline>. + +=item B<make> + +Make directives to set and export all the compilation flags in the +environment. +Output can be written to a Makefile fragment and +evaluated using an B<include> directive. + +=back + +=item B<--get> I<flag> + +Print the value of the flag on standard output. +Exits with 0 +if the flag is known otherwise exits with 1. + +=item B<--origin> I<flag> + +Print the origin of the value that is returned by B<--get>. +Exits with 0 if the flag is known otherwise exits with 1. +The origin can be one +of the following values: + +=over + +=item B<vendor> + +the original flag set by the vendor is returned; + +=item B<system> + +the flag is set/modified by a system-wide configuration; + +=item B<user> + +the flag is set/modified by a user-specific configuration; + +=item B<env> + +the flag is set/modified by an environment-specific configuration. + +=back + +=item B<--query> + +Print any information that can be useful to explain the behavior of the +program: current vendor, relevant environment variables, feature areas, +state of all feature flags, whether a feature is handled as a builtin +default by the compiler (since dpkg 1.21.14), +and the compiler flags with their origin (since dpkg 1.19.0). + +For example: + + Vendor: Debian + Environment: + DEB_CFLAGS_SET=-O0 -Wall + + Area: qa + Features: + bug=no + canary=no + Builtins: + + Area: hardening + Features: + pie=no + Builtins: + pie=yes + + Area: reproducible + Features: + timeless=no + Builtins: + + Flag: CFLAGS + Value: -O0 -Wall + Origin: env + + Flag: CPPFLAGS + Value: -D_FORTIFY_SOURCE=2 + Origin: vendor + +=item B<--query-features> I<area> + +Print the features enabled for a given area (since dpkg 1.16.2). +If the feature is handled (even if only on some architectures) as a +builtin default by the compiler, then a B<Builtin> field is printed +(since dpkg 1.21.14). +The only currently recognized +areas on Debian and derivatives are B<future>, B<qa>, B<reproducible>, +B<sanitize> and B<hardening>, see the B<FEATURE AREAS> +section for more details. +Exits with 0 if the area is known otherwise exits with 1. + +The output is in RFC822 format, with one section per feature. +For example: + + Feature: pie + Enabled: yes + Builtin: yes + + Feature: stackprotector + Enabled: yes + +=item B<--help> + +Show the usage message and exit. + +=item B<--version> + +Show the version and exit. + +=back + +=head1 SUPPORTED FLAGS + +=over + +=item B<ASFLAGS> + +Options for the host assembler. +Default value: empty. +Since dpkg 1.21.0. + +=item B<CFLAGS> + +Options for the host C compiler. +The default value set by the vendor +includes B<-g> and the default optimization level (B<-O2> usually, +or B<-O0> if the B<DEB_BUILD_OPTIONS> environment variable defines +I<noopt>). + +=item B<CPPFLAGS> + +Options for the host C preprocessor. +Default value: empty. + +=item B<CXXFLAGS> + +Options for the host C++ compiler. +Same as B<CFLAGS>. + +=item B<OBJCFLAGS> + +Options for the host Objective C compiler. +Same as B<CFLAGS>. +Since dpkg 1.17.7. + +=item B<OBJCXXFLAGS> + +Options for the host Objective C++ compiler. +Same as B<CXXFLAGS>. +Since dpkg 1.17.7. + +=item B<DFLAGS> + +Options for the host D compiler (ldc or gdc). +Since dpkg 1.20.6. + +=item B<FFLAGS> + +Options for the host Fortran 77 compiler. +A subset of B<CFLAGS>. + +=item B<FCFLAGS> + +Options for the host Fortran 9x compiler. +Same as B<FFLAGS>. +Since dpkg 1.17.7. + +=item B<LDFLAGS> + +Options passed to the host compiler when linking executables or shared +objects (if the linker is called directly, then +B<-Wl> +and +B<,> +have to be stripped from these options). +Default value: empty. + +=item B<ASFLAGS_FOR_BUILD> + +Options for the build assembler. +Default value: empty. +Since dpkg 1.22.1. + +=item B<CFLAGS_FOR_BUILD> + +Options for the build C compiler. +The default value set by the vendor includes B<-g> and the default +optimization level (B<-O2> usually, or B<-O0> if the B<DEB_BUILD_OPTIONS> +environment variable defines I<noopt>). +Since dpkg 1.22.1. + +=item B<CPPFLAGS_FOR_BUILD> + +Options for the build C preprocessor. +Default value: empty. +Since dpkg 1.22.1. + +=item B<CXXFLAGS_FOR_BUILD> + +Options for the build C++ compiler. +Same as B<CFLAGS_FOR_BUILD>. +Since dpkg 1.22.1. + +=item B<OBJCFLAGS_FOR_BUILD> + +Options for the build Objective C compiler. +Same as B<CFLAGS_FOR_BUILD>. +Since dpkg 1.22.1. + +=item B<OBJCXXFLAGS_FOR_BUILD> + +Options for the build Objective C++ compiler. +Same as B<CXXFLAGS_FOR_BUILD>. +Since dpkg 1.22.1. + +=item B<DFLAGS_FOR_BUILD> + +Options for the build D compiler (ldc or gdc). +Since dpkg 1.22.1. + +=item B<FFLAGS_FOR_BUILD> + +Options for the build Fortran 77 compiler. +A subset of B<CFLAGS_FOR_BUILD>. +Since dpkg 1.22.1. + +=item B<FCFLAGS_FOR_BUILD> + +Options for the build Fortran 9x compiler. +Same as B<FFLAGS_FOR_BUILD>. +Since dpkg 1.22.1. + +=item B<LDFLAGS_FOR_BUILD> + +Options passed to the build compiler when linking executables or shared +objects (if the linker is called directly, then B<-Wl> and B<,> have to +be stripped from these options). +Default value: empty. +Since dpkg 1.22.1. + +=back + +New flags might be added in the future if the need arises (for example +to support other languages). + +=head1 FEATURE AREAS + +Each area feature can be enabled and disabled in the B<DEB_BUILD_OPTIONS> +and B<DEB_BUILD_MAINT_OPTIONS> environment variable's area value with the +‘B<+>’ and ‘B<->’ modifier. +For example, to enable the B<hardening> “pie” feature and disable the +“fortify” feature you can do this in B<debian/rules>: + + export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify + +The special feature B<all> (valid in any area) can be used to enable or +disable all area features at the same time. +Thus disabling everything in the B<hardening> area and enabling only +“format” and “fortify” can be achieved with: + + export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify + +=head2 abi + +Several compile-time options (detailed below) can be used to enable features +that can change the ABI of a package, but cannot be enabled by default due to +backwards compatibility reasons unless coordinated or checked individually. + +=over + +=item B<lfs> + +This setting (since dpkg 1.22.0; disabled by default) enables +Large File Support on 32-bit architectures where their ABI does +not include LFS by default, by adding +B<-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64> to B<CPPFLAGS>. + +When this feature is enabled it will override the value from the same +feature in the B<future> feature area. + +=item B<time64> + +This setting (since dpkg 1.22.0; disabled by default) enables 64-bit time_t +support on 32-bit architectures where their ABI does not include it by +default, by adding B<-D_TIME_BITS=64> to B<CPPFLAGS>. +This setting automatically enables the B<lfs> feature as it requires it. + +=back + +=head2 future + +Several compile-time options (detailed below) can be used to enable features +that should be enabled by default, but cannot due to backwards compatibility +reasons. + +=over + +=item B<lfs> + +This setting (since dpkg 1.19.0; disabled by default) is now an alias +for the B<lfs> feature in the B<abi> area, use that instead. +The feature from the B<abi> area overrides this setting. + +=back + +=head2 qa + +Several compile-time options (detailed below) can be used to help detect +problems in the source code or build system. + +=over + +=item B<bug-implicit-func> + +This setting (since dpkg 1.22.3; disabled by default) adds +B<-Werror=implicit-function-declaration> to B<CFLAGS>. + +=item B<bug> + +This setting (since dpkg 1.17.4; disabled by default) adds any warning +option that reliably detects problematic source code. +The warnings are fatal. +The only currently supported flags are B<CFLAGS> and B<CXXFLAGS> +with flags set to B<-Werror=array-bounds>, B<-Werror=clobbered>, +B<-Werror=implicit-function-declaration> and +B<-Werror=volatile-register-var>. + +This feature handles B<-Werror=implicit-function-declaration> via +the B<bug-implicit-func> feature, if that has not been specified. + +=item B<canary> + +This setting (since dpkg 1.17.14; disabled by default) adds dummy canary +options to the build flags, so that the build logs can be checked for how +the build flags propagate and to allow finding any omission of normal +build flag settings. +The only currently supported flags are B<CPPFLAGS>, B<CFLAGS>, +B<OBJCFLAGS>, B<CXXFLAGS> and B<OBJCXXFLAGS> with flags set +to B<-D__DEB_CANARY_>I<flag>_I<random-id>B<__>, and +B<LDFLAGS> set to B<-Wl,-z,deb-canary->I<random-id>. + +=back + +=head2 optimize + +Several compile-time options (detailed below) can be used to help optimize +a resulting binary (since dpkg 1.21.0). +B<Note>: enabling B<all> these options can result in unreproducible binary +artifacts. + +=over + +=item B<lto> + +This setting (since dpkg 1.21.0; disabled by default) enables +Link Time Optimization by adding B<-flto=auto -ffat-lto-objects> to +B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS>, B<FCFLAGS> and B<LDFLAGS>. + +=back + +=head2 sanitize + +Several compile-time options (detailed below) can be used to help sanitize +a resulting binary against memory corruptions, memory leaks, use after free, +threading data races and undefined behavior bugs. +B<Note>: these options should B<not> be used for production builds +as they can reduce reliability for conformant code, reduce security or +even functionality. + +=over + +=item B<address> + +This setting (since dpkg 1.18.0; disabled by default) adds +B<-fsanitize=address> to +B<LDFLAGS> and B<-fsanitize=address -fno-omit-frame-pointer> to +B<CFLAGS> and B<CXXFLAGS>. + +=item B<thread> + +This setting (since dpkg 1.18.0; disabled by default) adds +B<-fsanitize=thread> to +B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>. + +=item B<leak> + +This setting (since dpkg 1.18.0; disabled by default) adds +B<-fsanitize=leak> to +B<LDFLAGS>. +It gets automatically disabled if either the B<address> +or the B<thread> features are enabled, as they imply it. + +=item B<undefined> + +This setting (since dpkg 1.18.0; disabled by default) adds +B<-fsanitize=undefined> to +B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>. + +=back + +=head2 hardening + +Several compile-time options (detailed below) can be used to help harden +a resulting binary against memory corruption attacks, or provide +additional warning messages during compilation. +Except as noted below, these are enabled by default for architectures +that support them. + +=over + +=item B<format> + +This setting (since dpkg 1.16.1; enabled by default) adds +B<-Wformat -Werror=format-security> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS> and B<OBJCXXFLAGS>. +This will warn about improper format +string uses, and will fail when format functions are used in a way +that represent possible security problems. +At present, this warns about +calls to B<printf> and B<scanf> functions where the format string is +not a string literal and there are no format arguments, as in +B<printf(foo);> instead of B<printf("%s", foo);> +This may be a security hole if the format string came from untrusted +input and contains ‘%n’. + +=item B<fortify> + +This setting (since dpkg 1.16.1; enabled by default) adds +B<-D_FORTIFY_SOURCE=2> +to B<CPPFLAGS>. +During code generation the compiler +knows a great deal of information about buffer sizes (where possible), and +attempts to replace insecure unlimited length buffer function calls with +length-limited ones. +This is especially useful for old, crufty code. +Additionally, format strings in writable memory that contain ‘%n’ are +blocked. +If an application depends on such a format string, it will need +to be worked around. + +Note that for this option to have any effect, the source must also +be compiled with B<-O1> or higher. +If the environment variable +B<DEB_BUILD_OPTIONS> contains I<noopt>, then B<fortify> +support will be disabled, due to new warnings being issued by +glibc 2.16 and later. + +=item B<stackprotector> + +This setting (since dpkg 1.16.1; enabled by default if stackprotectorstrong +is not in use) adds B<-fstack-protector --param=ssp-buffer-size=4> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS>. +This adds safety checks against stack +overwrites. +This renders many potential code injection attacks into aborting situations. +In the best case this turns code injection +vulnerabilities into denial of service or into non-issues (depending on +the application). + +This feature requires linking against glibc (or another provider of +B<__stack_chk_fail>), so needs to be disabled when building with +B<-nostdlib> or B<-ffreestanding> or similar. + +=item B<stackprotectorstrong> + +This setting (since dpkg 1.17.11; enabled by default) adds +B<-fstack-protector-strong> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS>. +This is a stronger variant of B<stackprotector>, but without significant +performance penalties. + +Disabling B<stackprotector> will also disable this setting. + +This feature has the same requirements as B<stackprotector>, and in +addition also requires gcc 4.9 and later. + +=item B<stackclash> + +This setting (since dpkg 1.22.0; enabled by default) adds +B<-fstack-clash-protection> on B<amd64>, B<arm64>, B<armhf> and B<armel> to +B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS>. +This adds code to prevent stack clash style attacks. + +=item B<branch> + +This setting (since dpkg 1.22.0; enabled by default) adds B<-fcf-protection> +on B<amd64> and B<-mbranch-protection=standard> on B<arm64> to +B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS>. +This adds branch protection to indirect calls, jumps and returns to check +whether these are valid at run-time. + +=item B<relro> + +This setting (since dpkg 1.16.1; enabled by default) adds +B<-Wl,-z,relro> +to B<LDFLAGS>. +During program load, +several ELF memory sections need to be written to by the linker. +This flags the loader to turn these sections read-only before turning over +control to the program. +Most notably this prevents GOT overwrite attacks. +If this option is disabled, +B<bindnow> will become disabled as well. + +=item B<bindnow> + +This setting (since dpkg 1.16.1; disabled by default) adds +B<-Wl,-z,now> +to B<LDFLAGS>. +During program load, all dynamic symbols are resolved, +allowing for the entire PLT to be marked read-only (due to B<relro> +above). +The option cannot become enabled if B<relro> is not enabled. + +=item B<pie> + +This setting (since dpkg 1.16.1; with no global default since dpkg 1.18.23, +as it is enabled +by default now by gcc on the amd64, arm64, armel, armhf, hurd-i386, i386, +kfreebsd-amd64, kfreebsd-i386, mips, mipsel, mips64el, powerpc, ppc64, +ppc64el, riscv64, s390x, sparc and sparc64 Debian architectures) adds +the required options to enable or disable PIE via gcc specs files, if +needed, depending on whether gcc injects on that architecture the flags +by itself or not. +When the setting is enabled and gcc injects the flags, it adds nothing. +When the setting is enabled and gcc does not inject the flags, it adds +B<-fPIE> (via I<%PKGDATADIR%/pie-compiler.specs>) to B<CFLAGS>, +B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS>, and +B<-fPIE -pie> (via I<%PKGDATADIR%/pie-link.specs>) to B<LDFLAGS>. +When the setting is disabled and gcc injects the flags, it adds +B<-fno-PIE> (via I<%PKGDATADIR%/no-pie-compile.specs>) to B<CFLAGS>, +B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS>, and +B<-fno-PIE -no-pie> (via I<%PKGDATADIR%/no-pie-link.specs>) to +B<LDFLAGS>. + +Position Independent Executable (PIE) is needed to take advantage of +Address Space Layout Randomization (ASLR), supported by some kernel versions. +While ASLR can already be enforced for data areas in the stack and heap +(brk and mmap), the code areas must be compiled as position-independent. +Shared libraries already do this (B<-fPIC>), so they gain ASLR automatically, +but binary .text regions need to be built as PIE to gain ASLR. +When this happens, ROP (Return Oriented Programming) attacks are much +harder since there are no static locations to bounce off of during a +memory corruption attack. + +PIE is not compatible with B<-fPIC>, so in general care must be taken +when building shared objects. +But because the PIE flags emitted get injected +via gcc specs files, it should always be safe to unconditionally set them +regardless of the object type being compiled or linked. + +Static libraries can be used by programs or other shared libraries. +Depending on the flags used to compile all the objects within a static +library, these libraries will be usable by different sets of objects: + +=over + +=item none + +Cannot be linked into a PIE program, nor a shared library. + +=item B<-fPIE> + +Can be linked into any program, but not a shared library (recommended). + +=item B<-fPIC> + +Can be linked into any program and shared library. + +=back + +If there is a need to set these flags manually, bypassing the gcc specs +injection, there are several things to take into account. +Unconditionally +and explicitly passing B<-fPIE>, B<-fpie> or B<-pie> to a +build-system using libtool is safe as these flags will get stripped +when building shared libraries. +Otherwise on projects that build both programs and shared libraries you +might need to make sure that when building the shared libraries B<-fPIC> +is always passed last (so that it overrides any previous B<-PIE>) to +compilation flags such as B<CFLAGS>, and B<-shared> is passed last +(so that it overrides any previous B<-pie>) to linking flags such as +B<LDFLAGS>. +B<Note>: This should not be needed with the default +gcc specs machinery. + +Additionally, since PIE is implemented via a general register, some +register starved architectures (but not including i386 anymore since +optimizations implemented in gcc E<gt>= 5) can see performance losses of up to +15% in very text-segment-heavy application workloads; most workloads +see less than 1%. +Architectures with more general registers (e.g. amd64) +do not see as high a worst-case penalty. + +=back + +=head2 reproducible + +The compile-time options detailed below can be used to help improve +build reproducibility or provide additional warning messages during +compilation. +Except as noted below, these are enabled by default for +architectures that support them. + +=over + +=item B<timeless> + +This setting (since dpkg 1.17.14; enabled by default) adds +B<-Wdate-time> +to B<CPPFLAGS>. +This will cause warnings when the B<__TIME__>, B<__DATE__> and +B<__TIMESTAMP__> macros are used. + +=item B<fixfilepath> + +This setting (since dpkg 1.19.1; enabled by default) adds +B<-ffile-prefix-map=>I<BUILDPATH>B<=.> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is +set to the top-level directory of the package being built. +This has the effect of removing the build path from any generated file. + +If both B<fixdebugpath> and B<fixfilepath> are set, this option +takes precedence, because it is a superset of the former. + +B<Note>: If the build process captures the build flags into the resulting +built objects, that will make the package unreproducible. +And while disabling this option might make some of the objects reproducible +again this would also require disabling B<fixdebugpath>, which might make +any generated debug symbols objects unreproducible. +The ideal fix is to stop capturing build flags. + +=item B<fixdebugpath> + +This setting (since dpkg 1.18.5; enabled by default) adds +B<-fdebug-prefix-map=>I<BUILDPATH>B<=.> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<FFLAGS> and B<FCFLAGS> where B<BUILDPATH> is +set to the top-level directory of the package being built. +This has the effect of removing the build path from any generated debug +symbols. + +B<Note>: This feature has similar reproducible properties as B<fixfilepath>. + +=back + +=head1 ENVIRONMENT + +There are 2 sets of environment variables doing the same operations, the +first one (DEB_I<flag>_I<op>) should never be used within +B<debian/rules>. +It's meant for any user that wants to rebuild the source package with +different build flags. +The second set +(DEB_I<flag>_MAINT_I<op>) should only be used in B<debian/rules> +by package maintainers to change the resulting build flags. + +=over + +=item B<DEB_>I<flag>B<_SET> + +=item B<DEB_>I<flag>B<_MAINT_SET> (since dpkg 1.16.1) + +This variable can be used to force the value returned for the given +I<flag>. + +=item B<DEB_>I<flag>B<_STRIP> (since dpkg 1.16.1) + +=item B<DEB_>I<flag>B<_MAINT_STRIP> (since dpkg 1.16.1) + +This variable can be used to provide a space separated list of options +that will be stripped from the set of flags returned for the given +I<flag>. + +=item B<DEB_>I<flag>B<_APPEND> + +=item B<DEB_>I<flag>B<_MAINT_APPEND> (since dpkg 1.16.1) + +This variable can be used to append supplementary options to the value +returned for the given I<flag>. + +=item B<DEB_>I<flag>B<_PREPEND> (since dpkg 1.16.1) + +=item B<DEB_>I<flag>B<_MAINT_PREPEND> (since dpkg 1.16.1) + +This variable can be used to prepend supplementary options to the value +returned for the given I<flag>. + +=item B<DEB_BUILD_OPTIONS> + +=item B<DEB_BUILD_MAINT_OPTIONS> (since dpkg 1.16.1) + +These variables can be used by a user or maintainer to disable/enable +various area features that affect build flags. +The B<DEB_BUILD_MAINT_OPTIONS> variable overrides any setting in the +B<DEB_BUILD_OPTIONS> feature areas. +See the L</FEATURE AREAS> section for details. + +=item B<DEB_VENDOR> + +This setting defines the current vendor. +If not set, it will discover the current vendor by reading +B<%PKGCONFDIR%/origins/default>. + +=item B<DEB_BUILD_PATH> + +This variable sets the build path (since dpkg 1.18.8) to use in features +such as B<fixdebugpath> so that they can be controlled by the caller. +This variable is currently Debian and derivatives-specific. + +=item B<DPKG_COLORS> + +Sets the color mode (since dpkg 1.18.5). +The currently accepted values are: B<auto> (default), B<always> and +B<never>. + +=item B<DPKG_NLS> + +If set, it will be used to decide whether to activate Native Language Support, +also known as internationalization (or i18n) support (since dpkg 1.19.0). +The accepted values are: B<0> and B<1> (default). + +=back + +=head1 FILES + +=head2 Configuration files + +=over + +=item B<%PKGCONFDIR%/buildflags.conf> + +System wide configuration file. + +=item B<$XDG_CONFIG_HOME/dpkg/buildflags.conf> or + +=item B<$HOME/.config/dpkg/buildflags.conf> + +User configuration file. + +=back + +=head2 Packaging support + +=over + +=item B<%PKGDATADIR%/buildflags.mk> + +Makefile snippet that will load (and optionally export) all flags +supported by B<dpkg-buildflags> into variables (since dpkg 1.16.1). + +=back + +=head1 EXAMPLES + +To pass build flags to a build command in a Makefile: + +=over + + $(MAKE) $(shell dpkg-buildflags --export=cmdline) + + ./configure $(shell dpkg-buildflags --export=cmdline) + +=back + +To set build flags in a shell script or shell fragment, B<eval> can be +used to interpret the output and to export the flags in the environment: + +=over + + eval "$(dpkg-buildflags --export=sh)" && make + +=back + +or to set the positional parameters to pass to a command: + +=over + + eval "set -- $(dpkg-buildflags --export=cmdline)" + for dir in a b c; do (cd $dir && ./configure "$@" && make); done + +=back + +=head2 Usage in debian/rules + +You should call B<dpkg-buildflags> or include B<buildflags.mk> +from the B<debian/rules> file to obtain the needed build flags to +pass to the build system. +Note that older versions of B<dpkg-buildpackage> (before dpkg 1.16.1) +exported these flags automatically. +However, you should not rely on this, +since this breaks manual invocation of B<debian/rules>. + +For packages with autoconf-like build systems, you can pass the relevant +options to configure or L<make(1)> directly, as shown above. + +For other build systems, or when you need more fine-grained control +about which flags are passed where, you can use B<--get>. +Or you +can include B<buildflags.mk> instead, which takes care of calling +B<dpkg-buildflags> and storing the build flags in make variables. + +If you want to export all buildflags into the environment (where they +can be picked up by your build system): + +=over + + DPKG_EXPORT_BUILDFLAGS = 1 + include %PKGDATADIR%/buildflags.mk + +=back + +For some extra control over what is exported, you can manually export +the variables (as none are exported by default): + +=over + + include %PKGDATADIR%/buildflags.mk + export CPPFLAGS CFLAGS LDFLAGS + +=back + +And you can of course pass the flags to commands manually: + +=over + + include %PKGDATADIR%/buildflags.mk + build-arch: + $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) + +=back |