Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | .\" dpkg manual page - dpkg-buildflags(1) |
2 | .\" | |
3 | .\" Copyright © 2010-2011 Raphaël Hertzog <hertzog@debian.org> | |
4 | .\" Copyright © 2011 Kees Cook <kees@debian.org> | |
5 | .\" Copyright © 2011-2015 Guillem Jover <guillem@debian.org> | |
6 | .\" | |
7 | .\" This is free software; you can redistribute it and/or modify | |
8 | .\" it under the terms of the GNU General Public License as published by | |
9 | .\" the Free Software Foundation; either version 2 of the License, or | |
10 | .\" (at your option) any later version. | |
11 | .\" | |
12 | .\" This is distributed in the hope that it will be useful, | |
13 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | .\" GNU General Public License for more details. | |
16 | .\" | |
17 | .\" You should have received a copy of the GNU General Public License | |
18 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
19 | . | |
20 | .TH dpkg\-buildflags 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite" | |
21 | .nh | |
22 | .SH NAME | |
23 | dpkg\-buildflags \- returns build flags to use during package build | |
24 | . | |
25 | .SH SYNOPSIS | |
26 | .B dpkg\-buildflags | |
27 | .RI [ option "...] [" command ] | |
28 | . | |
29 | .SH DESCRIPTION | |
30 | \fBdpkg\-buildflags\fP is a tool to retrieve compilation flags to use during | |
31 | build of Debian packages. | |
32 | . | |
33 | The default flags are defined by the vendor but they can be | |
34 | extended/overridden in several ways: | |
35 | .IP 1. | |
36 | system-wide with \fB%PKGCONFDIR%/buildflags.conf\fP; | |
37 | .IP 2. | |
38 | for the current user with \fB$XDG_CONFIG_HOME/dpkg/buildflags.conf\fP | |
39 | where \fB$XDG_CONFIG_HOME\fP defaults to \fB$HOME/.config\fP; | |
40 | .IP 3. | |
41 | temporarily by the user with environment variables (see section | |
42 | \fBENVIRONMENT\fP); | |
43 | .IP 4. | |
44 | dynamically by the package maintainer with environment variables set via | |
45 | \fBdebian/rules\fP (see section \fBENVIRONMENT\fP). | |
46 | .P | |
47 | The configuration files can contain four types of directives: | |
48 | .TP | |
49 | .BI SET " flag value" | |
50 | Override the flag named \fIflag\fP to have the value \fIvalue\fP. | |
51 | .TP | |
52 | .BI STRIP " flag value" | |
53 | Strip from the flag named \fIflag\fP all the build flags listed in \fIvalue\fP. | |
54 | .TP | |
55 | .BI APPEND " flag value" | |
56 | Extend the flag named \fIflag\fP by appending the options given in \fIvalue\fP. | |
57 | A space is prepended to the appended value if the flag's current value is non-empty. | |
58 | .TP | |
59 | .BI PREPEND " flag value" | |
60 | Extend the flag named \fIflag\fP by prepending the options given in \fIvalue\fP. | |
61 | A space is appended to the prepended value if the flag's current value is non-empty. | |
62 | .P | |
63 | The configuration files can contain comments on lines starting with a hash | |
64 | (#). Empty lines are also ignored. | |
65 | .SH COMMANDS | |
66 | .TP | |
67 | .BI \-\-dump | |
68 | Print to standard output all compilation flags and their values. It prints | |
69 | one flag per line separated from its value by an equal sign | |
70 | (“\fIflag\fP=\fIvalue\fP”). This is the default action. | |
71 | .TP | |
72 | .BI \-\-list | |
73 | Print the list of flags supported by the current vendor | |
74 | (one per line). See the \fBSUPPORTED FLAGS\fP section for more | |
75 | information about them. | |
76 | .TP | |
77 | .BI \-\-status | |
78 | Display any information that can be useful to explain the behaviour of | |
79 | \fBdpkg\-buildflags\fP (since dpkg 1.16.5): relevant environment variables, | |
80 | current vendor, state of all feature flags. | |
81 | Also print the resulting compiler flags with their origin. | |
82 | ||
83 | This is intended to be run from \fBdebian/rules\fP, so that the build log | |
84 | keeps a clear trace of the build flags used. This can be useful to diagnose | |
85 | problems related to them. | |
86 | .TP | |
87 | .BI \-\-export= format | |
88 | Print to standard output commands that can be used to export all the | |
89 | compilation flags for some particular tool. If the \fIformat\fP value is not | |
90 | given, \fBsh\fP is assumed. Only compilation flags starting with an | |
91 | upper case character are included, others are assumed to not be suitable | |
92 | for the environment. Supported formats: | |
93 | .RS | |
94 | .TP | |
95 | .B sh | |
96 | Shell commands to set and export all the compilation flags in the | |
97 | environment. The flag values are quoted so the output is ready for | |
98 | evaluation by a shell. | |
99 | .TP | |
100 | .B cmdline | |
101 | Arguments to pass to a build program's command line to use all the | |
102 | compilation flags (since dpkg 1.17.0). The flag values are quoted in | |
103 | shell syntax. | |
104 | .TP | |
105 | .B configure | |
106 | This is a legacy alias for \fBcmdline\fP. | |
107 | .TP | |
108 | .B make | |
109 | Make directives to set and export all the compilation flags in the | |
110 | environment. Output can be written to a makefile fragment and | |
111 | evaluated using an \fBinclude\fP directive. | |
112 | .RE | |
113 | .TP | |
114 | .BI \-\-get " flag" | |
115 | Print the value of the flag on standard output. Exits with 0 | |
116 | if the flag is known otherwise exits with 1. | |
117 | .TP | |
118 | .BI \-\-origin " flag" | |
119 | Print the origin of the value that is returned by \fB\-\-get\fP. Exits | |
120 | with 0 if the flag is known otherwise exits with 1. The origin can be one | |
121 | of the following values: | |
122 | .RS | |
123 | .TP | |
124 | .B vendor | |
125 | the original flag set by the vendor is returned; | |
126 | .TP | |
127 | .B system | |
128 | the flag is set/modified by a system-wide configuration; | |
129 | .TP | |
130 | .B user | |
131 | the flag is set/modified by a user-specific configuration; | |
132 | .TP | |
133 | .B env | |
134 | the flag is set/modified by an environment-specific configuration. | |
135 | .RE | |
136 | .TP | |
137 | .BI \-\-query\-features " area" | |
138 | Print the features enabled for a given area (since dpkg 1.16.2). | |
139 | The only currently recognized | |
140 | areas on Debian and derivatives are \fBqa\fP, \fBreproducible\fP, | |
141 | \fBsanitize\fP and \fBhardening\fP, see the \fBFEATURE AREAS\fP | |
142 | section for more details. | |
143 | Exits with 0 if the area is known otherwise exits with 1. | |
144 | .IP | |
145 | The output is in RFC822 format, with one section per feature. | |
146 | For example: | |
147 | .IP | |
148 | .nf | |
149 | Feature: pie | |
150 | Enabled: yes | |
151 | ||
152 | Feature: stackprotector | |
153 | Enabled: yes | |
154 | .fi | |
155 | .TP | |
156 | .B \-\-help | |
157 | Show the usage message and exit. | |
158 | .TP | |
159 | .B \-\-version | |
160 | Show the version and exit. | |
161 | . | |
162 | .SH SUPPORTED FLAGS | |
163 | .TP | |
164 | .B CFLAGS | |
165 | Options for the C compiler. The default value set by the vendor | |
166 | includes \fB\-g\fP and the default optimization level (\fB\-O2\fP usually, | |
167 | or \fB\-O0\fP if the \fBDEB_BUILD_OPTIONS\fP environment variable defines | |
168 | \fInoopt\fP). | |
169 | .TP | |
170 | .B CPPFLAGS | |
171 | Options for the C preprocessor. Default value: empty. | |
172 | .TP | |
173 | .B CXXFLAGS | |
174 | Options for the C++ compiler. Same as \fBCFLAGS\fP. | |
175 | .TP | |
176 | .B OBJCFLAGS | |
177 | Options for the Objective C compiler. Same as \fBCFLAGS\fP. | |
178 | .TP | |
179 | .B OBJCXXFLAGS | |
180 | Options for the Objective C++ compiler. Same as \fBCXXFLAGS\fP. | |
181 | .TP | |
182 | .B GCJFLAGS | |
183 | Options for the GNU Java compiler (gcj). A subset of \fBCFLAGS\fP. | |
184 | .TP | |
185 | .B FFLAGS | |
186 | Options for the Fortran 77 compiler. A subset of \fBCFLAGS\fP. | |
187 | .TP | |
188 | .B FCFLAGS | |
189 | Options for the Fortran 9x compiler. Same as \fBFFLAGS\fP. | |
190 | .TP | |
191 | .B LDFLAGS | |
192 | Options passed to the compiler when linking executables or shared | |
193 | objects (if the linker is called directly, then | |
194 | .B \-Wl | |
195 | and | |
196 | .B , | |
197 | have to be stripped from these options). Default value: empty. | |
198 | .PP | |
199 | New flags might be added in the future if the need arises (for example | |
200 | to support other languages). | |
201 | . | |
202 | .SH FEATURE AREAS | |
203 | .P | |
204 | Each area feature can be enabled and disabled in the \fBDEB_BUILD_OPTIONS\fP | |
205 | and \fBDEB_BUILD_MAINT_OPTIONS\fP environment variable's area value with the | |
206 | ‘\fB+\fP’ and ‘\fB\-\fP’ modifier. | |
207 | For example, to enable the \fBhardening\fP “pie” feature and disable the | |
208 | “fortify” feature you can do this in \fBdebian/rules\fP: | |
209 | .P | |
210 | export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,\-fortify | |
211 | .P | |
212 | The special feature \fBall\fP (valid in any area) can be used to enable or | |
213 | disable all area features at the same time. | |
214 | Thus disabling everything in the \fBhardening\fP area and enabling only | |
215 | “format” and “fortify” can be achieved with: | |
216 | .P | |
217 | export DEB_BUILD_MAINT_OPTIONS=hardening=\-all,+format,+fortify | |
218 | . | |
219 | .SS qa | |
220 | Several compile-time options (detailed below) can be used to help detect | |
221 | problems in the source code or build system. | |
222 | .TP | |
223 | .B bug | |
224 | This setting (disabled by default) adds any warning option that reliably | |
225 | detects problematic source code. The warnings are fatal. | |
226 | The only currently supported flags are \fBCFLAGS\fP and \fBCXXFLAGS\fP | |
227 | with flags set to \fB\-Werror=array\-bounds\fP, \fB\-Werror=clobbered\fP, | |
228 | \fB\-Werror=implicit\-function\-declaration\fP and | |
229 | \fB\-Werror=volatile\-register\-var\fP. | |
230 | . | |
231 | .TP | |
232 | .B canary | |
233 | This setting (disabled by default) adds dummy canary options to the build | |
234 | flags, so that the build logs can be checked for how the build flags | |
235 | propagate and to allow finding any omission of normal build flag settings. | |
236 | The only currently supported flags are \fBCPPFLAGS\fP, \fBCFLAGS\fP, | |
237 | \fBOBJCFLAGS\fP, \fBCXXFLAGS\fP and \fBOBJCXXFLAGS\fP with flags set | |
238 | to \fB\-D__DEB_CANARY_\fP\fIflag\fP_\fIrandom-id\fP\fB__\fP, and | |
239 | \fBLDFLAGS\fP set to \fB\-Wl,\-z,deb-canary\-\fP\fIrandom-id\fP. | |
240 | . | |
241 | .SS sanitize | |
242 | Several compile-time options (detailed below) can be used to help sanitize | |
243 | a resulting binary against memory corruptions, memory leaks, use after free, | |
244 | threading data races and undefined behavior bugs. | |
245 | .TP | |
246 | .B address | |
247 | This setting (disabled by default) adds \fB\-fsanitize=address\fP to | |
248 | \fBLDFLAGS\fP and \fB\-fsanitize=address \-fno\-omit\-frame\-pointer\fP to | |
249 | \fBCFLAGS\fP and \fBCXXFLAGS\fP. | |
250 | .TP | |
251 | .B thread | |
252 | This setting (disabled by default) adds \fB\-fsanitize=thread\fP to | |
253 | \fBCFLAGS\fP, \fBCXXFLAGS\fP and \fBLDFLAGS\fP. | |
254 | .TP | |
255 | .B leak | |
256 | This setting (disabled by default) adds \fB\-fsanitize=leak\fP to | |
257 | \fBLDFLAGS\fP. It gets automatically disabled if either the \fBaddress\fP | |
258 | or the \fBthread\fP features are enabled, as they imply it. | |
259 | .TP | |
260 | .B undefined | |
261 | This setting (disabled by default) adds \fB\-fsanitize=undefined\fP to | |
262 | \fBCFLAGS\fP, \fBCXXFLAGS\fP and \fBLDFLAGS\fP. | |
263 | .SS hardening | |
264 | Several compile-time options (detailed below) can be used to help harden | |
265 | a resulting binary against memory corruption attacks, or provide | |
266 | additional warning messages during compilation. | |
267 | Except as noted below, these are enabled by default for architectures | |
268 | that support them. | |
269 | .TP | |
270 | .B format | |
271 | This setting (enabled by default) adds | |
272 | .B \-Wformat \-Werror=format\-security | |
273 | to \fBCFLAGS\fP, \fBCXXFLAGS\fP, \fBOBJCFLAGS\fP and \fBOBJCXXFLAGS\fP. | |
274 | This will warn about improper format | |
275 | string uses, and will fail when format functions are used in a way | |
276 | that represent possible security problems. At present, this warns about | |
277 | calls to \fBprintf\fP and \fBscanf\fP functions where the format string is | |
278 | not a string literal and there are no format arguments, as in | |
279 | \fBprintf(foo);\fP instead of \fPprintf("%s", foo);\fP | |
280 | This may be a security hole if the format string came from untrusted | |
281 | input and contains ‘%n’. | |
282 | . | |
283 | .TP | |
284 | .B fortify | |
285 | This setting (enabled by default) adds | |
286 | .B \-D_FORTIFY_SOURCE=2 | |
287 | to \fBCPPFLAGS\fP. During code generation the compiler | |
288 | knows a great deal of information about buffer sizes (where possible), and | |
289 | attempts to replace insecure unlimited length buffer function calls with | |
290 | length-limited ones. This is especially useful for old, crufty code. | |
291 | Additionally, format strings in writable memory that contain ‘%n’ are | |
292 | blocked. If an application depends on such a format string, it will need | |
293 | to be worked around. | |
294 | ||
295 | Note that for this option to have any effect, the source must also | |
296 | be compiled with \fB\-O1\fP or higher. If the environment variable | |
297 | \fBDEB_BUILD_OPTIONS\fP contains \fInoopt\fP, then \fBfortify\fP | |
298 | support will be disabled, due to new warnings being issued by | |
299 | glibc 2.16 and later. | |
300 | .TP | |
301 | .B stackprotector | |
302 | This setting (enabled by default if stackprotectorstrong is not in use) adds | |
303 | .B \-fstack\-protector \-\-param=ssp\-buffer\-size=4 | |
304 | to \fBCFLAGS\fP, \fBCXXFLAGS\fP, \fBOBJCFLAGS\fP, \fBOBJCXXFLAGS\fP, | |
305 | \fBGCJFLAGS\fP, \fBFFLAGS\fP and \fBFCFLAGS\fP. | |
306 | This adds safety checks against stack | |
307 | overwrites. This renders many potential code injection attacks into | |
308 | aborting situations. In the best case this turns code injection | |
309 | vulnerabilities into denial of service or into non-issues (depending on | |
310 | the application). | |
311 | ||
312 | This feature requires linking against glibc (or another provider of | |
313 | \fB__stack_chk_fail\fP), so needs to be disabled when building with | |
314 | \fB\-nostdlib\fP or \fB\-ffreestanding\fP or similar. | |
315 | . | |
316 | .TP | |
317 | .B stackprotectorstrong | |
318 | This setting (enabled by default) adds | |
319 | .B \-fstack\-protector\-strong | |
320 | to \fBCFLAGS\fP, \fBCXXFLAGS\fP, \fBOBJCFLAGS\fP, \fBOBJCXXFLAGS\fP, | |
321 | \fBGCJFLAGS\fP, \fBFFLAGS\fP and \fBFCFLAGS\fP. | |
322 | This is a stronger variant of \fBstackprotector\fP, but without significant | |
323 | performance penalties. | |
324 | ||
325 | Disabling \fBstackprotector\fP will also disable this setting. | |
326 | ||
327 | This feature has the same requirements as \fBstackprotector\fP, and in | |
328 | addition also requires gcc 4.9 and later. | |
329 | . | |
330 | .TP | |
331 | .B relro | |
332 | This setting (enabled by default) adds | |
333 | .B \-Wl,\-z,relro | |
334 | to \fBLDFLAGS\fP. During program load, several ELF memory sections need | |
335 | to be written to by the linker. This flags the loader to turn these | |
336 | sections read-only before turning over control to the program. Most | |
337 | notably this prevents GOT overwrite attacks. If this option is disabled, | |
338 | \fBbindnow\fP will become disabled as well. | |
339 | . | |
340 | .TP | |
341 | .B bindnow | |
342 | This setting (disabled by default) adds | |
343 | .B \-Wl,\-z,now | |
344 | to \fBLDFLAGS\fP. During program load, all dynamic symbols are resolved, | |
345 | allowing for the entire PLT to be marked read-only (due to \fBrelro\fP | |
346 | above). The option cannot become enabled if \fBrelro\fP is not enabled. | |
347 | . | |
348 | .TP | |
349 | .B pie | |
350 | This setting (with no default since dpkg 1.18.23, and injected by default | |
351 | by gcc on the amd64, arm64, armel, armhf, i386, kfreebsd-amd64, kfreebsd-i386, | |
352 | mips, mipsel, mips64el, ppc64el, s390x, sparc and sparc64 Debian architectures) | |
353 | adds the required options via gcc specs files if | |
354 | needed to enable or disable PIE. When enabled and injected by gcc, | |
355 | adds nothing. When enabled and not injected by gcc, adds \fB\-fPIE\fP | |
356 | to \fBCFLAGS\fP, \fBCXXFLAGS\fP, \fBOBJCFLAGS\fP, \fBOBJCXXFLAGS\fP, | |
357 | \fBGCJFLAGS\fP, \fBFFLAGS\fP and \fBFCFLAGS\fP, and \fB\-fPIE \-pie\fP | |
358 | to \fBLDFLAGS\fP. When disabled and injected by gcc, adds \fB\-fno\-PIE\fP | |
359 | to \fBCFLAGS\fP, \fBCXXFLAGS\fP, \fBOBJCFLAGS\fP, \fBOBJCXXFLAGS\fP, | |
360 | \fBGCJFLAGS\fP, \fBFFLAGS\fP and \fBFCFLAGS\fP, and | |
361 | \fB\-fno\-PIE \-no\-pie\fP to \fBLDFLAGS\fP. | |
362 | ||
363 | Position Independent | |
364 | Executable are needed to take advantage of Address Space Layout | |
365 | Randomization, supported by some kernel versions. While ASLR can already | |
366 | be enforced for data areas in the stack and heap (brk and mmap), the code | |
367 | areas must be compiled as position-independent. Shared libraries already | |
368 | do this (\fB\-fPIC\fP), so they gain ASLR automatically, but binary .text | |
369 | regions need to be build PIE to gain ASLR. When this happens, ROP (Return | |
370 | Oriented Programming) attacks are much harder since there are no static | |
371 | locations to bounce off of during a memory corruption attack. | |
372 | ||
373 | PIE is not compatible with \fB\-fPIC\fP, so in general care must be taken | |
374 | when building shared objects. But because the PIE flags emitted get injected | |
375 | via gcc specs files, it should always be safe to unconditionally set them | |
376 | regardless of the object type being compiled or linked. | |
377 | ||
378 | Static libraries can be used by programs or other shared libraries. | |
379 | Depending on the flags used to compile all the objects within a static | |
380 | library, these libraries will be usable by different sets of objects: | |
381 | ||
382 | .RS | |
383 | .TP | |
384 | none | |
385 | Cannot be linked into a PIE program, nor a shared library. | |
386 | .TP | |
387 | .B \-fPIE | |
388 | Can be linked into any program, but not a shared library (recommended). | |
389 | .TP | |
390 | .B \-fPIC | |
391 | Can be linked into any program and shared library. | |
392 | .RE | |
393 | ||
394 | .IP | |
395 | If there is a need to set these flags manually, bypassing the gcc specs | |
396 | injection, there are several things to take into account. Unconditionally | |
397 | and explicitly passing \fB\-fPIE\fP, \fB\-fpie\fP or \fB\-pie\fP to a | |
398 | build-system using libtool is safe as these flags will get stripped | |
399 | when building shared libraries. | |
400 | Otherwise on projects that build both programs and shared libraries you | |
401 | might need to make sure that when building the shared libraries \fB\-fPIC\fP | |
402 | is always passed last (so that it overrides any previous \fB\-PIE\fP) to | |
403 | compilation flags such as \fBCFLAGS\fP, and \fB\-shared\fP is passed last | |
404 | (so that it overrides any previous \fB\-pie\fP) to linking flags such as | |
405 | \fBLDFLAGS\fP. \fBNote:\fP This should not be needed with the default | |
406 | gcc specs machinery. | |
407 | ||
408 | .IP | |
409 | Additionally, since PIE is implemented via a general register, some | |
410 | register starved architectures (but not including i386 anymore since | |
411 | optimizations implemented in gcc >= 5) can see performance losses of up to | |
412 | 15% in very text-segment-heavy application workloads; most workloads | |
413 | see less than 1%. Architectures with more general registers (e.g. amd64) | |
414 | do not see as high a worst-case penalty. | |
415 | .SS reproducible | |
416 | The compile-time options detailed below can be used to help improve | |
417 | build reproducibility or provide additional warning messages during | |
418 | compilation. Except as noted below, these are enabled by default for | |
419 | architectures that support them. | |
420 | .TP | |
421 | .B timeless | |
422 | This setting (enabled by default) adds | |
423 | .B \-Wdate\-time | |
424 | to \fBCPPFLAGS\fP. | |
425 | This will cause warnings when the \fB__TIME__\fP, \fB__DATE__\fP and | |
426 | \fB__TIMESTAMP__\fP macros are used. | |
427 | . | |
428 | .TP | |
429 | .B fixdebugpath | |
430 | This setting (enabled by default) adds | |
431 | .BI \-fdebug\-prefix\-map= BUILDPATH =. | |
432 | to \fBCFLAGS\fP, \fBCXXFLAGS\fP, \fBOBJCFLAGS\fP, \fBOBJCXXFLAGS\fP, | |
433 | \fBGCJFLAGS\fP, \fBFFLAGS\fP and \fBFCFLAGS\fP where \fBBUILDPATH\fP is | |
434 | set to the top-level directory of the package being built. | |
435 | This has the effect of removing the build path from any generated debug | |
436 | symbols. | |
437 | . | |
438 | .SH ENVIRONMENT | |
439 | There are 2 sets of environment variables doing the same operations, the | |
440 | first one (DEB_\fIflag\fP_\fIop\fP) should never be used within | |
441 | \fBdebian/rules\fP. It's meant for any user that wants to rebuild the | |
442 | source package with different build flags. The second set | |
443 | (DEB_\fIflag\fP_MAINT_\fIop\fP) should only be used in \fBdebian/rules\fP | |
444 | by package maintainers to change the resulting build flags. | |
445 | .TP | |
446 | .BI DEB_ flag _SET | |
447 | .TQ | |
448 | .BI DEB_ flag _MAINT_SET | |
449 | This variable can be used to force the value returned for the given | |
450 | \fIflag\fP. | |
451 | .TP | |
452 | .BI DEB_ flag _STRIP | |
453 | .TQ | |
454 | .BI DEB_ flag _MAINT_STRIP | |
455 | This variable can be used to provide a space separated list of options | |
456 | that will be stripped from the set of flags returned for the given | |
457 | \fIflag\fP. | |
458 | .TP | |
459 | .BI DEB_ flag _APPEND | |
460 | .TQ | |
461 | .BI DEB_ flag _MAINT_APPEND | |
462 | This variable can be used to append supplementary options to the value | |
463 | returned for the given \fIflag\fP. | |
464 | .TP | |
465 | .BI DEB_ flag _PREPEND | |
466 | .TQ | |
467 | .BI DEB_ flag _MAINT_PREPEND | |
468 | This variable can be used to prepend supplementary options to the value | |
469 | returned for the given \fIflag\fP. | |
470 | .TP | |
471 | .B DEB_BUILD_OPTIONS | |
472 | .TQ | |
473 | .B DEB_BUILD_MAINT_OPTIONS | |
474 | These variables can be used by a user or maintainer to disable/enable | |
475 | various area features that affect build flags. | |
476 | The \fBDEB_BUILD_MAINT_OPTIONS\fP variable overrides any setting in the | |
477 | \fBDEB_BUILD_OPTIONS\fP feature areas. | |
478 | See the \fBFEATURE AREAS\fP section for details. | |
479 | .TP | |
480 | .B DEB_VENDOR | |
481 | This setting defines the current vendor. | |
482 | If not set, it will discover the current vendor by reading | |
483 | \fB%PKGCONFDIR%/origins/default\fP. | |
484 | .TP | |
485 | .B DEB_BUILD_PATH | |
486 | This variable sets the build path (since dpkg 1.18.8) to use in features | |
487 | such as \fBfixdebugpath\fP so that they can be controlled by the caller. | |
488 | This variable is currently Debian and derivatives-specific. | |
489 | . | |
490 | .SH FILES | |
491 | .SS Configuration files | |
492 | .TP | |
493 | .B %PKGCONFDIR%/buildflags.conf | |
494 | System wide configuration file. | |
495 | .TP | |
496 | .BR $XDG_CONFIG_HOME/dpkg/buildflags.conf " or " | |
497 | .TQ | |
498 | .BR $HOME/.config/dpkg/buildflags.conf | |
499 | User configuration file. | |
500 | .SS Packaging support | |
501 | .TP | |
502 | .B %PKGDATADIR%/buildflags.mk | |
503 | Makefile snippet that will load (and optionally export) all flags | |
504 | supported by \fBdpkg-buildflags\fP into variables (since dpkg 1.16.1). | |
505 | . | |
506 | .SH EXAMPLES | |
507 | To pass build flags to a build command in a makefile: | |
508 | .PP | |
509 | .RS 4 | |
510 | .nf | |
511 | $(MAKE) $(shell dpkg\-buildflags \-\-export=cmdline) | |
512 | ||
513 | \&./configure $(shell dpkg\-buildflags \-\-export=cmdline) | |
514 | .fi | |
515 | .RE | |
516 | .PP | |
517 | To set build flags in a shell script or shell fragment, \fBeval\fP can be | |
518 | used to interpret the output and to export the flags in the environment: | |
519 | .PP | |
520 | .RS 4 | |
521 | .nf | |
522 | eval "$(dpkg\-buildflags \-\-export=sh)" && make | |
523 | .fi | |
524 | .RE | |
525 | .PP | |
526 | or to set the positional parameters to pass to a command: | |
527 | .PP | |
528 | .RS 4 | |
529 | .nf | |
530 | eval "set \-\- $(dpkg\-buildflags \-\-export=cmdline)" | |
531 | for dir in a b c; do (cd $dir && ./configure "$@" && make); done | |
532 | .fi | |
533 | .RE | |
534 | . | |
535 | .SS Usage in debian/rules | |
536 | You should call \fBdpkg\-buildflags\fP or include \fBbuildflags.mk\fP | |
537 | from the \fBdebian/rules\fP file to obtain the needed build flags to | |
538 | pass to the build system. | |
539 | Note that older versions of \fBdpkg\-buildpackage\fP (before dpkg 1.16.1) | |
540 | exported these flags automatically. However, you should not rely on this, | |
541 | since this breaks manual invocation of \fBdebian/rules\fP. | |
542 | .PP | |
543 | For packages with autoconf-like build systems, you can pass the relevant | |
544 | options to configure or \fBmake\fP(1) directly, as shown above. | |
545 | .PP | |
546 | For other build systems, or when you need more fine-grained control | |
547 | about which flags are passed where, you can use \fB\-\-get\fP. Or you | |
548 | can include \fBbuildflags.mk\fP instead, which takes care of calling | |
549 | \fBdpkg\-buildflags\fP and storing the build flags in make variables. | |
550 | .PP | |
551 | If you want to export all buildflags into the environment (where they | |
552 | can be picked up by your build system): | |
553 | .PP | |
554 | .RS 4 | |
555 | .nf | |
556 | DPKG_EXPORT_BUILDFLAGS = 1 | |
557 | include %PKGDATADIR%/buildflags.mk | |
558 | .fi | |
559 | .RE | |
560 | .PP | |
561 | For some extra control over what is exported, you can manually export | |
562 | the variables (as none are exported by default): | |
563 | .PP | |
564 | .RS 4 | |
565 | .nf | |
566 | include %PKGDATADIR%/buildflags.mk | |
567 | export CPPFLAGS CFLAGS LDFLAGS | |
568 | .fi | |
569 | .RE | |
570 | .PP | |
571 | And you can of course pass the flags to commands manually: | |
572 | .PP | |
573 | .RS 4 | |
574 | .nf | |
575 | include %PKGDATADIR%/buildflags.mk | |
576 | build\-arch: | |
577 | \& $(CC) \-o hello hello.c $(CPPFLAGS) $(CFLAGS) $(LDFLAGS) | |
578 | .fi | |
579 | .RE |