dpkg-architecture(1): drop old info and document architecture.mk

The backwards compatibility section contains information which is no
longer relevant since dpkg-architecture has been available for ages now.
Drop all the samples that were still using dpkg --print-architecture.

On the other hand, add a reference to /usr/share/dpkg/architecture.mk
since it can be used to properly retrieve all the variables exported
by dpkg-architecture.

Reported-by: Niels Thykier <niels@thykier.net>

debian/changelog

@@ -87,6 +87,8 @@ dpkg (1.16.2) UNRELEASED; urgency=low
   * Fix description of Multi-Arch in deb-control(5). Closes: #654453
     Thanks to Jakub Wilk for spotting the mistake.
   * Drop misleading spaces in deb-symbols(5) in the format description.
+  * Clean up dpkg-architecture(1) dropping useless information and
+    adding a reference to /usr/share/dpkg/architecture.mk.
 
   [ Jonathan Nieder ]
   * Bump po4a version in Build-Depends to 0.41, since earlier versions do

man/dpkg-architecture.1

@@ -1,4 +1,4 @@
-.TH dpkg\-architecture 1 "2011-08-14" "Debian Project" "dpkg utilities"
+.TH dpkg\-architecture 1 "2012-01-20" "Debian Project" "dpkg utilities"
 .SH "NAME"
 dpkg\-architecture \- set and determine the architecture for package building
 .
@@ -147,114 +147,53 @@ which also show how you can improve the cross compilation support in your
 package:
 .PP
 
