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