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
114              Print  any  information  that  can  be  useful  to  explain  the
115              behaviour of the program: current vendor,  relevant  environment
116              variables,  feature  areas,  state of all feature flags, and the
117              compiler flags with their origin (since dpkg 1.19.0).
118
119              For example:
120                Vendor: Debian
121                Environment:
122                 DEB_CFLAGS_SET=-O0 -Wall
123
124                Area: qa
125                Features:
126                 bug=no
127                 canary=no
128
129                Area: reproducible
130                Features:
131                 timeless=no
132
133                Flag: CFLAGS
134                Value: -O0 -Wall
135                Origin: env
136
137                Flag: CPPFLAGS
138                Value: -D_FORTIFY_SOURCE=2
139                Origin: vendor
140
141       --query-features area
142              Print the features enabled for a given area (since dpkg 1.16.2).
143              The  only  currently  recognized areas on Debian and derivatives
144              are future, qa, reproducible, sanitize and  hardening,  see  the
145              FEATURE  AREAS  section  for  more details.  Exits with 0 if the
146              area is known otherwise exits with 1.
147
148              The output is in RFC822 format, with one  section  per  feature.
149              For example:
150
151                Feature: pie
152                Enabled: yes
153
154                Feature: stackprotector
155                Enabled: yes
156
157       --help Show the usage message and exit.
158
159       --version
160              Show the version and exit.
161

SUPPORTED FLAGS

163       CFLAGS Options  for the C compiler. The default value set by the vendor
164              includes -g and the default optimization level (-O2 usually,  or
165              -O0   if  the  DEB_BUILD_OPTIONS  environment  variable  defines
166              noopt).
167
168       CPPFLAGS
169              Options for the C preprocessor. Default value: empty.
170
171       CXXFLAGS
172              Options for the C++ compiler. Same as CFLAGS.
173
174       OBJCFLAGS
175              Options for the Objective C compiler. Same as CFLAGS.
176
177       OBJCXXFLAGS
178              Options for the Objective C++ compiler. Same as CXXFLAGS.
179
180       GCJFLAGS
181              Options for the GNU Java compiler (gcj). A subset of CFLAGS.
182
183       FFLAGS Options for the Fortran 77 compiler. A subset of CFLAGS.
184
185       FCFLAGS
186              Options for the Fortran 9x compiler. Same as FFLAGS.
187
188       LDFLAGS
189              Options passed to  the  compiler  when  linking  executables  or
190              shared objects (if the linker is called directly, then -Wl and ,
191              have to be stripped from these options). Default value: empty.
192
193       New flags might be added in the future if the need arises (for  example
194       to support other languages).
195

FEATURE AREAS

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

ENVIRONMENT

439       There  are  2  sets of environment variables doing the same operations,
440       the first one (DEB_flag_op) should never be used  within  debian/rules.
441       It's  meant  for any user that wants to rebuild the source package with
442       different build flags. The second set (DEB_flag_MAINT_op)  should  only
443       be  used in debian/rules by package maintainers to change the resulting
444       build flags.
445
446       DEB_flag_SET
447       DEB_flag_MAINT_SET
448              This variable can be used to force the value  returned  for  the
449              given flag.
450
451       DEB_flag_STRIP
452       DEB_flag_MAINT_STRIP
453              This  variable  can be used to provide a space separated list of
454              options that will be stripped from the set of flags returned for
455              the given flag.
456
457       DEB_flag_APPEND
458       DEB_flag_MAINT_APPEND
459              This variable can be used to append supplementary options to the
460              value returned for the given flag.
461
462       DEB_flag_PREPEND
463       DEB_flag_MAINT_PREPEND
464              This variable can be used to prepend  supplementary  options  to
465              the value returned for the given flag.
466
467       DEB_BUILD_OPTIONS
468       DEB_BUILD_MAINT_OPTIONS
469              These  variables  can  be  used  by  a  user  or  maintainer  to
470              disable/enable various area features that  affect  build  flags.
471              The  DEB_BUILD_MAINT_OPTIONS  variable  overrides any setting in
472              the DEB_BUILD_OPTIONS feature  areas.   See  the  FEATURE  AREAS
473              section for details.
474
475       DEB_VENDOR
476              This  setting  defines  the current vendor.  If not set, it will
477              discover      the      current      vendor      by       reading
478              /etc/dpkg/origins/default.
479
480       DEB_BUILD_PATH
481              This  variable sets the build path (since dpkg 1.18.8) to use in
482              features such as fixdebugpath so that they can be controlled  by
483              the  caller.  This variable is currently Debian and derivatives-
484              specific.
485
486       DPKG_COLORS
487              Sets the color mode (since dpkg 1.18.5).  The currently accepted
488              values are: auto (default), always and never.
489
490       DPKG_NLS
491              If  set,  it  will  be used to decide whether to activate Native
492              Language Support, also known as internationalization  (or  i18n)
493              support  (since  dpkg 1.19.0).  The accepted values are: 0 and 1
494              (default).
495

FILES

497   Configuration files
498       /etc/dpkg/buildflags.conf
499              System wide configuration file.
500
501       $XDG_CONFIG_HOME/dpkg/buildflags.conf or
502       $HOME/.config/dpkg/buildflags.conf
503              User configuration file.
504
505   Packaging support
506       /usr/share/dpkg/buildflags.mk
507              Makefile snippet that will  load  (and  optionally  export)  all
508              flags  supported  by  dpkg-buildflags into variables (since dpkg
509              1.16.1).
510

EXAMPLES

512       To pass build flags to a build command in a Makefile:
513
514           $(MAKE) $(shell dpkg-buildflags --export=cmdline)
515
516           ./configure $(shell dpkg-buildflags --export=cmdline)
517
518       To set build flags in a shell script or shell  fragment,  eval  can  be
519       used   to  interpret  the  output  and  to  export  the  flags  in  the
520       environment:
521
522           eval "$(dpkg-buildflags --export=sh)" && make
523
524       or to set the positional parameters to pass to a command:
525
526           eval "set -- $(dpkg-buildflags --export=cmdline)"
527           for dir in a b c; do (cd $dir && ./configure "$@" && make); done
528
529   Usage in debian/rules
530       You should call  dpkg-buildflags  or  include  buildflags.mk  from  the
531       debian/rules file to obtain the needed build flags to pass to the build
532       system.  Note that older versions  of  dpkg-buildpackage  (before  dpkg
533       1.16.1)  exported  these  flags  automatically. However, you should not
534       rely on this, since this breaks manual invocation of debian/rules.
535
536       For packages  with  autoconf-like  build  systems,  you  can  pass  the
537       relevant options to configure or make(1) directly, as shown above.
538
539       For  other  build  systems,  or when you need more fine-grained control
540       about which flags are passed where, you  can  use  --get.  Or  you  can
541       include   buildflags.mk   instead,   which   takes   care   of  calling
542       dpkg-buildflags and storing the build flags in make variables.
543
544       If you want to export all buildflags into the environment  (where  they
545       can be picked up by your build system):
546
547           DPKG_EXPORT_BUILDFLAGS = 1
548           include /usr/share/dpkg/buildflags.mk
549
550       For  some  extra control over what is exported, you can manually export
551       the variables (as none are exported by default):
552
553           include /usr/share/dpkg/buildflags.mk
554           export CPPFLAGS CFLAGS LDFLAGS
555
556       And you can of course pass the flags to commands manually:
557
558           include /usr/share/dpkg/buildflags.mk
559           build-arch:
560                $(CC) -o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS)
561
562
563
5641.19.7                            2019-06-03                dpkg-buildflags(1)
Impressum