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

VARIABLES

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

FILES

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

EXAMPLES

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

ENVIRONMENT

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

NOTES

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