Adding upstream version 1.22.4.upstream/1.22.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 568 insertions, 0 deletions

diff --git a/man/dpkg-architecture.pod b/man/dpkg-architecture.pod
new file mode 100644
index 0000000..cb2f362
--- /dev/null
+++ b/man/dpkg-architecture.pod
@@ -0,0 +1,568 @@
+# dpkg manual page - dpkg-architecture(1)
+#
+# Copyright © 2005 Marcus Brinkmann <brinkmd@debian.org>
+# Copyright © 2005 Scott James Remnant <scott@netsplit.com>
+# Copyright © 2006-2015 Guillem Jover <guillem@debian.org>
+# Copyright © 2009-2012 Raphaël Hertzog <hertzog@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dpkg-architecture - set and determine the architecture for package building
+
+=head1 SYNOPSIS
+
+B<dpkg-architecture>
+[I<option>...] [I<command>]
+
+=head1 DESCRIPTION
+
+B<dpkg-architecture>
+provides a facility to determine and set the build and
+host architecture for package building.
+
+The build architecture is always determined by either the B<DEB_BUILD_ARCH>
+variable if set (and B<--force> not being specified) or by an external call to
+L<dpkg(1)>, and cannot be set at the command line.
+
+You can specify the host architecture by providing one or both of the options
+B<--host-arch> and B<--host-type>, otherwise the B<DEB_HOST_ARCH> variable
+is used if set (and B<--force> not being specified).
+The default is
+determined by an external call to L<gcc(1)>,
+or the same as the build architecture if B<CC> or gcc are both not
+available.
+One out of B<--host-arch> and B<--host-type> is
+sufficient, the value of the
+other will be set to a usable default.
+Indeed, it is often better to only
+specify one, because B<dpkg-architecture> will warn you if your choice
+does not match the default.
+
+=head1 COMMANDS
+
+=over
+
+=item B<-l>, B<--list>
+
+Print the environment variables, one each line, in the format
+I<VARIABLE=value>.
+This is the default action.
+
+=item B<-e>, B<--equal> I<architecture>
+
+Check for equality of architecture (since dpkg 1.13.13).
+It compares the current or specified Debian host architecture against
+I<architecture>, to check if they are equal.
+This action will not expand the architecture wildcards.
+Command finishes with an exit status of 0 if matched, 1 if not matched.
+
+=item B<-i>, B<--is> I<architecture-wildcard>
+
+Check for identity of architecture (since dpkg 1.13.13).
+It compares the current or specified Debian host architecture against
+I<architecture-wildcard> after having expanded it as an architecture
+wildcard, to check if they match.
+Command finishes with an exit status of 0 if matched, 1 if not matched.
+
+=item B<-q>, B<--query> I<variable-name>
+
+Print the value of a single variable.
+
+=item B<-s>, B<--print-set>
+
+Print an export command.
+This can be used to set the environment variables
+using the POSIX shell or make B<eval>, depending on the output format.
+
+=item B<-u>, B<--print-unset>
+
+Print a similar command to B<--print-set> but to unset all variables.
+
+=item B<-c>, B<--command> I<command-string>
+
+Execute a I<command-string> in an environment which has all variables
+set to the determined value.
+
+If the I<command-string> contains shell metacharacters, then it will be
+invoked through the system bourne shell.
+
+=item B<-L>, B<--list-known>
+
+Print a list of valid architecture names.
+Possibly restricted by one or more of the matching options
+B<--match-wildcard>, B<--match-bits> or B<--match-endian>
+(since dpkg 1.17.14).
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 OPTIONS
+
+=over
+
+=item B<-a>, B<--host-arch> I<architecture>
+
+Set the host Debian architecture.
+
+=item B<-t>, B<--host-type> I<gnu-system-type>
+
+Set the host GNU system type.
+
+=item B<-A>, B<--target-arch> I<architecture>
+
+Set the target Debian architecture (since dpkg 1.17.14).
+
+=item B<-T>, B<--target-type> I<gnu-system-type>
+
+Set the target GNU system type (since dpkg 1.17.14).
+
+=item B<-W>, B<--match-wildcard> I<architecture-wildcard>
+
+Restrict the architectures listed by B<--list-known> to ones matching
+the specified architecture wildcard (since dpkg 1.17.14).
+
+=item B<-B>, B<--match-bits> I<architecture-bits>
+
+Restrict the architectures listed by B<--list-known> to ones with the
+specified CPU bits (since dpkg 1.17.14).
+Either B<32> or B<64>.
+
+=item B<-E>, B<--match-endian> I<architecture-endianness>
+
+Restrict the architectures listed by B<--list-known> to ones with the
+specified endianness (since dpkg 1.17.14).
+Either B<little> or B<big>.
+
+=item B<--print-format> I<format>
+
+Sets the output format for B<--print-set> and B<--print-unset>
+(since dpkg 1.20.6), to either B<shell> (default) or B<make>.
+
+=item B<-f>, B<--force>
+
+Values set by existing environment variables with the same name as used by
+the scripts are honored (i.e. used by B<dpkg-architecture>), except if
+this force flag is present.
+This allows the user
+to override a value even when the call to B<dpkg-architecture> is buried
+in some other script (for example L<dpkg-buildpackage(1)>).
+
+=back
+
+=head1 TERMS
+
+=over
+
+=item build machine
+
+The machine the package is built on.
+
+=item host machine
+
+The machine the package is built for.
+
+=item target machine
+
+The machine the compiler is building for, or the emulator will run code for.
+This is only needed when building a cross-toolchain (or emulator), one that
+will be built on the build architecture, to be run on the host architecture,
+and to build (or run emulated) code for the target architecture.
+
+=item Debian architecture
+
+The Debian architecture string, which specifies the binary tree in the
+FTP archive.
+Examples: i386, sparc, hurd-i386.
+
+=item Debian architecture tuple
+
+A Debian architecture tuple is the fully qualified architecture with all its
+components spelled out.
+This differs with Debian architectures in that at least the I<cpu>
+component does not embed the I<abi>.
+The current tuple has the form I<abi>-I<libc>-I<os>-I<cpu>.
+Examples: base-gnu-linux-amd64, eabihf-musl-linux-arm.
+
+=item Debian architecture wildcard
+
+A Debian architecture wildcard is a special architecture string that will
+match any real architecture being part of it.
+The general form is a Debian architecture tuple with four or less elements,
+and with at least one of them being B<any>.
+Missing elements of the tuple are prefixed implicitly as B<any>, and thus
+the following pairs are equivalent:
+
+=over
+
+=item B<any>-B<any>-B<any>-B<any> = B<any>
+
+=item B<any>-B<any>-I<os>-B<any> = I<os>-B<any>
+
+=item B<any>-I<libc>-B<any>-B<any> = I<libc>-B<any>-B<any>
+
+=back
+
+Examples: linux-any, any-i386, hurd-any, eabi-any-any-arm,
+musl-any-any.
+
+=item GNU system type
+
+An architecture specification string consisting of two parts separated by
+a hyphen: cpu and system.
+Examples: i586-linux-gnu, sparc-linux-gnu, i686-gnu, x86_64-netbsd.
+
+=item multiarch triplet
+
+The clarified GNU system type, used for filesystem paths.
+This triplet does not change even when the baseline ISA gets bumped,
+so that the resulting paths are stable over time.
+The only current difference with the GNU system type is that the CPU part
+for i386 based systems is always i386.
+Examples: i386-linux-gnu, x86_64-linux-gnu.
+Example paths: /lib/powerpc64le-linux-gnu/, /usr/lib/i386-kfreebsd-gnu/.
+
+=back
+
+=head1 VARIABLES
+
+The following variables are read from the environment (unless B<--force>
+has been specified) and set by B<dpkg-architecture> (see the B<TERMS>
+section for a description of the naming scheme):
+
+=over
+
+=item B<DEB_BUILD_ARCH>
+
+The Debian architecture of the build machine.
+
+=item B<DEB_BUILD_ARCH_ABI>
+
+The Debian ABI name of the build machine (since dpkg 1.18.11).
+
+=item B<DEB_BUILD_ARCH_LIBC>
+
+The Debian libc name of the build machine (since dpkg 1.18.11).
+
+=item B<DEB_BUILD_ARCH_OS>
+
+The Debian system name of the build machine (since dpkg 1.13.2).
+
+=item B<DEB_BUILD_ARCH_CPU>
+
+The Debian CPU name of the build machine (since dpkg 1.13.2).
+
+=item B<DEB_BUILD_ARCH_BITS>
+
+The pointer size of the build machine (in bits; since dpkg 1.15.4).
+
+=item B<DEB_BUILD_ARCH_ENDIAN>
+
+The endianness of the build machine (little / big; since dpkg 1.15.4).
+
+=item B<DEB_BUILD_GNU_CPU>
+
+The GNU CPU part of B<DEB_BUILD_GNU_TYPE>.
+
+=item B<DEB_BUILD_GNU_SYSTEM>
+
+The GNU system part of B<DEB_BUILD_GNU_TYPE>.
+
+=item B<DEB_BUILD_GNU_TYPE>
+
+The GNU system type of the build machine.
+
+=item B<DEB_BUILD_MULTIARCH>
+
+The clarified GNU system type of the build machine, used for filesystem
+paths (since dpkg 1.16.0).
+
+=item B<DEB_HOST_ARCH>
+
+The Debian architecture of the host machine.
+
+=item B<DEB_HOST_ARCH_ABI>
+
+The Debian ABI name of the host machine (since dpkg 1.18.11).
+
+=item B<DEB_HOST_ARCH_LIBC>
+
+The Debian libc name of the host machine (since dpkg 1.18.11).
+
+=item B<DEB_HOST_ARCH_OS>
+
+The Debian system name of the host machine (since dpkg 1.13.2).
+
+=item B<DEB_HOST_ARCH_CPU>
+
+The Debian CPU name of the host machine (since dpkg 1.13.2).
+
+=item B<DEB_HOST_ARCH_BITS>
+
+The pointer size of the host machine (in bits; since dpkg 1.15.4).
+
+=item B<DEB_HOST_ARCH_ENDIAN>
+
+The endianness of the host machine (little / big; since dpkg 1.15.4).
+
+=item B<DEB_HOST_GNU_CPU>
+
+The GNU CPU part of B<DEB_HOST_GNU_TYPE>.
+
+=item B<DEB_HOST_GNU_SYSTEM>
+
+The GNU system part of B<DEB_HOST_GNU_TYPE>.
+
+=item B<DEB_HOST_GNU_TYPE>
+
+The GNU system type of the host machine.
+
+=item B<DEB_HOST_MULTIARCH>
+
+The clarified GNU system type of the host machine, used for filesystem
+paths (since dpkg 1.16.0).
+
+=item B<DEB_TARGET_ARCH>
+
+The Debian architecture of the target machine (since dpkg 1.17.14).
+
+=item B<DEB_TARGET_ARCH_ABI>
+
+The Debian ABI name of the target machine (since dpkg 1.18.11).
+
+=item B<DEB_TARGET_ARCH_LIBC>
+
+The Debian libc name of the target machine (since dpkg 1.18.11).
+
+=item B<DEB_TARGET_ARCH_OS>
+
+The Debian system name of the target machine (since dpkg 1.17.14).
+
+=item B<DEB_TARGET_ARCH_CPU>
+
+The Debian CPU name of the target machine (since dpkg 1.17.14).
+
+=item B<DEB_TARGET_ARCH_BITS>
+
+The pointer size of the target machine (in bits; since dpkg 1.17.14).
+
+=item B<DEB_TARGET_ARCH_ENDIAN>
+
+The endianness of the target machine (little / big; since dpkg 1.17.14).
+
+=item B<DEB_TARGET_GNU_CPU>
+
+The GNU CPU part of B<DEB_TARGET_GNU_TYPE> (since dpkg 1.17.14).
+
+=item B<DEB_TARGET_GNU_SYSTEM>
+
+The GNU system part of B<DEB_TARGET_GNU_TYPE> (since dpkg 1.17.14).
+
+=item B<DEB_TARGET_GNU_TYPE>
+
+The GNU system type of the target machine (since dpkg 1.17.14).
+
+=item B<DEB_TARGET_MULTIARCH>
+
+The clarified GNU system type of the target machine, used for filesystem
+paths (since dpkg 1.17.14).
+
+=back
+
+=head1 FILES
+
+=head2 Architecture tables
+
+All these files have to be present for B<dpkg-architecture> to
+work.
+Their location can be overridden at runtime with the environment
+variable B<DPKG_DATADIR>.
+These tables contain a format B<Version> pseudo-field on their first
+line to mark their format, so that parsers can check if they understand
+it, such as "# Version=1.0".
+
+=over
+
+=item I<%PKGDATADIR%/cputable>
+
+Table of known CPU names and mapping to their GNU name.
+Format version 1.0 (since dpkg 1.13.2).
+
+=item I<%PKGDATADIR%/ostable>
+
+Table of known operating system names and mapping to their GNU name.
+Format version 2.0 (since dpkg 1.18.11).
+
+=item I<%PKGDATADIR%/tupletable>
+
+Mapping between Debian architecture tuples and Debian architecture
+names.
+Format version 1.0 (since dpkg 1.18.11).
+
+=item I<%PKGDATADIR%/abitable>
+
+Table of Debian architecture ABI attribute overrides.
+Format version 2.0 (since dpkg 1.18.11).
+
+=back
+
+=head2 Packaging support
+
+=over
+
+=item I<%PKGDATADIR%/architecture.mk>
+
+Makefile snippet that properly sets and exports all the variables that
+B<dpkg-architecture> outputs (since dpkg 1.16.1).
+
+=back
+
+=head1 EXAMPLES
+
+B<dpkg-buildpackage> accepts the B<-a> option and passes it to
+B<dpkg-architecture>.
+Other examples:
+
+=over
+
+ CC=i386-gnu-gcc dpkg-architecture -c debian/rules build
+
+ eval $(dpkg-architecture -u)
+
+=back
+
+Check if the current or specified host architecture is equal to an
+architecture:
+
+=over
+
+ dpkg-architecture -elinux-alpha
+
+ dpkg-architecture -amips -elinux-mips
+
+=back
+
+Check if the current or specified host architecture is a Linux system:
+
+=over
+
+ dpkg-architecture -ilinux-any
+
+ dpkg-architecture -ai386 -ilinux-any
+
+=back
+
+=head2 Usage in debian/rules
+
+The environment variables set by B<dpkg-architecture> are passed to
+I<debian/rules> as make variables (see make documentation).
+However,
+you should not rely on them, as this breaks manual invocation of the
+script.
+Instead, you should always initialize them using
+B<dpkg-architecture> with the B<-q> option.
+Here are some examples,
+which also show how you can improve the cross compilation support in your
+package:
+
+Retrieving the GNU system type and forwarding it to ./configure:
+
+=over
+
+ DEB_BUILD_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_BUILD_GNU_TYPE)
+ DEB_HOST_GNU_TYPE ?= $(shell dpkg-architecture -qDEB_HOST_GNU_TYPE)
+ [...]
+ ifeq ($(DEB_BUILD_GNU_TYPE), $(DEB_HOST_GNU_TYPE))
+   confflags += --build=$(DEB_HOST_GNU_TYPE)
+ else
+   confflags += --build=$(DEB_BUILD_GNU_TYPE) \
+                --host=$(DEB_HOST_GNU_TYPE)
+ endif
+ [...]
+ ./configure $(confflags)
+
+=back
+
+Doing something only for a specific architecture:
+
+=over
+
+ DEB_HOST_ARCH ?= $(shell dpkg-architecture -qDEB_HOST_ARCH)
+
+ ifeq ($(DEB_HOST_ARCH),alpha)
+   [...]
+ endif
+
+=back
+
+or if you only need to check the CPU or OS type, use the
+B<DEB_HOST_ARCH_CPU> or B<DEB_HOST_ARCH_OS> variables.
+
+Note that you can also rely on an external Makefile snippet to properly
+set all the variables that B<dpkg-architecture> can provide:
+
+=over
+
+ include %PKGDATADIR%/architecture.mk
+
+ ifeq ($(DEB_HOST_ARCH),alpha)
+   [...]
+ endif
+
+=back
+
+In any case, you should never use B<dpkg --print-architecture> to get
+architecture information during a package build.
+
+=head1 ENVIRONMENT
+
+=over
+
+=item B<DPKG_DATADIR>
+
+If set, it will be used as the B<dpkg> data directory, where the
+architecture tables are located (since dpkg 1.14.17).
+Defaults to «%PKGDATADIR%».
+
+=item B<DPKG_COLORS>
+
+Sets the color mode (since dpkg 1.18.5).
+The currently accepted values are: B<auto> (default), B<always> and
+B<never>.
+
+=item B<DPKG_NLS>
+
+If set, it will be used to decide whether to activate Native Language Support,
+also known as internationalization (or i18n) support (since dpkg 1.19.0).
+The accepted values are: B<0> and B<1> (default).
+
+=back
+
+=head1 NOTES
+
+All long command and option names available only since dpkg 1.17.17.
+
+=head1 SEE ALSO
+
+L<dpkg-buildpackage(1)>.