Provided by: dpkg-dev_1.17.5ubuntu5.8_all bug


       dpkg-buildflags - returns build flags to use during package build


       dpkg-buildflags [option...] [command]


       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/overriden
       in several ways:

       1.     system-wide with /etc/dpkg/buildflags.conf;

       2.     for    the    current   user   with   $XDG_CONFIG_HOME/dpkg/buildflags.conf   where
              $XDG_CONFIG_HOME defaults to $HOME/.config;

       3.     temporarily by the user with environment variables (see section ENVIRONMENT);

       4.     dynamically  by  the  package  maintainer  with  environment  variables   set   via
              debian/rules (see section ENVIRONMENT).

       The configuration files can contain two types of directives:

       SET flag value
              Override the flag named flag to have the value value.

       STRIP flag value
              Strip from the flag named flag all the build flags listed in value.

       APPEND flag value
              Extend  the  flag  named  flag by appending the options given in value.  A space is
              prepended to the appended value if the flag's current value is non-empty.

       PREPEND flag value
              Extend the flag named flag by prepending the options given in value.   A  space  is
              appended to the prepended value if the flag's current value is non-empty.

       The  configuration  files  can  contain  comments on lines starting with a hash (#). Empty
       lines are also ignored.


       --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 ("flag=value"). This is the
              default action.

       --list Print the list of flags supported by the current vendor (one  per  line).  See  the
              SUPPORTED FLAGS section for more information about them.

              Display   any   information  that  can  be  useful  to  explain  the  behaviour  of
              dpkg-buildflags: 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 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

              Print  to  standard  output commands that can be used to export all the compilation
              flags for some particular tool. If the format value is not given,  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:

              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.

                     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

                     This is a legacy alias for cmdline.

              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 include directive.

       --get flag
              Print the value of the flag on standard output. Exits with 0 if the flag  is  known
              otherwise exits with 1.

       --origin flag
              Print  the  origin of the value that is returned by --get. Exits with 0 if the flag
              is known otherwise exits with 1. The origin can be one of the following values:

              vendor the original flag set by the vendor is returned;

              system the flag is set/modified by a system-wide configuration;

              user   the flag is set/modified by a user-specific configuration;

              env    the flag is set/modified by an environment-specific configuration.

       --query-features area
              Print the features enabled for a given area. The only currently recognized area  is
              hardening,  see  the  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: no

                Feature: stackprotector
                Enabled: yes

       --help Show the usage message and exit.

              Show the version and exit.


       CFLAGS Options for the C compiler. The default value set by the vendor includes -g and the
              default   optimization   level  (-O2  usually,  or  -O0  if  the  DEB_BUILD_OPTIONS
              environment variable defines noopt).

              Options for the C preprocessor. Default value: empty.

              Options for the C++ compiler. Same as CFLAGS.

              Options for the GNU Java compiler (gcj). A subset of CFLAGS.

       FFLAGS Options for the Fortran compiler. A subset of CFLAGS.

              Options passed to the compiler when linking executables or shared objects  (if  the
              linker  is called directly, then -Wl and , have to be stripped from these options).
              Default value: empty.

       New flags might be added in the future if the need arises (for example  to  support  other


       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.

       Each hardening  feature  can  be  enabled  and  disabled  in  the  DEB_BUILD_MAINT_OPTIONS
       environment  variable's  hardening  value  with  the "+" and "-" modifier. For example, to
       enable  the  "pie"  feature  and  disable  the  "fortify"  feature  you  can  do  this  in

         export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify

       The  special  feature  all  can be used to enable or disable all hardening features at the
       same time. Thus disabling everything and enabling  only  "format"  and  "fortify"  can  be
       achieved with:

         export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify

       format This  setting  (enabled by default) adds -Wformat -Werror=format-security to CFLAGS
              and CXXFLAGS. 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 printf and  scanf  functions  where  the  format
              string  is  not  a  string  literal  and  there  are  no  format  arguments,  as in
              printf(foo); instead of printf("%s", foo); This may  be  a  security  hole  if  the
              format string came from untrusted input and contains "%n".

              This setting (enabled by default) adds -D_FORTIFY_SOURCE=2 to 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
              -O1  or  higher. If the environment variable DEB_BUILD_OPTIONS contains noopt, then
              fortify support will be disabled, due to new warnings being issued  by  glibc  2.16
              and later.

              This  setting (enabled by default) adds -fstack-protector --param=ssp-buffer-size=4
              to CFLAGS and CXXFLAGS. 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
              __stack_chk_fail), so  needs  to  be  disabled  when  building  with  -nostdlib  or
              -ffreestanding or similar.

       relro  This  setting  (enabled  by  default) adds -Wl,-z,relro to 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, bindnow will become disabled as well.

              This setting (disabled by default) adds -Wl,-z,now to LDFLAGS. During program load,
              all dynamic symbols are resolved, allowing for the entire PLT to  be  marked  read-
              only  (due  to  relro  above).  The  option  cannot  become enabled if relro is not

       pie    This setting (disabled by default) adds -fPIE to CFLAGS  and  CXXFLAGS,  and  -fPIE
              -pie  to  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  (-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.

              This is not compatible with -fPIC so  care  must  be  taken  when  building  shared

              Additionally,  since  PIE is implemented via a general register, some architectures
              (most notably i386) 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.


       There are 2 sets of environment  variables  doing  the  same  operations,  the  first  one
       (DEB_flag_op) should never be used within debian/rules. It's meant for any user that wants
       to  rebuild  the  source  package   with   different   build   flags.   The   second   set
       (DEB_flag_MAINT_op)  should  only be used in debian/rules by package maintainers to change
       the resulting build flags.

              This variable can be used to force the value returned for the given flag.

              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 flag.

              This variable can be used to append supplementary options to the value returned for
              the given flag.

              This variable can be used to prepend supplementary options to  the  value  returned
              for the given flag.

              This  variable  can be used to disable/enable various hardening build flags through
              the hardening option. See the FEATURE AREAS section for details.


   Configuration files
              System wide configuration file.

       $XDG_CONFIG_HOME/dpkg/buildflags.conf or $HOME/.config/dpkg/buildflags.conf
              User configuration file.

   Packaging support
              Makefile snippet that will load (and optionally  export)  all  flags  supported  by
              dpkg-buildflags into variables (since dpkg 1.16.1).


       To pass build flags to a build command in a makefile:

           $(MAKE) $(shell dpkg-buildflags --export=cmdline)

           ./configure $(shell dpkg-buildflags --export=cmdline)

       To  set  build  flags in a shell script or shell fragment, "eval" can be used to interpret
       the output and to export the flags in the environment:

           eval "$(dpkg-buildflags --export=sh)" && make

       or to set the positional parameters to pass to a command:

           eval "set -- $(dpkg-buildflags --export=cmdline)"
           for dir in a b c; do (cd $dir && ./configure "$@" && make); done

   Usage in debian/rules
       You should call dpkg-buildflags or include from  the  debian/rules  file  to
       obtain  the  needed  build flags to pass to the build system.  Note that older versions of
       dpkg-buildpackage (before dpkg 1.16.1) exported these flags  automatically.  However,  you
       should not rely on this, since this breaks manual invocation of debian/rules.

       For  packages  with  autoconf-like  build  systems,  you  can pass the relevant options to
       configure or 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 --get. Or you can include instead, which takes
       care of calling 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):

           include /usr/share/dpkg/

       For  some  extra  control over what is exported, you can manually export the variables (as
       none are exported by default):

           include /usr/share/dpkg/

       And you can of course pass the flags to commands manually:

           include /usr/share/dpkg/
                $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)