1dpkg-buildflags(1)                dpkg suite                dpkg-buildflags(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

12       dpkg-buildflags  is  a tool to retrieve compilation flags to use during
13       build of Debian packages.  The default flags are defined by the  vendor
14       but they can be extended/overridden in several ways:
15
16       1.     system-wide with /etc/dpkg/buildflags.conf;
17
18       2.     for  the current user with $XDG_CONFIG_HOME/dpkg/buildflags.conf
19              where $XDG_CONFIG_HOME defaults to $HOME/.config;
20
21       3.     temporarily by the user with environment variables (see  section
22              ENVIRONMENT);
23
24       4.     dynamically by the package maintainer with environment variables
25              set via debian/rules (see section ENVIRONMENT).
26
27       The configuration files can contain four types of directives:
28
29       SET flag value
30              Override the flag named flag to have the value value.
31
32       STRIP flag value
33              Strip from the flag named flag all the  build  flags  listed  in
34              value.
35
36       APPEND flag value
37              Extend  the  flag  named  flag by appending the options given in
38              value.  A space is prepended to the appended value if the flag's
39              current value is non-empty.
40
41       PREPEND flag value
42              Extend  the  flag  named flag by prepending the options given in
43              value.  A space is appended to the prepended value if the flag's
44              current value is non-empty.
45
46       The  configuration  files can contain comments on lines starting with a
47       hash (#). Empty lines are also ignored.
48

COMMANDS

50       --dump Print to standard output all compilation flags and their values.
51              It prints one flag per line separated from its value by an equal
52              sign (“flag=value”). This is the default action.
53
54       --list Print the list of flags supported by the current vendor (one per
55              line).  See  the  SUPPORTED  FLAGS  section for more information
56              about them.
57
58       --status
59              Display any information  that  can  be  useful  to  explain  the
60              behaviour  of  dpkg-buildflags  (since  dpkg  1.16.5):  relevant
61              environment variables, current  vendor,  state  of  all  feature
62              flags.   Also  print  the  resulting  compiler  flags with their
63              origin.
64
65              This is intended to be run from debian/rules, so that the  build
66              log  keeps  a  clear  trace of the build flags used. This can be
67              useful to diagnose problems related to them.
68
69       --export=format
70              Print to standard output commands that can be used to export all
71              the  compilation  flags  for some particular tool. If the format
72              value is not  given,  sh  is  assumed.  Only  compilation  flags
73              starting  with  an upper case character are included, others are
74              assumed to  not  be  suitable  for  the  environment.  Supported
75              formats:
76
77              sh     Shell  commands  to  set  and  export all the compilation
78                     flags in the environment. The flag values are  quoted  so
79                     the output is ready for evaluation by a shell.
80
81              cmdline
82                     Arguments  to  pass  to a build program's command line to
83                     use all the compilation flags (since  dpkg  1.17.0).  The
84                     flag values are quoted in shell syntax.
85
86              configure
87                     This is a legacy alias for cmdline.
88
89              make   Make  directives  to  set  and export all the compilation
90                     flags in the environment. Output  can  be  written  to  a
91                     makefile   fragment   and   evaluated  using  an  include
92                     directive.
93
94       --get flag
95              Print the value of the flag on standard output. Exits with 0  if
96              the flag is known otherwise exits with 1.
97
98       --origin flag
99              Print  the  origin of the value that is returned by --get. Exits
100              with 0 if the flag is known otherwise exits with 1.  The  origin
101              can be one of the following values:
102
103              vendor the original flag set by the vendor is returned;
104
105              system the flag is set/modified by a system-wide configuration;
106
107              user   the    flag    is   set/modified   by   a   user-specific
108                     configuration;
109
110              env    the  flag  is  set/modified  by  an  environment-specific
111                     configuration.
112
113       --query-features area
114              Print the features enabled for a given area (since dpkg 1.16.2).
115              The only currently recognized areas on  Debian  and  derivatives
116              are  qa,  reproducible,  sanitize and hardening, see the FEATURE
117              AREAS section for more details.  Exits with 0  if  the  area  is
118              known otherwise exits with 1.
119
120              The  output  is  in RFC822 format, with one section per feature.
121              For example:
122
123                Feature: pie
124                Enabled: yes
125
126                Feature: stackprotector
127                Enabled: yes
128
129       --help Show the usage message and exit.
130
131       --version
132              Show the version and exit.
133

SUPPORTED FLAGS

135       CFLAGS Options for the C compiler. The default value set by the  vendor
136              includes  -g and the default optimization level (-O2 usually, or
137              -O0  if  the  DEB_BUILD_OPTIONS  environment  variable   defines
138              noopt).
139
140       CPPFLAGS
141              Options for the C preprocessor. Default value: empty.
142
143       CXXFLAGS
144              Options for the C++ compiler. Same as CFLAGS.
145
146       OBJCFLAGS
147              Options for the Objective C compiler. Same as CFLAGS.
148
149       OBJCXXFLAGS
150              Options for the Objective C++ compiler. Same as CXXFLAGS.
151
152       GCJFLAGS
153              Options for the GNU Java compiler (gcj). A subset of CFLAGS.
154
155       FFLAGS Options for the Fortran 77 compiler. A subset of CFLAGS.
156
157       FCFLAGS
158              Options for the Fortran 9x compiler. Same as FFLAGS.
159
160       LDFLAGS
161              Options  passed  to  the  compiler  when  linking executables or
162              shared objects (if the linker is called directly, then -Wl and ,
163              have to be stripped from these options). Default value: empty.
164
165       New  flags might be added in the future if the need arises (for example
166       to support other languages).
167

FEATURE AREAS

169       Each area feature can be enabled and disabled in the  DEB_BUILD_OPTIONS
170       and  DEB_BUILD_MAINT_OPTIONS environment variable's area value with the
171+’ and ‘-’ modifier.  For  example,  to  enable  the  hardening  “pie”
172       feature   and  disable  the  “fortify”  feature  you  can  do  this  in
173       debian/rules:
174
175         export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
176
177       The special feature all (valid in any area) can be used  to  enable  or
178       disable  all area features at the same time.  Thus disabling everything
179       in the hardening area and enabling only “format” and “fortify”  can  be
180       achieved with:
181
182         export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
183
184   qa
185       Several  compile-time  options  (detailed  below)  can  be used to help
186       detect problems in the source code or build system.
187
188       bug    This setting (disabled by default) adds any warning option  that
189              reliably  detects  problematic  source  code.  The  warnings are
190              fatal.  The  only  currently  supported  flags  are  CFLAGS  and
191              CXXFLAGS     with    flags    set    to    -Werror=array-bounds,
192              -Werror=clobbered,   -Werror=implicit-function-declaration   and
193              -Werror=volatile-register-var.
194
195       canary This  setting (disabled by default) adds dummy canary options to
196              the build flags, so that the build logs can be checked  for  how
197              the  build  flags propagate and to allow finding any omission of
198              normal build flag settings.  The only currently supported  flags
199              are  CPPFLAGS,  CFLAGS, OBJCFLAGS, CXXFLAGS and OBJCXXFLAGS with
200              flags set to -D__DEB_CANARY_flag_random-id__, and LDFLAGS set to
201              -Wl,-z,deb-canary-random-id.
202
203   sanitize
204       Several  compile-time  options  (detailed  below)  can  be used to help
205       sanitize a resulting binary against memory corruptions,  memory  leaks,
206       use after free, threading data races and undefined behavior bugs.
207
208       address
209              This  setting  (disabled  by default) adds -fsanitize=address to
210              LDFLAGS and -fsanitize=address -fno-omit-frame-pointer to CFLAGS
211              and CXXFLAGS.
212
213       thread This  setting  (disabled  by  default) adds -fsanitize=thread to
214              CFLAGS, CXXFLAGS and LDFLAGS.
215
216       leak   This setting  (disabled  by  default)  adds  -fsanitize=leak  to
217              LDFLAGS. It gets automatically disabled if either the address or
218              the thread features are enabled, as they imply it.
219
220       undefined
221              This setting (disabled by default) adds -fsanitize=undefined  to
222              CFLAGS, CXXFLAGS and LDFLAGS.
223
224   hardening
225       Several  compile-time  options  (detailed  below)  can  be used to help
226       harden a resulting binary against memory corruption attacks, or provide
227       additional warning messages during compilation.  Except as noted below,
228       these are enabled by default for architectures that support them.
229
230       format This   setting    (enabled    by    default)    adds    -Wformat
231              -Werror=format-security   to  CFLAGS,  CXXFLAGS,  OBJCFLAGS  and
232              OBJCXXFLAGS.  This will warn about improper format string  uses,
233              and  will  fail  when  format  functions  are used in a way that
234              represent possible security problems.  At  present,  this  warns
235              about  calls  to  printf  and  scanf  functions where the format
236              string  is  not  a  string  literal  and  there  are  no  format
237              arguments, as in printf(foo); instead of printf("%s", foo); This
238              may be a security hole if the format string came from  untrusted
239              input and contains ‘%n’.
240
241       fortify
242              This  setting  (enabled  by default) adds -D_FORTIFY_SOURCE=2 to
243              CPPFLAGS. During code generation the compiler knows a great deal
244              of information about buffer sizes (where possible), and attempts
245              to replace insecure unlimited length buffer function calls  with
246              length-limited  ones.  This is especially useful for old, crufty
247              code.  Additionally, format  strings  in  writable  memory  that
248              contain  ‘%n’  are  blocked. If an application depends on such a
249              format string, it will need to be worked around.
250
251              Note that for this option to have any effect,  the  source  must
252              also be compiled with -O1 or higher. If the environment variable
253              DEB_BUILD_OPTIONS contains noopt, then fortify support  will  be
254              disabled,  due  to  new  warnings being issued by glibc 2.16 and
255              later.
256
257       stackprotector
258              This setting (enabled by default if stackprotectorstrong is  not
259              in  use)  adds  -fstack-protector  --param=ssp-buffer-size=4  to
260              CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS,  FFLAGS  and
261              FCFLAGS.  This adds safety checks against stack overwrites. This
262              renders many potential  code  injection  attacks  into  aborting
263              situations.   In   the  best  case  this  turns  code  injection
264              vulnerabilities  into  denial  of  service  or  into  non-issues
265              (depending on the application).
266
267              This feature requires linking against glibc (or another provider
268              of __stack_chk_fail), so needs to be disabled when building with
269              -nostdlib or -ffreestanding or similar.
270
271       stackprotectorstrong
272              This  setting (enabled by default) adds -fstack-protector-strong
273              to CFLAGS, CXXFLAGS, OBJCFLAGS,  OBJCXXFLAGS,  GCJFLAGS,  FFLAGS
274              and  FCFLAGS.  This is a stronger variant of stackprotector, but
275              without significant performance penalties.
276
277              Disabling stackprotector will also disable this setting.
278
279              This feature has the same requirements as stackprotector, and in
280              addition also requires gcc 4.9 and later.
281
282       relro  This  setting (enabled by default) adds -Wl,-z,relro to LDFLAGS.
283              During program load, several ELF  memory  sections  need  to  be
284              written  to  by  the linker. This flags the loader to turn these
285              sections read-only before turning over control to  the  program.
286              Most notably this prevents GOT overwrite attacks. If this option
287              is disabled, bindnow will become disabled as well.
288
289       bindnow
290              This setting (disabled by default) adds -Wl,-z,now  to  LDFLAGS.
291              During  program load, all dynamic symbols are resolved, allowing
292              for the entire PLT to be marked read-only (due to relro  above).
293              The option cannot become enabled if relro is not enabled.
294
295       pie    This  setting  (with no default since dpkg 1.18.23, and injected
296              by default by gcc on  the  amd64,  arm64,  armel,  armhf,  i386,
297              kfreebsd-amd64,  kfreebsd-i386, mips, mipsel, mips64el, ppc64el,
298              s390x, sparc and sparc64 Debian architectures) adds the required
299              options  via gcc specs files if needed to enable or disable PIE.
300              When enabled and injected by gcc, adds nothing. When enabled and
301              not  injected by gcc, adds -fPIE to CFLAGS, CXXFLAGS, OBJCFLAGS,
302              OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS,  and  -fPIE  -pie  to
303              LDFLAGS.  When  disabled  and  injected by gcc, adds -fno-PIE to
304              CFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS,  FFLAGS  and
305              FCFLAGS, and -fno-PIE -no-pie to LDFLAGS.
306
307              Position  Independent Executable are needed to take advantage of
308              Address Space Layout Randomization,  supported  by  some  kernel
309              versions.  While  ASLR can already be enforced for data areas in
310              the stack and heap (brk  and  mmap),  the  code  areas  must  be
311              compiled  as  position-independent.  Shared libraries already do
312              this (-fPIC), so they gain ASLR automatically, but binary  .text
313              regions  need  to  be build PIE to gain ASLR. When this happens,
314              ROP (Return Oriented Programming) attacks are much harder  since
315              there  are  no static locations to bounce off of during a memory
316              corruption attack.
317
318              PIE is not compatible with -fPIC, so in  general  care  must  be
319              taken  when  building  shared objects. But because the PIE flags
320              emitted get injected via gcc specs files, it  should  always  be
321              safe  to  unconditionally set them regardless of the object type
322              being compiled or linked.
323
324              Static libraries  can  be  used  by  programs  or  other  shared
325              libraries.   Depending  on  the  flags  used  to compile all the
326              objects within a static library, these libraries will be  usable
327              by different sets of objects:
328
329
330              none   Cannot  be  linked  into  a  PIE  program,  nor  a shared
331                     library.
332
333              -fPIE  Can be linked into any program, but not a shared  library
334                     (recommended).
335
336              -fPIC  Can be linked into any program and shared library.
337
338
339              If  there  is  a need to set these flags manually, bypassing the
340              gcc specs injection, there  are  several  things  to  take  into
341              account.  Unconditionally and explicitly passing -fPIE, -fpie or
342              -pie to a build-system using libtool is safe as these flags will
343              get  stripped  when  building  shared  libraries.   Otherwise on
344              projects that build both programs and shared libraries you might
345              need  to make sure that when building the shared libraries -fPIC
346              is always passed last (so that it overrides any  previous  -PIE)
347              to  compilation flags such as CFLAGS, and -shared is passed last
348              (so that it overrides any previous -pie) to linking  flags  such
349              as LDFLAGS. Note: This should not be needed with the default gcc
350              specs machinery.
351
352
353              Additionally, since PIE is implemented via a  general  register,
354              some  register  starved  architectures  (but  not including i386
355              anymore since optimizations implemented in gcc  >=  5)  can  see
356              performance  losses  of  up  to  15%  in very text-segment-heavy
357              application  workloads;  most  workloads  see  less   than   1%.
358              Architectures  with  more  general registers (e.g. amd64) do not
359              see as high a worst-case penalty.
360
361   reproducible
362       The compile-time options detailed below can be  used  to  help  improve
363       build  reproducibility  or  provide  additional warning messages during
364       compilation. Except as noted below, these are enabled  by  default  for
365       architectures that support them.
366
367       timeless
368              This  setting (enabled by default) adds -Wdate-time to CPPFLAGS.
369              This  will  cause  warnings  when  the  __TIME__,  __DATE__  and
370              __TIMESTAMP__ macros are used.
371
372       fixdebugpath
373              This       setting      (enabled      by      default)      adds
374              -fdebug-prefix-map=BUILDPATH=.  to CFLAGS, CXXFLAGS,  OBJCFLAGS,
375              OBJCXXFLAGS, GCJFLAGS, FFLAGS and FCFLAGS where BUILDPATH is set
376              to the top-level directory of the package being built.  This has
377              the  effect  of removing the build path from any generated debug
378              symbols.
379

ENVIRONMENT

381       There are 2 sets of environment variables doing  the  same  operations,
382       the  first  one (DEB_flag_op) should never be used within debian/rules.
383       It's meant for any user that wants to rebuild the source  package  with
384       different  build  flags. The second set (DEB_flag_MAINT_op) should only
385       be used in debian/rules by package maintainers to change the  resulting
386       build flags.
387
388       DEB_flag_SET
389       DEB_flag_MAINT_SET
390              This  variable  can  be used to force the value returned for the
391              given flag.
392
393       DEB_flag_STRIP
394       DEB_flag_MAINT_STRIP
395              This variable can be used to provide a space separated  list  of
396              options that will be stripped from the set of flags returned for
397              the given flag.
398
399       DEB_flag_APPEND
400       DEB_flag_MAINT_APPEND
401              This variable can be used to append supplementary options to the
402              value returned for the given flag.
403
404       DEB_flag_PREPEND
405       DEB_flag_MAINT_PREPEND
406              This  variable  can  be used to prepend supplementary options to
407              the value returned for the given flag.
408
409       DEB_BUILD_OPTIONS
410       DEB_BUILD_MAINT_OPTIONS
411              These  variables  can  be  used  by  a  user  or  maintainer  to
412              disable/enable  various  area  features that affect build flags.
413              The DEB_BUILD_MAINT_OPTIONS variable overrides  any  setting  in
414              the  DEB_BUILD_OPTIONS  feature  areas.   See  the FEATURE AREAS
415              section for details.
416
417       DEB_VENDOR
418              This setting defines the current vendor.  If not  set,  it  will
419              discover       the      current      vendor      by      reading
420              /etc/dpkg/origins/default.
421
422       DEB_BUILD_PATH
423              This variable sets the build path (since dpkg 1.18.8) to use  in
424              features  such as fixdebugpath so that they can be controlled by
425              the caller.  This variable is currently Debian and  derivatives-
426              specific.
427

FILES

429   Configuration files
430       /etc/dpkg/buildflags.conf
431              System wide configuration file.
432
433       $XDG_CONFIG_HOME/dpkg/buildflags.conf or
434       $HOME/.config/dpkg/buildflags.conf
435              User configuration file.
436
437   Packaging support
438       /usr/share/dpkg/buildflags.mk
439              Makefile  snippet  that  will  load  (and optionally export) all
440              flags supported by dpkg-buildflags into  variables  (since  dpkg
441              1.16.1).
442

EXAMPLES

444       To pass build flags to a build command in a makefile:
445
446           $(MAKE) $(shell dpkg-buildflags --export=cmdline)
447
448           ./configure $(shell dpkg-buildflags --export=cmdline)
449
450       To  set  build  flags  in a shell script or shell fragment, eval can be
451       used  to  interpret  the  output  and  to  export  the  flags  in   the
452       environment:
453
454           eval "$(dpkg-buildflags --export=sh)" && make
455
456       or to set the positional parameters to pass to a command:
457
458           eval "set -- $(dpkg-buildflags --export=cmdline)"
459           for dir in a b c; do (cd $dir && ./configure "$@" && make); done
460
461   Usage in debian/rules
462       You  should  call  dpkg-buildflags  or  include  buildflags.mk from the
463       debian/rules file to obtain the needed build flags to pass to the build
464       system.   Note  that  older  versions of dpkg-buildpackage (before dpkg
465       1.16.1) exported these flags automatically.  However,  you  should  not
466       rely on this, since this breaks manual invocation of debian/rules.
467
468       For  packages  with  autoconf-like  build  systems,  you  can  pass the
469       relevant options to configure or make(1) directly, as shown above.
470
471       For other build systems, or when you  need  more  fine-grained  control
472       about  which  flags  are  passed  where,  you can use --get. Or you can
473       include  buildflags.mk   instead,   which   takes   care   of   calling
474       dpkg-buildflags and storing the build flags in make variables.
475
476       If  you  want to export all buildflags into the environment (where they
477       can be picked up by your build system):
478
479           DPKG_EXPORT_BUILDFLAGS = 1
480           include /usr/share/dpkg/buildflags.mk
481
482       For some extra control over what is exported, you can  manually  export
483       the variables (as none are exported by default):
484
485           include /usr/share/dpkg/buildflags.mk
486           export CPPFLAGS CFLAGS LDFLAGS
487
488       And you can of course pass the flags to commands manually:
489
490           include /usr/share/dpkg/buildflags.mk
491           build-arch:
492                $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
493
494
495
4961.18.25                           2018-06-26                dpkg-buildflags(1)
Impressum