dpkg-architecture(1)

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

NAME

6       dpkg-architecture - set and determine the architecture for package
7       building
8

SYNOPSIS

10       dpkg-architecture [option...] [command]
11

DESCRIPTION

13       dpkg-architecture provides a facility to determine and set the build
14       and host architecture for package building.
15
16       The build architecture is always determined by either the
17       DEB_BUILD_ARCH variable if set (and --force not being specified) or by
18       an external call to dpkg(1), and cannot be set at the command line.
19
20       You can specify the host architecture by providing one or both of the
21       options --host-arch and --host-type, otherwise the DEB_HOST_ARCH
22       variable is used if set (and --force not being specified). The default
23       is determined by an external call to gcc(1), or the same as the build
24       architecture if CC or gcc are both not available. One out of
25       --host-arch and --host-type is sufficient, the value of the other will
26       be set to a usable default. Indeed, it is often better to only specify
27       one, because dpkg-architecture will warn you if your choice does not
28       match the default.
29

COMMANDS

31       -l, --list
32           Print the environment variables, one each line, in the format
33           VARIABLE=value. This is the default action.
34
35       -e, --equal architecture
36           Check for equality of architecture (since dpkg 1.13.13).  It
37           compares the current or specified Debian host architecture against
38           architecture, to check if they are equal.  This action will not
39           expand the architecture wildcards.  Command finishes with an exit
40           status of 0 if matched, 1 if not matched.
41
42       -i, --is architecture-wildcard
43           Check for identity of architecture (since dpkg 1.13.13).  It
44           compares the current or specified Debian host architecture against
45           architecture-wildcard after having expanded it as an architecture
46           wildcard, to check if they match.  Command finishes with an exit
47           status of 0 if matched, 1 if not matched.
48
49       -q, --query variable-name
50           Print the value of a single variable.
51
52       -s, --print-set
53           Print an export command. This can be used to set the environment
54           variables using the POSIX shell or make eval, depending on the
55           output format.
56
57       -u, --print-unset
58           Print a similar command to --print-set but to unset all variables.
59
60       -c, --command command-string
61           Execute a command-string in an environment which has all variables
62           set to the determined value.
63
64       -L, --list-known
65           Print a list of valid architecture names.  Possibly restricted by
66           one or more of the matching options --match-wildcard, --match-bits
67           or --match-endian (since dpkg 1.17.14).
68
69       -?, --help
70           Show the usage message and exit.
71
72       --version
73           Show the version and exit.
74

OPTIONS

76       -a, --host-arch architecture
77           Set the host Debian architecture.
78
79       -t, --host-type gnu-system-type
80           Set the host GNU system type.
81
82       -A, --target-arch architecture
83           Set the target Debian architecture (since dpkg 1.17.14).
84
85       -T, --target-type gnu-system-type
86           Set the target GNU system type (since dpkg 1.17.14).
87
88       -W, --match-wildcard architecture-wildcard
89           Restrict the architectures listed by --list-known to ones matching
90           the specified architecture wildcard (since dpkg 1.17.14).
91
92       -B, --match-bits architecture-bits
93           Restrict the architectures listed by --list-known to ones with the
94           specified CPU bits (since dpkg 1.17.14). Either 32 or 64.
95
96       -E, --match-endian architecture-endianness
97           Restrict the architectures listed by --list-known to ones with the
98           specified endianness (since dpkg 1.17.14). Either little or big.
99
100       --print-format format
101           Sets the output format for --print-set and --print-unset (since
102           dpkg 1.20.6), to either shell (default) or make.
103
104       -f, --force
105           Values set by existing environment variables with the same name as
106           used by the scripts are honored (i.e. used by dpkg-architecture),
107           except if this force flag is present. This allows the user to
108           override a value even when the call to dpkg-architecture is buried
109           in some other script (for example dpkg-buildpackage(1)).
110

TERMS

