Adding upstream version 1.20.13.upstream/1.20.13upstream

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

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