dpkg-buildflags


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

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

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

       --status
              Display any information that can be useful to explain the behav-
              iour of dpkg-buildflags: relevant environment variables, current
              assumed  to  not be suitable for the environment. Supported for-
              mats:

              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.

              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.

              configure
                     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  direc-
                     tive.

       --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  configura-
                     tion;

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

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

              Options for the C preprocessor. Default value: empty.

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

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

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

       LDFLAGS
              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 languages).

FEATURE AREAS
   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.

       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 dis-
       able the "fortify" feature you can do this in debian/rules:

         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=for-
              mat-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".

       fortify
              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
              --param=ssp-buffer-size=4 to  CFLAGS  and  CXXFLAGS.  This  adds
              safety checks against stack overwrites. This renders many poten-
              tial 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.

       bindnow
              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 enabled.

       pie    This setting (disabled by default)  adds  -fPIE  to  CFLAGS  and
              CXXFLAGS,  and  -fPIE -pie to LDFLAGS. Position Independent Exe-
              cutable 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-indepen-
              dent. 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  Pro-
              gramming)  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 objects.

              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 work-
              loads; most workloads see less than 1%. Architectures with  more
              general  registers  (e.g. amd64) do not see as high a worst-case
              penalty.

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

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

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

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

FILES
   Configuration files
       /etc/dpkg/buildflags.conf
              System wide configuration file.

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

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

EXAMPLES
       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  environ-
       ment:

           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  buildflags.mk 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 rele-

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

           include /usr/share/dpkg/buildflags.mk
           export CPPFLAGS CFLAGS LDFLAGS

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

           include /usr/share/dpkg/buildflags.mk
           build-arch:
                $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)



Debian Project                    2013-10-20                dpkg-buildflags(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2018 Hurricane Electric. All Rights Reserved.