112       build machine
113           The machine the package is built on.
114
115       host machine
116           The machine the package is built for.
117
118       target machine
119           The machine the compiler is building for, or the emulator will run
120           code for.  This is only needed when building a cross-toolchain (or
121           emulator), one that will be built on the build architecture, to be
122           run on the host architecture, and to build (or run emulated) code
123           for the target architecture.
124
125       Debian architecture
126           The Debian architecture string, which specifies the binary tree in
127           the FTP archive. Examples: i386, sparc, hurd-i386.
128
129       Debian architecture tuple
130           A Debian architecture tuple is the fully qualified architecture
131           with all its components spelled out.  This differs with Debian
132           architectures in that at least the cpu component does not embed the
133           abi.  The current tuple has the form abi-libc-os-cpu.  Examples:
134           base-gnu-linux-amd64, eabihf-musl-linux-arm.
135
136       Debian architecture wildcard
137           A Debian architecture wildcard is a special architecture string
138           that will match any real architecture being part of it.  The
139           general form is a Debian architecture tuple with four or less
140           elements, and with at least one of them being any.  Missing
141           elements of the tuple are prefixed implicitly as any, and thus the
142           following pairs are equivalent:
143
144           any-any-any-any = any
145           any-any-os-any = os-any
146           any-libc-any-any = libc-any-any
147
148           Examples: linux-any, any-i386, hurd-any, eabi-any-any-arm, musl-
149           any-any.
150
151       GNU system type
152           An architecture specification string consisting of two parts
153           separated by a hyphen: cpu and system.  Examples: i586-linux-gnu,
154           sparc-linux-gnu, i686-gnu, x86_64-netbsd.
155
156       multiarch triplet
157           The clarified GNU system type, used for filesystem paths.  This
158           triplet does not change even when the baseline ISA gets bumped, so
159           that the resulting paths are stable over time.  The only current
160           difference with the GNU system type is that the CPU part for i386
161           based systems is always i386.  Examples: i386-linux-gnu,
162           x86_64-linux-gnu.  Example paths: /lib/powerpc64le-linux-gnu/,
163           /usr/lib/i386-kfreebsd-gnu/.
164

VARIABLES

166       The following variables are read from the environment (unless --force
167       has been specified) and set by dpkg-architecture (see the TERMS section
168       for a description of the naming scheme):
169
170       DEB_BUILD_ARCH
171           The Debian architecture of the build machine.
172
173       DEB_BUILD_ARCH_ABI
174           The Debian ABI name of the build machine (since dpkg 1.18.11).
175
176       DEB_BUILD_ARCH_LIBC
177           The Debian libc name of the build machine (since dpkg 1.18.11).
178
179       DEB_BUILD_ARCH_OS
180           The Debian system name of the build machine (since dpkg 1.13.2).
181
182       DEB_BUILD_ARCH_CPU
183           The Debian CPU name of the build machine (since dpkg 1.13.2).
184
185       DEB_BUILD_ARCH_BITS
186           The pointer size of the build machine (in bits; since dpkg 1.15.4).
187
188       DEB_BUILD_ARCH_ENDIAN
189           The endianness of the build machine (little / big; since dpkg
190           1.15.4).
191
192       DEB_BUILD_GNU_CPU
193           The GNU CPU part of DEB_BUILD_GNU_TYPE.
194
195       DEB_BUILD_GNU_SYSTEM
196           The GNU system part of DEB_BUILD_GNU_TYPE.
197
198       DEB_BUILD_GNU_TYPE
199           The GNU system type of the build machine.
200
201       DEB_BUILD_MULTIARCH
202           The clarified GNU system type of the build machine, used for
203           filesystem paths (since dpkg 1.16.0).
204
205       DEB_HOST_ARCH
206           The Debian architecture of the host machine.
207
208       DEB_HOST_ARCH_ABI
209           The Debian ABI name of the host machine (since dpkg 1.18.11).
210
211       DEB_HOST_ARCH_LIBC
212           The Debian libc name of the host machine (since dpkg 1.18.11).
213
214       DEB_HOST_ARCH_OS
215           The Debian system name of the host machine (since dpkg 1.13.2).
216
217       DEB_HOST_ARCH_CPU
218           The Debian CPU name of the host machine (since dpkg 1.13.2).
219
220       DEB_HOST_ARCH_BITS
221           The pointer size of the host machine (in bits; since dpkg 1.15.4).
222
223       DEB_HOST_ARCH_ENDIAN
224           The endianness of the host machine (little / big; since dpkg
225           1.15.4).
226
227       DEB_HOST_GNU_CPU
228           The GNU CPU part of DEB_HOST_GNU_TYPE.
229
230       DEB_HOST_GNU_SYSTEM
231           The GNU system part of DEB_HOST_GNU_TYPE.
232
233       DEB_HOST_GNU_TYPE
234           The GNU system type of the host machine.
235
236       DEB_HOST_MULTIARCH
237           The clarified GNU system type of the host machine, used for
238           filesystem paths (since dpkg 1.16.0).
239
240       DEB_TARGET_ARCH
241           The Debian architecture of the target machine (since dpkg 1.17.14).
242
243       DEB_TARGET_ARCH_ABI
244           The Debian ABI name of the target machine (since dpkg 1.18.11).
245
246       DEB_TARGET_ARCH_LIBC
247           The Debian libc name of the target machine (since dpkg 1.18.11).
248
249       DEB_TARGET_ARCH_OS
250           The Debian system name of the target machine (since dpkg 1.17.14).
251
252       DEB_TARGET_ARCH_CPU
253           The Debian CPU name of the target machine (since dpkg 1.17.14).
254
255       DEB_TARGET_ARCH_BITS
256           The pointer size of the target machine (in bits; since dpkg
257           1.17.14).
258
259       DEB_TARGET_ARCH_ENDIAN
260           The endianness of the target machine (little / big; since dpkg
261           1.17.14).
262
263       DEB_TARGET_GNU_CPU
264           The GNU CPU part of DEB_TARGET_GNU_TYPE (since dpkg 1.17.14).
265
266       DEB_TARGET_GNU_SYSTEM
267           The GNU system part of DEB_TARGET_GNU_TYPE (since dpkg 1.17.14).
268
269       DEB_TARGET_GNU_TYPE
270           The GNU system type of the target machine (since dpkg 1.17.14).
271
272       DEB_TARGET_MULTIARCH
273           The clarified GNU system type of the target machine, used for
274           filesystem paths (since dpkg 1.17.14).
275

