Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | .\" dpkg manual page - dpkg-architecture(1) |
2 | .\" | |
3 | .\" Copyright © 2005 Marcus Brinkmann <brinkmd@debian.org> | |
4 | .\" Copyright © 2005 Scott James Remnant <scott@netsplit.com> | |
5 | .\" Copyright © 2006-2015 Guillem Jover <guillem@debian.org> | |
6 | .\" Copyright © 2009-2012 Raphaël Hertzog <hertzog@debian.org> | |
7 | .\" | |
8 | .\" This is free software; you can redistribute it and/or modify | |
9 | .\" it under the terms of the GNU General Public License as published by | |
10 | .\" the Free Software Foundation; either version 2 of the License, or | |
11 | .\" (at your option) any later version. | |
12 | .\" | |
13 | .\" This is distributed in the hope that it will be useful, | |
14 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | .\" GNU General Public License for more details. | |
17 | .\" | |
18 | .\" You should have received a copy of the GNU General Public License | |
19 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
20 | . | |
21 | .TH dpkg\-architecture 1 "%RELEASE_DATE%" "%VERSION%" "dpkg suite" | |
22 | .nh | |
23 | .SH NAME | |
24 | dpkg\-architecture \- set and determine the architecture for package building | |
25 | . | |
26 | .SH SYNOPSIS | |
27 | .B dpkg\-architecture | |
28 | .RI [ option "...] [" command ] | |
29 | .PP | |
30 | . | |
31 | .SH DESCRIPTION | |
32 | .B dpkg\-architecture | |
33 | provides a facility to determine and set the build and | |
34 | host architecture for package building. | |
35 | .PP | |
36 | The build architecture is always determined by an external call to | |
37 | \fBdpkg\fP(1), and cannot be set at the command line. | |
38 | .PP | |
39 | You can specify the host architecture by providing one or both of the options | |
40 | \fB\-\-host\-arch\fR and \fB\-\-host\-type\fR. The default is determined by | |
41 | an external call to | |
42 | .BR gcc (1), | |
43 | or the same as the build architecture if \fBCC\fP or gcc are both not | |
44 | available. One out of \fB\-\-host\-arch\fR and \fB\-\-host\-type\fR is | |
45 | sufficient, the value of the | |
46 | other will be set to a usable default. Indeed, it is often better to only | |
47 | specify one, because \fBdpkg\-architecture\fP will warn you if your choice | |
48 | does not match the default. | |
49 | . | |
50 | .SH COMMANDS | |
51 | .TP | |
52 | .BR \-l ", " \-\-list | |
53 | Print the environment variables, one each line, in the format | |
54 | \fIVARIABLE=value\fP. This is the default action. | |
55 | .TP | |
56 | .BR \-e ", " \-\-equal " \fIarchitecture\fP" | |
57 | Check for equality of architecture (since dpkg 1.13.13). | |
58 | It compares the current or specified Debian host architecture against | |
59 | \fIarchitecture\fP, to check if they are equal. | |
60 | This action will not expand the architecture wildcards. | |
61 | Command finishes with an exit status of 0 if matched, 1 if not matched. | |
62 | ||
63 | .TP | |
64 | .BR \-i ", " \-\-is " \fIarchitecture-wildcard\fP" | |
65 | Check for identity of architecture (since dpkg 1.13.13). | |
66 | It compares the current or specified Debian host architecture against | |
67 | \fIarchitecture-wildcard\fP after having expanded it as an architecture | |
68 | wildcard, to check if they match. | |
69 | Command finishes with an exit status of 0 if matched, 1 if not matched. | |
70 | .TP | |
71 | .BR \-q ", " \-\-query " \fIvariable-name\fP" | |
72 | Print the value of a single variable. | |
73 | .TP | |
74 | .BR \-s ", " \-\-print\-set | |
75 | Print an export command. This can be used to set the environment variables | |
76 | using eval. | |
77 | .TP | |
78 | .BR \-u ", " \-\-print\-unset | |
79 | Print a similar command to \fB\-\-print\-unset\fP but to unset all variables. | |
80 | .TP | |
81 | .BR \-c ", " \-\-command " \fIcommand\fP" | |
82 | Execute a \fIcommand\fP in an environment which has all variables set to | |
83 | the determined value. | |
84 | .TP | |
85 | .BR \-L ", " \-\-list\-known | |
86 | Print a list of valid architecture names. | |
87 | Possibly restricted by one or more of the matching options | |
88 | \fB\-\-match\-wildcard\fP, \fB\-\-match\-bits\fP or \fB\-\-match\-endian\fP | |
89 | (since dpkg 1.17.14). | |
90 | .TP | |
91 | .BR \-? ", " \-\-help | |
92 | Show the usage message and exit. | |
93 | .TP | |
94 | .B \-\-version | |
95 | Show the version and exit. | |
96 | . | |
97 | .SH OPTIONS | |
98 | .TP | |
99 | .BR \-a ", " \-\-host\-arch " \fIarchitecture\fP" | |
100 | Set the host Debian architecture. | |
101 | .TP | |
102 | .BR \-t ", " \-\-host\-type " \fIgnu-system-type\fP" | |
103 | Set the host GNU system type. | |
104 | .TP | |
105 | .BR \-A ", " \-\-target\-arch " \fIarchitecture\fP" | |
106 | Set the target Debian architecture (since dpkg 1.17.14). | |
107 | .TP | |
108 | .BR \-T ", " \-\-target\-type " \fIgnu-system-type\fP" | |
109 | Set the target GNU system type (since dpkg 1.17.14). | |
110 | .TP | |
111 | .BR \-W ", " \-\-match\-wildcard " \fIarchitecture-wildcard\fP" | |
112 | Restrict the architectures listed by \fB\-\-list\-known\fP to ones matching | |
113 | the specified architecture wildcard (since dpkg 1.17.14). | |
114 | .TP | |
115 | .BR \-B ", " \-\-match\-bits " \fIarchitecture-bits\fP" | |
116 | Restrict the architectures listed by \fB\-\-list\-known\fP to ones with the | |
117 | specified CPU bits (since dpkg 1.17.14). Either \fB32\fP or \fB64\fP. | |
118 | .TP | |
119 | .BR \-E ", " \-\-match\-endian " \fIarchitecture-endianness\fP" | |
120 | Restrict the architectures listed by \fB\-\-list\-known\fP to ones with the | |
121 | specified endianness (since dpkg 1.17.14). Either \fBlittle\fP or \fBbig\fP. | |
122 | .TP | |
123 | .BR \-f ", " \-\-force | |
124 | Values set by existing environment variables with the same name as used by | |
125 | the scripts are honored (i.e. used by \fBdpkg\-architecture\fP), except if | |
126 | this force flag is present. This allows the user | |
127 | to override a value even when the call to \fBdpkg\-architecture\fP is buried | |
128 | in some other script (for example \fBdpkg\-buildpackage\fP(1)). | |
129 | . | |
130 | .SH TERMS | |
131 | .IP "build machine" 4 | |
132 | The machine the package is built on. | |
133 | .IP "host machine" 4 | |
134 | The machine the package is built for. | |
135 | .IP "target machine" 4 | |
136 | The machine the compiler is building for. | |
137 | This is only needed when building a cross-toolchain, one that will be built | |
138 | on the build architecture, to be run on the host architecture, and to build | |
139 | code for the target architecture. | |
140 | .IP "Debian architecture" 4 | |
141 | The Debian architecture string, which specifies the binary tree in the | |
142 | FTP archive. Examples: i386, sparc, hurd\-i386. | |
143 | .IP "Debian architecture tuple" 4 | |
144 | A Debian architecture tuple is the fully qualified architecture with all its | |
145 | components spelled out. | |
146 | This differs with Debian architectures in that at least the \fIcpu\fP | |
147 | component does not embed the \fIabi\fP. | |
148 | The current tuple has the form \fIabi\fP\-\fIlibc\fP\-\fIos\fP\-\fIcpu\fP. | |
149 | Examples: base\-gnu\-linux\-amd64, eabihf\-musl\-linux\-arm. | |
150 | .IP "Debian architecture wildcard" 4 | |
151 | A Debian architecture wildcard is a special architecture string that will | |
152 | match any real architecture being part of it. | |
153 | The general form is a Debian architecture tuple with four or less elements, | |
154 | and with at least one of them being \fBany\fP. | |
155 | Missing elements of the tuple are prefixed implicitly as \fBany\fP, and thus | |
156 | the following pairs are equivalent: | |
157 | .nf | |
158 | \fBany\fP\-\fBany\fP\-\fBany\fP\-\fBany\fP = \fBany\fP | |
159 | \fBany\fP\-\fBany\fP\-\fIos\fP\-\fBany\fP = \fIos\fP\-\fBany\fP | |
160 | \fBany\fP\-\fIlibc\fP\-\fBany\fP\-\fBany\fP = \fIlibc\fP\-\fBany\fP\-\fBany\fP | |
161 | .fi | |
162 | Examples: linux\-any, any\-i386, hurd\-any, eabi\-any\-any\-arm, | |
163 | musl\-any\-any. | |
164 | .IP "GNU system type" 4 | |
165 | An architecture specification string consisting of two parts separated by | |
166 | a hyphen: cpu and system. | |
167 | Examples: i586\-linux\-gnu, sparc\-linux\-gnu, i686\-gnu, x86_64\-netbsd. | |
168 | .IP "multiarch triplet" 4 | |
169 | The clarified GNU system type, used for filesystem paths. | |
170 | This triplet does not change even when the baseline ISA gets bumped, | |
171 | so that the resulting paths are stable over time. | |
172 | The only current difference with the GNU system type is that the CPU part | |
173 | for i386 based systems is always i386. | |
174 | Examples: i386\-linux\-gnu, x86_64\-linux\-gnu. | |
175 | Example paths: /lib/powerpc64le-linux-gnu/, /usr/lib/i386-kfreebsd-gnu/. | |
176 | . | |
177 | .SH VARIABLES | |
178 | The following variables are set by \fBdpkg\-architecture\fP: | |
179 | .IP "\fBDEB_BUILD_ARCH\fP" 4 | |
180 | The Debian architecture of the build machine. | |
181 | .IP "\fBDEB_BUILD_ARCH_ABI\fP" 4 | |
182 | The Debian abi name of the build machine (since dpkg 1.18.11). | |
183 | .IP "\fBDEB_BUILD_ARCH_LIBC\fP" 4 | |
184 | The Debian libc name of the build machine (since dpkg 1.18.11). | |
185 | .IP "\fBDEB_BUILD_ARCH_OS\fP" 4 | |
186 | The Debian system name of the build machine (since dpkg 1.13.2). | |
187 | .IP "\fBDEB_BUILD_ARCH_CPU\fP" 4 | |
188 | The Debian cpu name of the build machine (since dpkg 1.13.2). | |
189 | .IP "\fBDEB_BUILD_ARCH_BITS\fP" 4 | |
190 | The pointer size of the build machine (in bits; since dpkg 1.15.4). | |
191 | .IP "\fBDEB_BUILD_ARCH_ENDIAN\fP" 4 | |
192 | The endianness of the build machine (little / big; since dpkg 1.15.4). | |
193 | .IP "\fBDEB_BUILD_GNU_CPU\fP" 4 | |
194 | The CPU part of \fBDEB_BUILD_GNU_TYPE\fP. | |
195 | .IP "\fBDEB_BUILD_GNU_SYSTEM\fP" 4 | |
196 | The System part of \fBDEB_BUILD_GNU_TYPE\fP. | |
197 | .IP "\fBDEB_BUILD_GNU_TYPE\fP" 4 | |
198 | The GNU system type of the build machine. | |
199 | .IP "\fBDEB_BUILD_MULTIARCH\fP" 4 | |
200 | The clarified GNU system type of the build machine, used for filesystem | |
201 | paths (since dpkg 1.16.0). | |
202 | .IP "\fBDEB_HOST_ARCH\fP" 4 | |
203 | The Debian architecture of the host machine. | |
204 | .IP "\fBDEB_HOST_ARCH_ABI\fP" 4 | |
205 | The Debian abi name of the host machine (since dpkg 1.18.11). | |
206 | .IP "\fBDEB_HOST_ARCH_LIBC\fP" 4 | |
207 | The Debian libc name of the host machine (since dpkg 1.18.11). | |
208 | .IP "\fBDEB_HOST_ARCH_OS\fP" 4 | |
209 | The Debian system name of the host machine (since dpkg 1.13.2). | |
210 | .IP "\fBDEB_HOST_ARCH_CPU\fP" 4 | |
211 | The Debian cpu name of the host machine (since dpkg 1.13.2). | |
212 | .IP "\fBDEB_HOST_ARCH_BITS\fP" 4 | |
213 | The pointer size of the host machine (in bits; since dpkg 1.15.4). | |
214 | .IP "\fBDEB_HOST_ARCH_ENDIAN\fP" 4 | |
215 | The endianness of the host machine (little / big; since dpkg 1.15.4). | |
216 | .IP "\fBDEB_HOST_GNU_CPU\fP" 4 | |
217 | The CPU part of \fBDEB_HOST_GNU_TYPE\fP. | |
218 | .IP "\fBDEB_HOST_GNU_SYSTEM\fP" 4 | |
219 | The System part of \fBDEB_HOST_GNU_TYPE\fP. | |
220 | .IP "\fBDEB_HOST_GNU_TYPE\fP" 4 | |
221 | The GNU system type of the host machine. | |
222 | .IP "\fBDEB_HOST_MULTIARCH\fP" 4 | |
223 | The clarified GNU system type of the host machine, used for filesystem | |
224 | paths (since dpkg 1.16.0). | |
225 | .IP "\fBDEB_TARGET_ARCH\fP" 4 | |
226 | The Debian architecture of the target machine (since dpkg 1.17.14). | |
227 | .IP "\fBDEB_TARGET_ARCH_ABI\fP" 4 | |
228 | The Debian abi name of the target machine (since dpkg 1.18.11). | |
229 | .IP "\fBDEB_TARGET_ARCH_LIBC\fP" 4 | |
230 | The Debian libc name of the target machine (since dpkg 1.18.11). | |
231 | .IP "\fBDEB_TARGET_ARCH_OS\fP" 4 | |
232 | The Debian system name of the target machine (since dpkg 1.17.14). | |
233 | .IP "\fBDEB_TARGET_ARCH_CPU\fP" 4 | |
234 | The Debian cpu name of the target machine (since dpkg 1.17.14). | |
235 | .IP "\fBDEB_TARGET_ARCH_BITS\fP" 4 | |
236 | The pointer size of the target machine (in bits; since dpkg 1.17.14). | |
237 | .IP "\fBDEB_TARGET_ARCH_ENDIAN\fP" 4 | |
238 | The endianness of the target machine (little / big; since dpkg 1.17.14). | |
239 | .IP "\fBDEB_TARGET_GNU_CPU\fP" 4 | |
240 | The CPU part of \fBDEB_TARGET_GNU_TYPE\fP (since dpkg 1.17.14). | |
241 | .IP "\fBDEB_TARGET_GNU_SYSTEM\fP" 4 | |
242 | The System part of \fBDEB_TARGET_GNU_TYPE\fP (since dpkg 1.17.14). | |
243 | .IP "\fBDEB_TARGET_GNU_TYPE\fP" 4 | |
244 | The GNU system type of the target machine (since dpkg 1.17.14). | |
245 | .IP "\fBDEB_TARGET_MULTIARCH\fP" 4 | |
246 | The clarified GNU system type of the target machine, used for filesystem | |
247 | paths (since dpkg 1.17.14). | |
248 | . | |
249 | .SH FILES | |
250 | .SS Architecture tables | |
251 | All these files have to be present for \fBdpkg\-architecture\fP to | |
252 | work. Their location can be overridden at runtime with the environment | |
253 | variable \fBDPKG_DATADIR\fP. | |
254 | These tables contain a format \fBVersion\fP pseudo-field on their first | |
255 | line to mark their format, so that parsers can check if they understand | |
256 | it, such as "# Version=1.0". | |
257 | .TP | |
258 | .I %PKGDATADIR%/cputable | |
259 | Table of known CPU names and mapping to their GNU name. | |
260 | Format version 1.0 (since dpkg 1.13.2). | |
261 | .TP | |
262 | .I %PKGDATADIR%/ostable | |
263 | Table of known operating system names and mapping to their GNU name. | |
264 | Format version 2.0 (since dpkg 1.18.11). | |
265 | .TP | |
266 | .I %PKGDATADIR%/tupletable | |
267 | Mapping between Debian architecture tuples and Debian architecture | |
268 | names. | |
269 | Format version 1.0 (since dpkg 1.18.11). | |
270 | .TP | |
271 | .I %PKGDATADIR%/abitable | |
272 | Table of Debian architecture ABI attribute overrides. | |
273 | Format version 2.0 (since dpkg 1.18.11). | |
274 | .SS Packaging support | |
275 | .TP | |
276 | .I %PKGDATADIR%/architecture.mk | |
277 | Makefile snippet that properly sets and exports all the variables that | |
278 | \fBdpkg\-architecture\fP outputs (since dpkg 1.16.1). | |
279 | . | |
280 | .SH EXAMPLES | |
281 | \fBdpkg\-buildpackage\fP accepts the \fB\-a\fR option and passes it to | |
282 | \fBdpkg\-architecture\fP. Other examples: | |
283 | .IP | |
284 | CC=i386\-gnu\-gcc dpkg\-architecture \-c debian/rules build | |
285 | .IP | |
286 | eval \`dpkg\-architecture \-u\` | |
287 | .PP | |
288 | Check if the current or specified host architecture is equal to an | |
289 | architecture: | |
290 | .IP | |
291 | dpkg\-architecture \-elinux\-alpha | |
292 | .IP | |
293 | dpkg\-architecture \-amips \-elinux\-mips | |
294 | .PP | |
295 | Check if the current or specified host architecture is a Linux system: | |
296 | .IP | |
297 | dpkg\-architecture \-ilinux\-any | |
298 | .IP | |
299 | dpkg\-architecture \-ai386 \-ilinux\-any | |
300 | . | |
301 | .SS Usage in debian/rules | |
302 | The environment variables set by \fBdpkg\-architecture\fP are passed to | |
303 | \fIdebian/rules\fP as make variables (see make documentation). However, | |
304 | you should not rely on them, as this breaks manual invocation of the | |
305 | script. Instead, you should always initialize them using | |
306 | \fBdpkg\-architecture\fP with the \fB\-q\fP option. Here are some examples, | |
307 | which also show how you can improve the cross compilation support in your | |
308 | package: | |
309 | .PP | |
310 | Retrieving the GNU system type and forwarding it to ./configure: | |
311 | .PP | |
312 | .RS 4 | |
313 | .nf | |
314 | DEB_BUILD_GNU_TYPE ?= $(shell dpkg\-architecture \-qDEB_BUILD_GNU_TYPE) | |
315 | DEB_HOST_GNU_TYPE ?= $(shell dpkg\-architecture \-qDEB_HOST_GNU_TYPE) | |
316 | [...] | |
317 | ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE)) | |
318 | confflags += \-\-build=$(DEB_HOST_GNU_TYPE) | |
319 | else | |
320 | confflags += \-\-build=$(DEB_BUILD_GNU_TYPE) \\ | |
321 | \-\-host=$(DEB_HOST_GNU_TYPE) | |
322 | endif | |
323 | [...] | |
324 | \&./configure $(confflags) | |
325 | .fi | |
326 | .RE | |
327 | .PP | |
328 | Doing something only for a specific architecture: | |
329 | .PP | |
330 | .RS 4 | |
331 | .nf | |
332 | DEB_HOST_ARCH ?= $(shell dpkg\-architecture \-qDEB_HOST_ARCH) | |
333 | ||
334 | ifeq ($(DEB_HOST_ARCH),alpha) | |
335 | [...] | |
336 | endif | |
337 | .fi | |
338 | .RE | |
339 | .PP | |
340 | or if you only need to check the CPU or OS type, use the | |
341 | \fBDEB_HOST_ARCH_CPU\fP or \fBDEB_HOST_ARCH_OS\fP variables. | |
342 | .PP | |
343 | Note that you can also rely on an external Makefile snippet to properly | |
344 | set all the variables that \fBdpkg\-architecture\fP can provide: | |
345 | .PP | |
346 | .RS 4 | |
347 | .nf | |
348 | include %PKGDATADIR%/architecture.mk | |
349 | ||
350 | ifeq ($(DEB_HOST_ARCH),alpha) | |
351 | [...] | |
352 | endif | |
353 | .fi | |
354 | .RE | |
355 | .PP | |
356 | In any case, you should never use \fBdpkg \-\-print\-architecture\fP to get | |
357 | architecture information during a package build. | |
358 | . | |
359 | .SH ENVIRONMENT | |
360 | .TP | |
361 | .B DPKG_DATADIR | |
362 | If set, it will be used as the \fBdpkg\fP data directory, where the | |
363 | architecture tables are located (since dpkg 1.14.17). | |
364 | Defaults to «%PKGDATADIR%». | |
365 | .SH NOTES | |
366 | All long command and option names available only since dpkg 1.17.17. | |
367 | . | |
368 | .SH SEE ALSO | |
369 | .BR dpkg\-buildpackage (1), | |
370 | .BR dpkg\-cross (1). |