-Instead of:
-.IP
-.nf
-ARCH=\`dpkg \-\-print\-architecture\`
-configure $(\s-1ARCH\s0)\-linux
-.fi
-.PP
-please use the following:
+Retrieving the GNU system type and forwarding it to ./configure:
 .IP
 .nf
 \&\s-1DEB_BUILD_GNU_TYPE\s0 := $(shell dpkg\-architecture \-qDEB_BUILD_GNU_TYPE)
 \&\s-1DEB_HOST_GNU_TYPE\s0 := $(shell dpkg\-architecture \-qDEB_HOST_GNU_TYPE)
-
+[...]
 configure \-\-build=$(\s-1DEB_BUILD_GNU_TYPE\s0) \-\-host=$(\s-1DEB_HOST_GNU_TYPE\s0)
 .fi
 .PP
 
-Instead of:
-.IP
-.nf
-ARCH=\`dpkg \-\-print\-architecture\`
-ifeq ($(\s-1ARCH\s0),alpha)
-  ...
-endif
-.fi
-.PP
-please use:
+Doing something only for a specific architecture:
 .IP
 .nf
 \&\s-1DEB_HOST_ARCH\s0 := $(shell dpkg\-architecture \-qDEB_HOST_ARCH)
 
 ifeq ($(\s-1DEB_HOST_ARCH\s0),alpha)
-  ...
+  [...]
 endif
 .fi
 .PP
 or if you only need to check the CPU or OS type, use the DEB_HOST_ARCH_CPU
 or DEB_HOST_ARCH_OS variables.
 .PP
-In general, calling dpkg in the rules file to get architecture information
-is deprecated (unless you want to provide backward compatibility, see below).
-Especially the \-\-print\-architecture option is unreliable since we have
-Debian architectures which don't equal a processor name.
-.
-.SH "BACKWARD COMPATIBILITY"
-The DEB_*_ARCH_BITS and DEB_*_ARCH_ENDIAN variables were introduced
-in dpkg\-dev 1.15.4. Using them in \fIdebian/rules\fR thus requires a
-build-dependency on dpkg\-dev (>= 1.15.4).
-.PP
-The DEB_HOST_ARCH_CPU and DEB_HOST_ARCH_OS variables were introduced
-in dpkg\-dev 1.13.2. Before this \fIdebian/rules\fR files tended to check
-the values of the DEB_HOST_GNU_CPU or DEB_HOST_GNU_TYPE variables which
-have been subject to change.
-.PP
-Where \fIdebian/rules\fR files check these variables to decide how or what
-to compile, this should be updated to use the new variables and values.
-You may wish to retain backwards compatibility with older version of
-dpkg\-dev by using the following code:
+Note that you can also rely on an external Makefile snippet to properly
+set all the variables that \fBdpkg\-architecture\fP can provide:
 .IP
 .nf
-DEB_HOST_ARCH_CPU := $(shell dpkg\-architecture \-qDEB_HOST_ARCH_CPU 2>/dev/null)
-DEB_HOST_ARCH_OS := $(shell dpkg\-architecture \-qDEB_HOST_ARCH_OS 2>/dev/null)
+include /usr/share/dpkg/architecture.mk
 
-# Take account of old dpkg\-architecture output.
-ifeq ($(DEB_HOST_ARCH_CPU),)
-  DEB_HOST_ARCH_CPU := $(shell dpkg\-architecture \-qDEB_HOST_GNU_CPU)
-  ifeq ($(DEB_HOST_ARCH_CPU),x86_64)
-    DEB_HOST_ARCH_CPU := amd64
-  endif
-endif
-ifeq ($(DEB_HOST_ARCH_OS),)
-  DEB_HOST_ARCH_OS := $(subst \-gnu,,$(shell dpkg\-architecture \-qDEB_HOST_GNU_SYSTEM))
-  ifeq ($(DEB_HOST_ARCH_OS),gnu)
-    DEB_HOST_ARCH_OS := hurd
-  endif
+ifeq ($(\s-1DEB_HOST_ARCH\s0),alpha)
+  [...]
 endif
 .fi
 .PP
-And similarly for DEB_BUILD_ARCH_CPU and DEB_BUILD_ARCH_OS.
-.PP
-If you still wish to support versions of dpkg\-dev that did not include
-\fBdpkg\-architecture\fR, the following does the job:
-.IP
-.nf
-\&\s-1DEB_BUILD_ARCH\s0 := $(shell dpkg \-\-print\-architecture)
-\&\s-1DEB_BUILD_GNU_CPU\s0 := $(patsubst hurd\-%,%,$(\s-1DEB_BUILD_ARCH\s0))
-ifeq ($(filter\-out hurd\-%,$(\s-1DEB_BUILD_ARCH\s0)),)
-  \s-1DEB_BUILD_GNU_SYSTEM\s0 := gnu
-else
-  \s-1DEB_BUILD_GNU_SYSTEM\s0 := linux\-gnu
-endif
-DEB_BUILD_GNU_TYPE=$(\s-1DEB_BUILD_GNU_CPU\s0)\-$(\s-1DEB_BUILD_GNU_SYSTEM\s0)
-
-\&\s-1DEB_HOST_ARCH\s0 := $(\s-1DEB_BUILD_ARCH\s0)
-\&\s-1DEB_HOST_GNU_CPU\s0 := $(\s-1DEB_BUILD_GNU_CPU\s0)
-\&\s-1DEB_HOST_GNU_SYSTEM\s0 := $(\s-1DEB_BUILD_GNU_SYSTEM\s0)
-\&\s-1DEB_HOST_GNU_TYPE\s0 := $(\s-1DEB_BUILD_GNU_TYPE\s0)
-.fi
+In any case, you should never use \fBdpkg \-\-print\-architecture\fP to get
+architecture information during a package build.
+.
+.SH "BACKWARD COMPATIBILITY"
+The /usr/share/dpkg/architecture.mk Makefile snippet is provided by
+dpkg\-dev since version 1.16.1.
 .PP
-Put a subset of these lines at the top of your debian/rules file; these
-default values will be overwritten if dpkg\-architecture is used.
+The DEB_*_ARCH_BITS and DEB_*_ARCH_ENDIAN variables were introduced
+in dpkg\-dev 1.15.4. Using them in \fIdebian/rules\fR thus requires a
+build-dependency on dpkg\-dev (>= 1.15.4).
 .PP
-You don't need the full set. Choose a consistent set which contains the
-values you use in the rules file. For example, if you only need the host
-Debian architecture, `DEB_HOST_ARCH=\`dpkg \-\-print\-architecture\`'
-is sufficient (this is indeed the Debian architecture of the build machine,
-but remember that we are only trying to be backward compatible with native
-compilation).
+The DEB_HOST_ARCH_CPU and DEB_HOST_ARCH_OS variables were introduced
+in dpkg\-dev 1.13.2.
 .PP
 The \fB\-e\fP and \fB\-i\fP options were only introduced in relatively recent
 versions of \fBdpkg\-architecture\fR (since dpkg 1.13.13).