837 lines
26 KiB
HTML
837 lines
26 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of dpkg-buildflags</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>dpkg-buildflags</H1>
|
|
Section: dpkg suite (1)<BR>Updated: 2020-03-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
dpkg-buildflags - returns build flags to use during package build
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>dpkg-buildflags</B>
|
|
|
|
[<I>option</I>...] [<I>command</I>]
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>dpkg-buildflags</B> 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:
|
|
<DL COMPACT>
|
|
<DT id="1">1.<DD>
|
|
system-wide with <B>/etc/dpkg/buildflags.conf</B>;
|
|
<DT id="2">2.<DD>
|
|
for the current user with <B>$XDG_CONFIG_HOME/dpkg/buildflags.conf</B>
|
|
where <B>$XDG_CONFIG_HOME</B> defaults to <B>$HOME/.config</B>;
|
|
<DT id="3">3.<DD>
|
|
temporarily by the user with environment variables (see section
|
|
<B>ENVIRONMENT</B>);
|
|
<DT id="4">4.<DD>
|
|
dynamically by the package maintainer with environment variables set via
|
|
<B>debian/rules</B> (see section <B>ENVIRONMENT</B>).
|
|
</DL>
|
|
<P>
|
|
|
|
The configuration files can contain four types of directives:
|
|
<DL COMPACT>
|
|
<DT id="5"><B>SET</B><I> flag value</I>
|
|
|
|
<DD>
|
|
Override the flag named <I>flag</I> to have the value <I>value</I>.
|
|
<DT id="6"><B>STRIP</B><I> flag value</I>
|
|
|
|
<DD>
|
|
Strip from the flag named <I>flag</I> all the build flags listed in <I>value</I>.
|
|
<DT id="7"><B>APPEND</B><I> flag value</I>
|
|
|
|
<DD>
|
|
Extend the flag named <I>flag</I> by appending the options given in <I>value</I>.
|
|
A space is prepended to the appended value if the flag's current value is non-empty.
|
|
<DT id="8"><B>PREPEND</B><I> flag value</I>
|
|
|
|
<DD>
|
|
Extend the flag named <I>flag</I> by prepending the options given in <I>value</I>.
|
|
A space is appended to the prepended value if the flag's current value is non-empty.
|
|
</DL>
|
|
<P>
|
|
|
|
The configuration files can contain comments on lines starting with a hash
|
|
(#). Empty lines are also ignored.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>COMMANDS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="9"><B>--dump</B>
|
|
|
|
<DD>
|
|
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>=<I>value</I>"). This is the default action.
|
|
<DT id="10"><B>--list</B>
|
|
|
|
<DD>
|
|
Print the list of flags supported by the current vendor
|
|
(one per line). See the <B>SUPPORTED FLAGS</B> section for more
|
|
information about them.
|
|
<DT id="11"><B>--status</B>
|
|
|
|
<DD>
|
|
Display any information that can be useful to explain the behaviour of
|
|
<B>dpkg-buildflags</B> (since dpkg 1.16.5): relevant environment variables,
|
|
current vendor, state of all feature flags.
|
|
Also print the resulting compiler flags with their origin.
|
|
<P>
|
|
This is intended to be run from <B>debian/rules</B>, so that the build log
|
|
keeps a clear trace of the build flags used. This can be useful to diagnose
|
|
problems related to them.
|
|
<DT id="12"><B>--export=</B><I>format</I>
|
|
|
|
<DD>
|
|
Print to standard output commands that can be used to export all the
|
|
compilation flags for some particular tool. If the <I>format</I> value is not
|
|
given, <B>sh</B> 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:
|
|
<DL COMPACT><DT id="13"><DD>
|
|
<DL COMPACT>
|
|
<DT id="14"><B>sh</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="15"><B>cmdline</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="16"><B>configure</B>
|
|
|
|
<DD>
|
|
This is a legacy alias for <B>cmdline</B>.
|
|
<DT id="17"><B>make</B>
|
|
|
|
<DD>
|
|
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</B> directive.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="18"><B>--get</B><I> flag</I>
|
|
|
|
<DD>
|
|
Print the value of the flag on standard output. Exits with 0
|
|
if the flag is known otherwise exits with 1.
|
|
<DT id="19"><B>--origin</B><I> flag</I>
|
|
|
|
<DD>
|
|
Print the origin of the value that is returned by <B>--get</B>. Exits
|
|
with 0 if the flag is known otherwise exits with 1. The origin can be one
|
|
of the following values:
|
|
<DL COMPACT><DT id="20"><DD>
|
|
<DL COMPACT>
|
|
<DT id="21"><B>vendor</B>
|
|
|
|
<DD>
|
|
the original flag set by the vendor is returned;
|
|
<DT id="22"><B>system</B>
|
|
|
|
<DD>
|
|
the flag is set/modified by a system-wide configuration;
|
|
<DT id="23"><B>user</B>
|
|
|
|
<DD>
|
|
the flag is set/modified by a user-specific configuration;
|
|
<DT id="24"><B>env</B>
|
|
|
|
<DD>
|
|
the flag is set/modified by an environment-specific configuration.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="25"><B>--query</B>
|
|
|
|
<DD>
|
|
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).
|
|
<DT id="26"><DD>
|
|
For example:
|
|
<PRE>
|
|
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
|
|
</PRE>
|
|
|
|
<DT id="27"><B>--query-features</B><I> area</I>
|
|
|
|
<DD>
|
|
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>, <B>qa</B>, <B>reproducible</B>,
|
|
<B>sanitize</B> and <B>hardening</B>, see the <B>FEATURE AREAS</B>
|
|
section for more details.
|
|
Exits with 0 if the area is known otherwise exits with 1.
|
|
<DT id="28"><DD>
|
|
The output is in RFC822 format, with one section per feature.
|
|
For example:
|
|
<DT id="29"><DD>
|
|
<PRE>
|
|
Feature: pie
|
|
Enabled: yes
|
|
|
|
Feature: stackprotector
|
|
Enabled: yes
|
|
</PRE>
|
|
|
|
<DT id="30"><B>--help</B>
|
|
|
|
<DD>
|
|
Show the usage message and exit.
|
|
<DT id="31"><B>--version</B>
|
|
|
|
<DD>
|
|
Show the version and exit.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SUPPORTED FLAGS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="32"><B>CFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the C compiler. The default value set by the vendor
|
|
includes <B>-g</B> and the default optimization level (<B>-O2</B> usually,
|
|
or <B>-O0</B> if the <B>DEB_BUILD_OPTIONS</B> environment variable defines
|
|
<I>noopt</I>).
|
|
<DT id="33"><B>CPPFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the C preprocessor. Default value: empty.
|
|
<DT id="34"><B>CXXFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the C++ compiler. Same as <B>CFLAGS</B>.
|
|
<DT id="35"><B>OBJCFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the Objective C compiler. Same as <B>CFLAGS</B>.
|
|
<DT id="36"><B>OBJCXXFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the Objective C++ compiler. Same as <B>CXXFLAGS</B>.
|
|
<DT id="37"><B>GCJFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the GNU Java compiler (gcj). A subset of <B>CFLAGS</B>.
|
|
<DT id="38"><B>FFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the Fortran 77 compiler. A subset of <B>CFLAGS</B>.
|
|
<DT id="39"><B>FCFLAGS</B>
|
|
|
|
<DD>
|
|
Options for the Fortran 9x compiler. Same as <B>FFLAGS</B>.
|
|
<DT id="40"><B>LDFLAGS</B>
|
|
|
|
<DD>
|
|
Options passed to the compiler when linking executables or shared
|
|
objects (if the linker is called directly, then
|
|
<B>-Wl</B>
|
|
|
|
and
|
|
<B>,</B>
|
|
|
|
have to be stripped from these options). Default value: empty.
|
|
</DL>
|
|
<P>
|
|
|
|
New flags might be added in the future if the need arises (for example
|
|
to support other languages).
|
|
<A NAME="lbAG"> </A>
|
|
<H2>FEATURE AREAS</H2>
|
|
|
|
<P>
|
|
|
|
Each area feature can be enabled and disabled in the <B>DEB_BUILD_OPTIONS</B>
|
|
and <B>DEB_BUILD_MAINT_OPTIONS</B> environment variable's area value with the
|
|
'<B>+</B>' and '<B>-</B>' modifier.
|
|
For example, to enable the <B>hardening</B> "pie" feature and disable the
|
|
"fortify" feature you can do this in <B>debian/rules</B>:
|
|
<P>
|
|
|
|
<BR> export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
|
|
<P>
|
|
|
|
The special feature <B>all</B> (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</B> area and enabling only
|
|
"format" and "fortify" can be achieved with:
|
|
<P>
|
|
|
|
<BR> export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
|
|
<A NAME="lbAH"> </A>
|
|
<H3>future</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="41"><B>lfs</B>
|
|
|
|
<DD>
|
|
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</B> to <B>CPPFLAGS</B>.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>qa</H3>
|
|
|
|
Several compile-time options (detailed below) can be used to help detect
|
|
problems in the source code or build system.
|
|
<DL COMPACT>
|
|
<DT id="42"><B>bug</B>
|
|
|
|
<DD>
|
|
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</B> and <B>CXXFLAGS</B>
|
|
with flags set to <B>-Werror=array-bounds</B>, <B>-Werror=clobbered</B>,
|
|
<B>-Werror=implicit-function-declaration</B> and
|
|
<B>-Werror=volatile-register-var</B>.
|
|
<DT id="43"><B>canary</B>
|
|
|
|
<DD>
|
|
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>, <B>CFLAGS</B>,
|
|
<B>OBJCFLAGS</B>, <B>CXXFLAGS</B> and <B>OBJCXXFLAGS</B> with flags set
|
|
to <B>-D__DEB_CANARY_</B><I>flag</I>_<I>random-id</I><B>__</B>, and
|
|
<B>LDFLAGS</B> set to <B>-Wl,-z,deb-canary-</B><I>random-id</I>.
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>sanitize</H3>
|
|
|
|
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</B>: these options should <B>not</B> be used for production builds
|
|
as they can reduce reliability for conformant code, reduce security or
|
|
even functionality.
|
|
<DL COMPACT>
|
|
<DT id="44"><B>address</B>
|
|
|
|
<DD>
|
|
This setting (disabled by default) adds <B>-fsanitize=address</B> to
|
|
<B>LDFLAGS</B> and <B>-fsanitize=address -fno-omit-frame-pointer</B> to
|
|
<B>CFLAGS</B> and <B>CXXFLAGS</B>.
|
|
<DT id="45"><B>thread</B>
|
|
|
|
<DD>
|
|
This setting (disabled by default) adds <B>-fsanitize=thread</B> to
|
|
<B>CFLAGS</B>, <B>CXXFLAGS</B> and <B>LDFLAGS</B>.
|
|
<DT id="46"><B>leak</B>
|
|
|
|
<DD>
|
|
This setting (disabled by default) adds <B>-fsanitize=leak</B> to
|
|
<B>LDFLAGS</B>. It gets automatically disabled if either the <B>address</B>
|
|
or the <B>thread</B> features are enabled, as they imply it.
|
|
<DT id="47"><B>undefined</B>
|
|
|
|
<DD>
|
|
This setting (disabled by default) adds <B>-fsanitize=undefined</B> to
|
|
<B>CFLAGS</B>, <B>CXXFLAGS</B> and <B>LDFLAGS</B>.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>hardening</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="48"><B>format</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default) adds
|
|
<B>-Wformat -Werror=format-security</B>
|
|
|
|
to <B>CFLAGS</B>, <B>CXXFLAGS</B>, <B>OBJCFLAGS</B> and <B>OBJCXXFLAGS</B>.
|
|
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</B> and <B>scanf</B> functions where the format string is
|
|
not a string literal and there are no format arguments, as in
|
|
<B>printf(foo);</B> instead of printf("%s", foo);
|
|
This may be a security hole if the format string came from untrusted
|
|
input and contains '%n'.
|
|
<DT id="49"><B>fortify</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default) adds
|
|
<B>-D_FORTIFY_SOURCE=2</B>
|
|
|
|
to <B>CPPFLAGS</B>. 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.
|
|
<P>
|
|
Note that for this option to have any effect, the source must also
|
|
be compiled with <B>-O1</B> or higher. If the environment variable
|
|
<B>DEB_BUILD_OPTIONS</B> contains <I>noopt</I>, then <B>fortify</B>
|
|
support will be disabled, due to new warnings being issued by
|
|
glibc 2.16 and later.
|
|
<DT id="50"><B>stackprotector</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default if stackprotectorstrong is not in use) adds
|
|
<B>-fstack-protector --param=ssp-buffer-size=4</B>
|
|
|
|
to <B>CFLAGS</B>, <B>CXXFLAGS</B>, <B>OBJCFLAGS</B>, <B>OBJCXXFLAGS</B>,
|
|
<B>GCJFLAGS</B>, <B>FFLAGS</B> and <B>FCFLAGS</B>.
|
|
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).
|
|
<P>
|
|
This feature requires linking against glibc (or another provider of
|
|
<B>__stack_chk_fail</B>), so needs to be disabled when building with
|
|
<B>-nostdlib</B> or <B>-ffreestanding</B> or similar.
|
|
<DT id="51"><B>stackprotectorstrong</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default) adds
|
|
<B>-fstack-protector-strong</B>
|
|
|
|
to <B>CFLAGS</B>, <B>CXXFLAGS</B>, <B>OBJCFLAGS</B>, <B>OBJCXXFLAGS</B>,
|
|
<B>GCJFLAGS</B>, <B>FFLAGS</B> and <B>FCFLAGS</B>.
|
|
This is a stronger variant of <B>stackprotector</B>, but without significant
|
|
performance penalties.
|
|
<P>
|
|
Disabling <B>stackprotector</B> will also disable this setting.
|
|
<P>
|
|
This feature has the same requirements as <B>stackprotector</B>, and in
|
|
addition also requires gcc 4.9 and later.
|
|
<DT id="52"><B>relro</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default) adds
|
|
<B>-Wl,-z,relro</B>
|
|
|
|
to <B>LDFLAGS</B>. 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</B> will become disabled as well.
|
|
<DT id="53"><B>bindnow</B>
|
|
|
|
<DD>
|
|
This setting (disabled by default) adds
|
|
<B>-Wl,-z,now</B>
|
|
|
|
to <B>LDFLAGS</B>. During program load, all dynamic symbols are resolved,
|
|
allowing for the entire PLT to be marked read-only (due to <B>relro</B>
|
|
above). The option cannot become enabled if <B>relro</B> is not enabled.
|
|
<DT id="54"><B>pie</B>
|
|
|
|
<DD>
|
|
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</B> (via <I>/usr/share/dpkg/pie-compiler.specs</I>) to <B>CFLAGS</B>,
|
|
<B>CXXFLAGS</B>, <B>OBJCFLAGS</B>, <B>OBJCXXFLAGS</B>, <B>GCJFLAGS</B>,
|
|
<B>FFLAGS</B> and <B>FCFLAGS</B>, and
|
|
<B>-fPIE -pie</B> (via <I>/usr/share/dpkg/pie-link.specs</I>) to <B>LDFLAGS</B>.
|
|
When the setting is disabled and gcc injects the flags, it adds
|
|
<B>-fno-PIE</B> (via <I>/usr/share/dpkg/no-pie-compile.specs</I>) to <B>CFLAGS</B>,
|
|
<B>CXXFLAGS</B>, <B>OBJCFLAGS</B>, <B>OBJCXXFLAGS</B>, <B>GCJFLAGS</B>,
|
|
<B>FFLAGS</B> and <B>FCFLAGS</B>, and
|
|
<B>-fno-PIE -no-pie</B> (via <I>/usr/share/dpkg/no-pie-link.specs</I>) to
|
|
<B>LDFLAGS</B>.
|
|
<P>
|
|
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</B>), 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.
|
|
<P>
|
|
PIE is not compatible with <B>-fPIC</B>, 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.
|
|
<P>
|
|
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:
|
|
<P>
|
|
<DL COMPACT><DT id="55"><DD>
|
|
<DL COMPACT>
|
|
<DT id="56">none<DD>
|
|
Cannot be linked into a PIE program, nor a shared library.
|
|
<DT id="57"><B>-fPIE</B>
|
|
|
|
<DD>
|
|
Can be linked into any program, but not a shared library (recommended).
|
|
<DT id="58"><B>-fPIC</B>
|
|
|
|
<DD>
|
|
Can be linked into any program and shared library.
|
|
</DL>
|
|
</DL>
|
|
|
|
<P>
|
|
<DT id="59"><DD>
|
|
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>, <B>-fpie</B> or <B>-pie</B> 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</B>
|
|
is always passed last (so that it overrides any previous <B>-PIE</B>) to
|
|
compilation flags such as <B>CFLAGS</B>, and <B>-shared</B> is passed last
|
|
(so that it overrides any previous <B>-pie</B>) to linking flags such as
|
|
<B>LDFLAGS</B>. <B>Note:</B> This should not be needed with the default
|
|
gcc specs machinery.
|
|
<P>
|
|
<DT id="60"><DD>
|
|
Additionally, since PIE is implemented via a general register, some
|
|
register starved architectures (but not including i386 anymore since
|
|
optimizations implemented in gcc >= 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.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H3>reproducible</H3>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="61"><B>timeless</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default) adds
|
|
<B>-Wdate-time</B>
|
|
|
|
to <B>CPPFLAGS</B>.
|
|
This will cause warnings when the <B>__TIME__</B>, <B>__DATE__</B> and
|
|
<B>__TIMESTAMP__</B> macros are used.
|
|
<DT id="62"><B>fixfilepath</B>
|
|
|
|
<DD>
|
|
This setting (disabled by default) adds
|
|
<B>-ffile-prefix-map=</B><I>BUILDPATH</I><B>=.</B>
|
|
|
|
to <B>CFLAGS</B>, <B>CXXFLAGS</B>, <B>OBJCFLAGS</B>, <B>OBJCXXFLAGS</B>,
|
|
<B>GCJFLAGS</B>, <B>FFLAGS</B> and <B>FCFLAGS</B> where <B>BUILDPATH</B> 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.
|
|
<P>
|
|
If both <B>fixdebugpath</B> and <B>fixfilepath</B> are set, this option
|
|
takes precedence, because it is a superset of the former.
|
|
<DT id="63"><B>fixdebugpath</B>
|
|
|
|
<DD>
|
|
This setting (enabled by default) adds
|
|
<B>-fdebug-prefix-map=</B><I>BUILDPATH</I><B>=.</B>
|
|
|
|
to <B>CFLAGS</B>, <B>CXXFLAGS</B>, <B>OBJCFLAGS</B>, <B>OBJCXXFLAGS</B>,
|
|
<B>GCJFLAGS</B>, <B>FFLAGS</B> and <B>FCFLAGS</B> where <B>BUILDPATH</B> 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.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
There are 2 sets of environment variables doing the same operations, the
|
|
first one (DEB_<I>flag</I>_<I>op</I>) should never be used within
|
|
<B>debian/rules</B>. It's meant for any user that wants to rebuild the
|
|
source package with different build flags. The second set
|
|
(DEB_<I>flag</I>_MAINT_<I>op</I>) should only be used in <B>debian/rules</B>
|
|
by package maintainers to change the resulting build flags.
|
|
<DL COMPACT>
|
|
<DT id="64"><B>DEB_</B><I>flag</I><B>_SET</B>
|
|
|
|
<DD>
|
|
|
|
<B>DEB_</B><I>flag</I><B>_MAINT_SET</B>
|
|
|
|
This variable can be used to force the value returned for the given
|
|
<I>flag</I>.
|
|
<DT id="65"><B>DEB_</B><I>flag</I><B>_STRIP</B>
|
|
|
|
<DD>
|
|
|
|
<B>DEB_</B><I>flag</I><B>_MAINT_STRIP</B>
|
|
|
|
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</I>.
|
|
<DT id="66"><B>DEB_</B><I>flag</I><B>_APPEND</B>
|
|
|
|
<DD>
|
|
|
|
<B>DEB_</B><I>flag</I><B>_MAINT_APPEND</B>
|
|
|
|
This variable can be used to append supplementary options to the value
|
|
returned for the given <I>flag</I>.
|
|
<DT id="67"><B>DEB_</B><I>flag</I><B>_PREPEND</B>
|
|
|
|
<DD>
|
|
|
|
<B>DEB_</B><I>flag</I><B>_MAINT_PREPEND</B>
|
|
|
|
This variable can be used to prepend supplementary options to the value
|
|
returned for the given <I>flag</I>.
|
|
<DT id="68"><B>DEB_BUILD_OPTIONS</B>
|
|
|
|
<DD>
|
|
|
|
<B>DEB_BUILD_MAINT_OPTIONS</B>
|
|
|
|
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</B> variable overrides any setting in the
|
|
<B>DEB_BUILD_OPTIONS</B> feature areas.
|
|
See the <B>FEATURE AREAS</B> section for details.
|
|
<DT id="69"><B>DEB_VENDOR</B>
|
|
|
|
<DD>
|
|
This setting defines the current vendor.
|
|
If not set, it will discover the current vendor by reading
|
|
<B>/etc/dpkg/origins/default</B>.
|
|
<DT id="70"><B>DEB_BUILD_PATH</B>
|
|
|
|
<DD>
|
|
This variable sets the build path (since dpkg 1.18.8) to use in features
|
|
such as <B>fixdebugpath</B> so that they can be controlled by the caller.
|
|
This variable is currently Debian and derivatives-specific.
|
|
<DT id="71"><B>DPKG_COLORS</B>
|
|
|
|
<DD>
|
|
Sets the color mode (since dpkg 1.18.5).
|
|
The currently accepted values are: <B>auto</B> (default), <B>always</B> and
|
|
<B>never</B>.
|
|
<DT id="72"><B>DPKG_NLS</B>
|
|
|
|
<DD>
|
|
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</B> and <B>1</B> (default).
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Configuration files</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="73"><B>/etc/dpkg/buildflags.conf</B>
|
|
|
|
<DD>
|
|
System wide configuration file.
|
|
<DT id="74"><B>$XDG_CONFIG_HOME/dpkg/buildflags.conf</B> or
|
|
|
|
<DD>
|
|
|
|
<B>$HOME/.config/dpkg/buildflags.conf</B>
|
|
|
|
User configuration file.
|
|
</DL>
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Packaging support</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="75"><B>/usr/share/dpkg/buildflags.mk</B>
|
|
|
|
<DD>
|
|
Makefile snippet that will load (and optionally export) all flags
|
|
supported by <B>dpkg-buildflags</B> into variables (since dpkg 1.16.1).
|
|
</DL>
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
To pass build flags to a build command in a Makefile:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="76"><DD>
|
|
<PRE>
|
|
$(MAKE) $(shell dpkg-buildflags --export=cmdline)
|
|
|
|
./configure $(shell dpkg-buildflags --export=cmdline)
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
To set build flags in a shell script or shell fragment, <B>eval</B> can be
|
|
used to interpret the output and to export the flags in the environment:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="77"><DD>
|
|
<PRE>
|
|
eval "$(dpkg-buildflags --export=sh)" && make
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
or to set the positional parameters to pass to a command:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="78"><DD>
|
|
<PRE>
|
|
eval "set -- $(dpkg-buildflags --export=cmdline)"
|
|
for dir in a b c; do (cd $dir && ./configure "$@" && make); done
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Usage in debian/rules</H3>
|
|
|
|
You should call <B>dpkg-buildflags</B> or include <B>buildflags.mk</B>
|
|
from the <B>debian/rules</B> file to obtain the needed build flags to
|
|
pass to the build system.
|
|
Note that older versions of <B>dpkg-buildpackage</B> (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</B>.
|
|
<P>
|
|
|
|
For packages with autoconf-like build systems, you can pass the relevant
|
|
options to configure or <B><A HREF="/cgi-bin/man/man2html?1+make">make</A></B>(1) directly, as shown above.
|
|
<P>
|
|
|
|
For other build systems, or when you need more fine-grained control
|
|
about which flags are passed where, you can use <B>--get</B>. Or you
|
|
can include <B>buildflags.mk</B> instead, which takes care of calling
|
|
<B>dpkg-buildflags</B> and storing the build flags in make variables.
|
|
<P>
|
|
|
|
If you want to export all buildflags into the environment (where they
|
|
can be picked up by your build system):
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="79"><DD>
|
|
<PRE>
|
|
DPKG_EXPORT_BUILDFLAGS = 1
|
|
include /usr/share/dpkg/buildflags.mk
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
For some extra control over what is exported, you can manually export
|
|
the variables (as none are exported by default):
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="80"><DD>
|
|
<PRE>
|
|
include /usr/share/dpkg/buildflags.mk
|
|
export CPPFLAGS CFLAGS LDFLAGS
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
And you can of course pass the flags to commands manually:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="81"><DD>
|
|
<PRE>
|
|
include /usr/share/dpkg/buildflags.mk
|
|
build-arch:
|
|
$(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="82"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="83"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="84"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="85"><A HREF="#lbAE">COMMANDS</A><DD>
|
|
<DT id="86"><A HREF="#lbAF">SUPPORTED FLAGS</A><DD>
|
|
<DT id="87"><A HREF="#lbAG">FEATURE AREAS</A><DD>
|
|
<DL>
|
|
<DT id="88"><A HREF="#lbAH">future</A><DD>
|
|
<DT id="89"><A HREF="#lbAI">qa</A><DD>
|
|
<DT id="90"><A HREF="#lbAJ">sanitize</A><DD>
|
|
<DT id="91"><A HREF="#lbAK">hardening</A><DD>
|
|
<DT id="92"><A HREF="#lbAL">reproducible</A><DD>
|
|
</DL>
|
|
<DT id="93"><A HREF="#lbAM">ENVIRONMENT</A><DD>
|
|
<DT id="94"><A HREF="#lbAN">FILES</A><DD>
|
|
<DL>
|
|
<DT id="95"><A HREF="#lbAO">Configuration files</A><DD>
|
|
<DT id="96"><A HREF="#lbAP">Packaging support</A><DD>
|
|
</DL>
|
|
<DT id="97"><A HREF="#lbAQ">EXAMPLES</A><DD>
|
|
<DL>
|
|
<DT id="98"><A HREF="#lbAR">Usage in debian/rules</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:11 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|