man/dpkg-architecture.pod

   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 =encoding utf8
  22
  23 =head1 NAME
  24
  25 dpkg-architecture - set and determine the architecture for package building
  26
  27 =head1 SYNOPSIS
  28
  29 B<dpkg-architecture>
  30 [I<option>...] [I<command>]
  31
  32 =head1 DESCRIPTION
  33
  34 B<dpkg-architecture>
  35 provides a facility to determine and set the build and
  36 host architecture for package building.
  37
  38 The build architecture is always determined by either the B<DEB_BUILD_ARCH>
  39 variable if set (and B<--force> not being specified) or by an external call to
  40 L<dpkg(1)>, and cannot be set at the command line.
  41
  42 You can specify the host architecture by providing one or both of the options
  43 B<--host-arch> and B<--host-type>, otherwise the B<DEB_HOST_ARCH> variable
  44 is used if set (and B<--force> not being specified). The default is
  45 determined by an external call to L<gcc(1)>,
  46 or the same as the build architecture if B<CC> or gcc are both not
  47 available. One out of B<--host-arch> and B<--host-type> is
  48 sufficient, the value of the
  49 other will be set to a usable default. Indeed, it is often better to only
  50 specify one, because B<dpkg-architecture> will warn you if your choice
  51 does not match the default.
  52
  53 =head1 COMMANDS
  54
  55 =over
  56
  57 =item B<-l>, B<--list>
  58
  59 Print the environment variables, one each line, in the format
  60 I<VARIABLE=value>. This is the default action.
  61
  62 =item B<-e>, B<--equal> I<architecture>
  63
  64 Check for equality of architecture (since dpkg 1.13.13).
  65 It compares the current or specified Debian host architecture against
  66 I<architecture>, to check if they are equal.
  67 This action will not expand the architecture wildcards.
  68 Command finishes with an exit status of 0 if matched, 1 if not matched.
  69
  70 =item B<-i>, B<--is> I<architecture-wildcard>
  71
  72 Check for identity of architecture (since dpkg 1.13.13).
  73 It compares the current or specified Debian host architecture against
  74 I<architecture-wildcard> after having expanded it as an architecture
  75 wildcard, to check if they match.
  76 Command finishes with an exit status of 0 if matched, 1 if not matched.
  77
  78 =item B<-q>, B<--query> I<variable-name>
  79
  80 Print the value of a single variable.
  81
  82 =item B<-s>, B<--print-set>
  83
  84 Print an export command. This can be used to set the environment variables
  85 using the POSIX shell or make B<eval>, depending on the output format.
  86
  87 =item B<-u>, B<--print-unset>
  88
  89 Print a similar command to B<--print-set> but to unset all variables.
  90
  91 =item B<-c>, B<--command> I<command-string>
  92
  93 Execute a I<command-string> in an environment which has all variables
  94 set to the determined value.
  95
  96 If the I<command-string> contains shell metacharacters, then it will be
  97 invoked through the system bourne shell.
  98
  99 =item B<-L>, B<--list-known>
 100
 101 Print a list of valid architecture names.
 102 Possibly restricted by one or more of the matching options
 103 B<--match-wildcard>, B<--match-bits> or B<--match-endian>
 104 (since dpkg 1.17.14).
 105
 106 =item B<-?>, B<--help>
 107
 108 Show the usage message and exit.
 109
 110 =item B<--version>
 111
 112 Show the version and exit.
 113
 114 =back
 115
 116 =head1 OPTIONS
 117
 118 =over
 119
 120 =item B<-a>, B<--host-arch> I<architecture>
 121
 122 Set the host Debian architecture.
 123
 124 =item B<-t>, B<--host-type> I<gnu-system-type>
 125
 126 Set the host GNU system type.
 127
 128 =item B<-A>, B<--target-arch> I<architecture>
 129
 130 Set the target Debian architecture (since dpkg 1.17.14).
 131
 132 =item B<-T>, B<--target-type> I<gnu-system-type>
 133
 134 Set the target GNU system type (since dpkg 1.17.14).
 135
 136 =item B<-W>, B<--match-wildcard> I<architecture-wildcard>
 137
 138 Restrict the architectures listed by B<--list-known> to ones matching
 139 the specified architecture wildcard (since dpkg 1.17.14).
 140
 141 =item B<-B>, B<--match-bits> I<architecture-bits>
 142
 143 Restrict the architectures listed by B<--list-known> to ones with the
 144 specified CPU bits (since dpkg 1.17.14). Either B<32> or B<64>.
 145
 146 =item B<-E>, B<--match-endian> I<architecture-endianness>
 147
 148 Restrict the architectures listed by B<--list-known> to ones with the
 149 specified endianness (since dpkg 1.17.14). Either B<little> or B<big>.
 150
 151 =item B<--print-format> I<format>
 152
 153 Sets the output format for B<--print-set> and B<--print-unset>
 154 (since dpkg 1.20.6), to either B<shell> (default) or B<make>.
 155
 156 =item B<-f>, B<--force>
 157
 158 Values set by existing environment variables with the same name as used by
 159 the scripts are honored (i.e. used by B<dpkg-architecture>), except if
 160 this force flag is present. This allows the user
 161 to override a value even when the call to B<dpkg-architecture> is buried
 162 in some other script (for example L<dpkg-buildpackage(1)>).
 163
 164 =back
 165
 166 =head1 TERMS
 167
 168 =over
 169
 170 =item build machine
 171
 172 The machine the package is built on.
 173
 174 =item host machine
 175
 176 The machine the package is built for.
 177
 178 =item target machine
 179
 180 The machine the compiler is building for, or the emulator will run code for.
 181 This is only needed when building a cross-toolchain (or emulator), one that
 182 will be built on the build architecture, to be run on the host architecture,
 183 and to build (or run emulated) code for the target architecture.
 184
 185 =item Debian architecture
 186
 187 The Debian architecture string, which specifies the binary tree in the
 188 FTP archive. Examples: i386, sparc, hurd-i386.
 189
 190 =item Debian architecture tuple
 191
 192 A Debian architecture tuple is the fully qualified architecture with all its
 193 components spelled out.
 194 This differs with Debian architectures in that at least the I<cpu>
 195 component does not embed the I<abi>.
 196 The current tuple has the form I<abi>-I<libc>-I<os>-I<cpu>.
 197 Examples: base-gnu-linux-amd64, eabihf-musl-linux-arm.
 198
 199 =item Debian architecture wildcard
 200
 201 A Debian architecture wildcard is a special architecture string that will
 202 match any real architecture being part of it.
 203 The general form is a Debian architecture tuple with four or less elements,
 204 and with at least one of them being B<any>.
 205 Missing elements of the tuple are prefixed implicitly as B<any>, and thus
 206 the following pairs are equivalent:
 207
 208 =over
 209
 210 =item B<any>-B<any>-B<any>-B<any> = B<any>
 211
 212 =item B<any>-B<any>-I<os>-B<any> = I<os>-B<any>
 213
 214 =item B<any>-I<libc>-B<any>-B<any> = I<libc>-B<any>-B<any>
 215
 216 =back
 217
 218 Examples: linux-any, any-i386, hurd-any, eabi-any-any-arm,
 219 musl-any-any.
 220
 221 =item GNU system type
 222
 223 An architecture specification string consisting of two parts separated by
 224 a hyphen: cpu and system.
 225 Examples: i586-linux-gnu, sparc-linux-gnu, i686-gnu, x86_64-netbsd.
 226
 227 =item multiarch triplet
 228
 229 The clarified GNU system type, used for filesystem paths.
 230 This triplet does not change even when the baseline ISA gets bumped,
 231 so that the resulting paths are stable over time.
 232 The only current difference with the GNU system type is that the CPU part
 233 for i386 based systems is always i386.
 234 Examples: i386-linux-gnu, x86_64-linux-gnu.
 235 Example paths: /lib/powerpc64le-linux-gnu/, /usr/lib/i386-kfreebsd-gnu/.
 236
 237 =back
 238
 239 =head1 VARIABLES
 240
 241 The following variables are read from the environment (unless B<--force>
 242 has been specified) and set by B<dpkg-architecture> (see the B<TERMS>
 243 section for a description of the naming scheme):
 244
 245 =over
 246
 247 =item B<DEB_BUILD_ARCH>
 248
 249 The Debian architecture of the build machine.
 250
 251 =item B<DEB_BUILD_ARCH_ABI>
 252
 253 The Debian ABI name of the build machine (since dpkg 1.18.11).
 254
 255 =item B<DEB_BUILD_ARCH_LIBC>
 256
 257 The Debian libc name of the build machine (since dpkg 1.18.11).
 258
 259 =item B<DEB_BUILD_ARCH_OS>
 260
 261 The Debian system name of the build machine (since dpkg 1.13.2).
 262
 263 =item B<DEB_BUILD_ARCH_CPU>
 264
 265 The Debian CPU name of the build machine (since dpkg 1.13.2).
 266
 267 =item B<DEB_BUILD_ARCH_BITS>
 268
 269 The pointer size of the build machine (in bits; since dpkg 1.15.4).
 270
 271 =item B<DEB_BUILD_ARCH_ENDIAN>
 272
 273 The endianness of the build machine (little / big; since dpkg 1.15.4).
 274
 275 =item B<DEB_BUILD_GNU_CPU>
 276
 277 The GNU CPU part of B<DEB_BUILD_GNU_TYPE>.
 278
 279 =item B<DEB_BUILD_GNU_SYSTEM>
 280
 281 The GNU system part of B<DEB_BUILD_GNU_TYPE>.
 282
 283 =item B<DEB_BUILD_GNU_TYPE>
 284
 285 The GNU system type of the build machine.
 286
 287 =item B<DEB_BUILD_MULTIARCH>
 288
 289 The clarified GNU system type of the build machine, used for filesystem
 290 paths (since dpkg 1.16.0).
 291
 292 =item B<DEB_HOST_ARCH>
 293
 294 The Debian architecture of the host machine.
 295
 296 =item B<DEB_HOST_ARCH_ABI>
 297
 298 The Debian ABI name of the host machine (since dpkg 1.18.11).
 299
 300 =item B<DEB_HOST_ARCH_LIBC>
 301
 302 The Debian libc name of the host machine (since dpkg 1.18.11).
 303
 304 =item B<DEB_HOST_ARCH_OS>
 305
 306 The Debian system name of the host machine (since dpkg 1.13.2).
 307
 308 =item B<DEB_HOST_ARCH_CPU>
 309
 310 The Debian CPU name of the host machine (since dpkg 1.13.2).
 311
 312 =item B<DEB_HOST_ARCH_BITS>
 313
 314 The pointer size of the host machine (in bits; since dpkg 1.15.4).
 315
 316 =item B<DEB_HOST_ARCH_ENDIAN>
 317
 318 The endianness of the host machine (little / big; since dpkg 1.15.4).
 319
 320 =item B<DEB_HOST_GNU_CPU>
 321
 322 The GNU CPU part of B<DEB_HOST_GNU_TYPE>.
 323
 324 =item B<DEB_HOST_GNU_SYSTEM>
 325
 326 The GNU system part of B<DEB_HOST_GNU_TYPE>.
 327
 328 =item B<DEB_HOST_GNU_TYPE>
 329
 330 The GNU system type of the host machine.
 331
 332 =item B<DEB_HOST_MULTIARCH>
 333
 334 The clarified GNU system type of the host machine, used for filesystem
 335 paths (since dpkg 1.16.0).
 336
 337 =item B<DEB_TARGET_ARCH>
 338
 339 The Debian architecture of the target machine (since dpkg 1.17.14).
 340
 341 =item B<DEB_TARGET_ARCH_ABI>
 342
 343 The Debian ABI name of the target machine (since dpkg 1.18.11).
 344
 345 =item B<DEB_TARGET_ARCH_LIBC>
 346
 347 The Debian libc name of the target machine (since dpkg 1.18.11).
 348
 349 =item B<DEB_TARGET_ARCH_OS>
 350
 351 The Debian system name of the target machine (since dpkg 1.17.14).
 352
 353 =item B<DEB_TARGET_ARCH_CPU>
 354
 355 The Debian CPU name of the target machine (since dpkg 1.17.14).
 356
 357 =item B<DEB_TARGET_ARCH_BITS>
 358
 359 The pointer size of the target machine (in bits; since dpkg 1.17.14).
 360
 361 =item B<DEB_TARGET_ARCH_ENDIAN>
 362
 363 The endianness of the target machine (little / big; since dpkg 1.17.14).
 364
 365 =item B<DEB_TARGET_GNU_CPU>
 366
 367 The GNU CPU part of B<DEB_TARGET_GNU_TYPE> (since dpkg 1.17.14).
 368
 369 =item B<DEB_TARGET_GNU_SYSTEM>
 370
 371 The GNU system part of B<DEB_TARGET_GNU_TYPE> (since dpkg 1.17.14).
 372
 373 =item B<DEB_TARGET_GNU_TYPE>
 374
 375 The GNU system type of the target machine (since dpkg 1.17.14).
 376
 377 =item B<DEB_TARGET_MULTIARCH>
 378
 379 The clarified GNU system type of the target machine, used for filesystem
 380 paths (since dpkg 1.17.14).
 381
 382 =back
 383
 384 =head1 FILES
 385
 386 =head2 Architecture tables
 387
 388 All these files have to be present for B<dpkg-architecture> to
 389 work. Their location can be overridden at runtime with the environment
 390 variable B<DPKG_DATADIR>.
 391 These tables contain a format B<Version> pseudo-field on their first
 392 line to mark their format, so that parsers can check if they understand
 393 it, such as "# Version=1.0".
 394
 395 =over
 396
 397 =item I<%PKGDATADIR%/cputable>
 398
 399 Table of known CPU names and mapping to their GNU name.
 400 Format version 1.0 (since dpkg 1.13.2).
 401
 402 =item I<%PKGDATADIR%/ostable>
 403
 404 Table of known operating system names and mapping to their GNU name.
 405 Format version 2.0 (since dpkg 1.18.11).
 406
 407 =item I<%PKGDATADIR%/tupletable>
 408
 409 Mapping between Debian architecture tuples and Debian architecture
 410 names.
 411 Format version 1.0 (since dpkg 1.18.11).
 412
 413 =item I<%PKGDATADIR%/abitable>
 414
 415 Table of Debian architecture ABI attribute overrides.
 416 Format version 2.0 (since dpkg 1.18.11).
 417
 418 =back
 419
 420 =head2 Packaging support
 421
 422 =over
 423
 424 =item I<%PKGDATADIR%/architecture.mk>
 425
 426 Makefile snippet that properly sets and exports all the variables that
 427 B<dpkg-architecture> outputs (since dpkg 1.16.1).
 428
 429 =back
 430
 431 =head1 EXAMPLES
 432
 433 B<dpkg-buildpackage> accepts the B<-a> option and passes it to
 434 B<dpkg-architecture>. Other examples:
 435
 436 =over
 437
 438  CC=i386-gnu-gcc dpkg-architecture -c debian/rules build
 439
 440  eval $(dpkg-architecture -u)
 441
 442 =back
 443
 444 Check if the current or specified host architecture is equal to an
 445 architecture:
 446
 447 =over
 448
 449  dpkg-architecture -elinux-alpha
 450
 451  dpkg-architecture -amips -elinux-mips
 452
 453 =back
 454
 455 Check if the current or specified host architecture is a Linux system:
 456
 457 =over
 458
 459  dpkg-architecture -ilinux-any
 460
 461  dpkg-architecture -ai386 -ilinux-any
 462
 463 =back
 464
 465 =head2 Usage in debian/rules
 466
 467 The environment variables set by B<dpkg-architecture> are passed to
 468 I<debian/rules> as make variables (see make documentation). However,
 469 you should not rely on them, as this breaks manual invocation of the
 470 script. Instead, you should always initialize them using
 471 B<dpkg-architecture> with the B<-q> option. Here are some examples,
 472 which also show how you can improve the cross compilation support in your
 473 package:
 474
 475 Retrieving the GNU system type and forwarding it to ./configure:
 476
 477 =over
 478
 479  DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE)
 480  DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE)
 481  [...]
 482  ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE))
 483    confflags += --build=$(DEB_HOST_GNU_TYPE)
 484  else
 485    confflags += --build=$(DEB_BUILD_GNU_TYPE) \
 486                 --host=$(DEB_HOST_GNU_TYPE)
 487  endif
 488  [...]
 489  ./configure $(confflags)
 490
 491 =back
 492
 493 Doing something only for a specific architecture:
 494
 495 =over
 496
 497  DEB_HOST_ARCH ?= $(shell dpkg-architecture -qDEB_HOST_ARCH)
 498
 499  ifeq ($(DEB_HOST_ARCH),alpha)
 500    [...]
 501  endif
 502
 503 =back
 504
 505 or if you only need to check the CPU or OS type, use the
 506 B<DEB_HOST_ARCH_CPU> or B<DEB_HOST_ARCH_OS> variables.
 507
 508 Note that you can also rely on an external Makefile snippet to properly
 509 set all the variables that B<dpkg-architecture> can provide:
 510
 511 =over
 512
 513  include %PKGDATADIR%/architecture.mk
 514
 515  ifeq ($(DEB_HOST_ARCH),alpha)
 516    [...]
 517  endif
 518
 519 =back
 520
 521 In any case, you should never use B<dpkg --print-architecture> to get
 522 architecture information during a package build.
 523
 524 =head1 ENVIRONMENT
 525
 526 =over
 527
 528 =item B<DPKG_DATADIR>
 529
 530 If set, it will be used as the B<dpkg> data directory, where the
 531 architecture tables are located (since dpkg 1.14.17).
 532 Defaults to «%PKGDATADIR%».
 533
 534 =item B<DPKG_COLORS>
 535
 536 Sets the color mode (since dpkg 1.18.5).
 537 The currently accepted values are: B<auto> (default), B<always> and
 538 B<never>.
 539
 540 =item B<DPKG_NLS>
 541
 542 If set, it will be used to decide whether to activate Native Language Support,
 543 also known as internationalization (or i18n) support (since dpkg 1.19.0).
 544 The accepted values are: B<0> and B<1> (default).
 545
 546 =back
 547
 548 =head1 NOTES
 549
 550 All long command and option names available only since dpkg 1.17.17.
 551
 552 =head1 SEE ALSO
 553
 554 L<dpkg-buildpackage(1)>.