diff options
Diffstat (limited to '')
| -rw-r--r-- | man/dpkg-buildflags.pod | 782 |
1 files changed, 782 insertions, 0 deletions
diff --git a/man/dpkg-buildflags.pod b/man/dpkg-buildflags.pod new file mode 100644 index 0000000..adf496f --- /dev/null +++ b/man/dpkg-buildflags.pod @@ -0,0 +1,782 @@ +# 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 +B<ENVIRONMENT>); + +=item 4. + +dynamically by the package maintainer with environment variables set via +B<debian/rules> (see section B<ENVIRONMENT>). + +=back + +The configuration files can contain four types of directives: + +=over + +=item B<SET> I<flag value> + +Override the flag named I<flag> to have the value I<value>. + +=item B<STRIP> I<flag value> + +Strip from the flag named I<flag> all the build flags listed in I<value>. + +=item B<APPEND> I<flag 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 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. + +=back + +The configuration files can contain comments on lines starting with a hash +(#). Empty lines are also ignored. + +=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 B<SUPPORTED FLAGS> section for more +information about them. + +=item B<--status> + +Display any information that can be useful to explain the behaviour 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 behaviour of the +program: current vendor, relevant environment variables, feature areas, +state of all feature flags, 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 + + Area: reproducible + Features: + timeless=no + + 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). +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 + + 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<CFLAGS> + +Options for the 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 C preprocessor. Default value: empty. + +=item B<CXXFLAGS> + +Options for the C++ compiler. Same as B<CFLAGS>. + +=item B<OBJCFLAGS> + +Options for the Objective C compiler. Same as B<CFLAGS>. + +=item B<OBJCXXFLAGS> + +Options for the Objective C++ compiler. Same as B<CXXFLAGS>. + +=item B<GCJFLAGS> + +Options for the GNU Java compiler (gcj). A subset of B<CFLAGS>. + +=item B<DFLAGS> + +Options for the D compiler (ldc or gdc). Since dpkg 1.20.6. + +=item B<FFLAGS> + +Options for the Fortran 77 compiler. A subset of B<CFLAGS>. + +=item B<FCFLAGS> + +Options for the Fortran 9x compiler. Same as B<FFLAGS>. + +=item B<LDFLAGS> + +Options passed to the 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. + +=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 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 (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>. + +=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> + +This setting (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>. + +=item B<canary> + +This setting (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 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 (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 (disabled by default) adds B<-fsanitize=thread> to +B<CFLAGS>, B<CXXFLAGS> and B<LDFLAGS>. + +=item B<leak> + +This setting (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 (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 (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 (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 (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<GCJFLAGS>, 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 (enabled by default) adds +B<-fstack-protector-strong> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<GCJFLAGS>, 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<relro> + +This setting (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 (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 (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<GCJFLAGS>, +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<GCJFLAGS>, +B<FFLAGS> and B<FCFLAGS>, and +B<-fno-PIE -no-pie> (via I<%PKGDATADIR%/no-pie-link.specs>) to +B<LDFLAGS>. + +Position Independent +Executable are needed to take advantage of Address Space Layout +Randomization, 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 build 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 (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 (enabled by default) adds +B<-ffile-prefix-map=>I<BUILDPATH>B<=.> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<GCJFLAGS>, 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. + +=item B<fixdebugpath> + +This setting (enabled by default) adds +B<-fdebug-prefix-map=>I<BUILDPATH>B<=.> +to B<CFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, +B<GCJFLAGS>, 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. + +=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> + +This variable can be used to force the value returned for the given +I<flag>. + +=item B<DEB_>I<flag>B<_STRIP> + +=item B<DEB_>I<flag>B<_MAINT_STRIP> + +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> + +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> + +=item B<DEB_>I<flag>B<_MAINT_PREPEND> + +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> + +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 B<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 B<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 |