FILES

277   Architecture tables
278       All these files have to be present for dpkg-architecture to work. Their
279       location can be overridden at runtime with the environment variable
280       DPKG_DATADIR.  These tables contain a format Version pseudo-field on
281       their first line to mark their format, so that parsers can check if
282       they understand it, such as "# Version=1.0".
283
284       /usr/share/dpkg/cputable
285           Table of known CPU names and mapping to their GNU name.  Format
286           version 1.0 (since dpkg 1.13.2).
287
288       /usr/share/dpkg/ostable
289           Table of known operating system names and mapping to their GNU
290           name.  Format version 2.0 (since dpkg 1.18.11).
291
292       /usr/share/dpkg/tupletable
293           Mapping between Debian architecture tuples and Debian architecture
294           names.  Format version 1.0 (since dpkg 1.18.11).
295
296       /usr/share/dpkg/abitable
297           Table of Debian architecture ABI attribute overrides.  Format
298           version 2.0 (since dpkg 1.18.11).
299
300   Packaging support
301       /usr/share/dpkg/architecture.mk
302           Makefile snippet that properly sets and exports all the variables
303           that dpkg-architecture outputs (since dpkg 1.16.1).
304

EXAMPLES

306       dpkg-buildpackage accepts the -a option and passes it to dpkg-
307       architecture. Other examples:
308
309        CC=i386-gnu-gcc dpkg-architecture -c debian/rules build
310
311        eval $(dpkg-architecture -u)
312
313       Check if the current or specified host architecture is equal to an
314       architecture:
315
316        dpkg-architecture -elinux-alpha
317
318        dpkg-architecture -amips -elinux-mips
319
320       Check if the current or specified host architecture is a Linux system:
321
322        dpkg-architecture -ilinux-any
323
324        dpkg-architecture -ai386 -ilinux-any
325
326   Usage in debian/rules
327       The environment variables set by dpkg-architecture are passed to
328       debian/rules as make variables (see make documentation). However, you
329       should not rely on them, as this breaks manual invocation of the
330       script. Instead, you should always initialize them using dpkg-
331       architecture with the -q option. Here are some examples, which also
332       show how you can improve the cross compilation support in your package:
333
334       Retrieving the GNU system type and forwarding it to ./configure:
335
336        DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE)
337        DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE)
338        [...]
339        ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE))
340          confflags += --build=$(DEB_HOST_GNU_TYPE)
341        else
342          confflags += --build=$(DEB_BUILD_GNU_TYPE) \
343                       --host=$(DEB_HOST_GNU_TYPE)
344        endif
345        [...]
346        ./configure $(confflags)
347
348       Doing something only for a specific architecture:
349
350        DEB_HOST_ARCH ?= $(shell dpkg-architecture -qDEB_HOST_ARCH)
351
352        ifeq ($(DEB_HOST_ARCH),alpha)
353          [...]
354        endif
355
356       or if you only need to check the CPU or OS type, use the
357       DEB_HOST_ARCH_CPU or DEB_HOST_ARCH_OS variables.
358
359       Note that you can also rely on an external Makefile snippet to properly
360       set all the variables that dpkg-architecture can provide:
361
362        include /usr/share/dpkg/architecture.mk
363
364        ifeq ($(DEB_HOST_ARCH),alpha)
365          [...]
366        endif
367
368       In any case, you should never use dpkg --print-architecture to get
369       architecture information during a package build.
370

ENVIRONMENT

372       DPKG_DATADIR
373           If set, it will be used as the dpkg data directory, where the
374           architecture tables are located (since dpkg 1.14.17).  Defaults to
375           «/usr/share/dpkg».
376
377       DPKG_COLORS
378           Sets the color mode (since dpkg 1.18.5).  The currently accepted
379           values are: auto (default), always and never.
380
381       DPKG_NLS
382           If set, it will be used to decide whether to activate Native
383           Language Support, also known as internationalization (or i18n)
384           support (since dpkg 1.19.0).  The accepted values are: 0 and 1
385           (default).
386

NOTES

388       All long command and option names available only since dpkg 1.17.17.
389