Adding upstream version 1.22.4.upstream/1.22.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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