From 54b893df3f199ea7280fa58ed2ae3ad2fd8ebc33 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Thu, 12 Aug 2010 11:23:22 -0700
Subject: [PATCH] Better define build architecture and host architecture

* Be more verbose in defining the build architecture and the host
  architecture and consistently refer to architecture rather than
  machine.  (Closes: #591857)
---
 debian/changelog |  3 +++
 policy.sgml      | 27 +++++++++++++++++----------
 2 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 031152c..743a18e 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,9 @@ debian-policy (3.9.2.0) UNRELEASED; urgency=low
     Seconded: Charles Plessy <plessy@debian.org>
     Seconded: Raphaël Hertzog <hertzog@debian.org>
     Closes: #459868, #581011
+  * Be more verbose in defining the build architecture and the host
+    architecture and consistently refer to architecture rather than
+    machine.  (Closes: #591857)
   * Correct the name of the Filesystem Hierarchy Standard in the package
     description.  Patch from Christoph Anton Mitterer.  (Closes: #590696)
 
diff --git a/policy.sgml b/policy.sgml
index d6c63f6..0624290 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2084,14 +2084,21 @@
 
 	<p>
 	  The architectures we build on and build for are determined
-	  by <prgn>make</prgn> variables using the utility
-	  <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
-	  You can determine the
-	  Debian architecture and the GNU style architecture
-	  specification string for the build machine (the machine type
-	  we are building on) as well as for the host machine (the
-	  machine type we are building for).  Here is a list of
-	  supported <prgn>make</prgn> variables:
+	  by <prgn>make</prgn> variables using the
+	  utility <qref id="pkg-dpkg-architecture"><prgn>dpkg-architecture</prgn></qref>.
+	  You can determine the Debian architecture and the GNU style
+	  architecture specification string for the build architecture as
+	  well as for the host architecture.  The build architecture is
+	  the architecture on which <file>debian/rules</file> is run and
+	  the package build is performed.  The host architecture is the
+	  architecture on which the resulting package will be installed
+	  and run.  These are normally the same, but may be different in
+	  the case of cross-compilation (building packages for one
+	  architecture on machines of a different architecture).
+	</p>
+
+	<p>
+	  Here is a list of supported <prgn>make</prgn> variables:
 	  <list compact="compact">
 	    <item>
 		<tt>DEB_*_ARCH</tt> (the Debian architecture)
@@ -2115,8 +2122,8 @@
 		<tt>DEB_*_GNU_TYPE</tt>)
 	  </list>
 	  where <tt>*</tt> is either <tt>BUILD</tt> for specification of
-	  the build machine or <tt>HOST</tt> for specification of the
-	  host machine.
+	  the build architecture or <tt>HOST</tt> for specification of the
+	  host architecture.
 	</p>
 
 	<p>
-- 
2.39.2