From e917008ce295400781b8073bacb6e40162f99ce7 Mon Sep 17 00:00:00 2001
From: Johannes Schauer <josch@debian.org>
Date: Sun, 18 Sep 2016 09:09:12 +0200
Subject: [PATCH] Document Build-Depends-Arch and Build-Conflicts-Arch (closes:
 #823910)

---
 policy.sgml | 68 +++++++++++++++++++++++++++++--------------------------------
 1 file changed, 32 insertions(+), 36 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index 9cd182b..1b5ec35 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -505,8 +505,9 @@
 		  must not require or recommend a package outside
 		  of <em>main</em> for compilation or execution (thus, the
 		  package must not declare a "Pre-Depends", "Depends",
-		  "Recommends", "Build-Depends", or "Build-Depends-Indep"
-		  relationship on a non-<em>main</em> package),
+		  "Recommends", "Build-Depends", "Build-Depends-Indep",
+		  or "Build-Depends-Arch" relationship on a non-<em>main</em>
+		  package),
 	      </item>
 	      <item>
 		  must not be so buggy that we refuse to support them,
@@ -4747,7 +4748,8 @@ fi
         <p>
           In the <tt>Depends</tt>, <tt>Recommends</tt>,
           <tt>Suggests</tt>, <tt>Pre-Depends</tt>,
-          <tt>Build-Depends</tt> and <tt>Build-Depends-Indep</tt>
+          <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt> and
+	  <tt>Build-Depends-Arch</tt>
           control fields of the package, which declare
           dependencies on other packages, the package names listed may
           also include lists of alternative package names, separated
@@ -4815,7 +4817,8 @@ Depends: libc6 (>= 2.2.1), exim | mail-transport-agent
 	<p>
 	  For build relationship fields
 	  (<tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
-	  <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>), if
+	  <tt>Build-Depends-Arch</tt>, <tt>Build-Conflicts</tt>,
+	  <tt>Build-Conflicts-Indep</tt> and <tt>Build-Conflicts-Arch</tt>), if
 	  the current Debian host architecture is not in this list and
 	  there are no exclamation marks in the list, or it is in the list
 	  with a prepended exclamation mark, the package name and the
@@ -5306,7 +5309,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 	  <tt>Recommends</tt>, <tt>Suggests</tt>, <tt>Enhances</tt>,
 	  <tt>Pre-Depends</tt>, <tt>Breaks</tt>, <tt>Conflicts</tt>,
 	  <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
-	  <tt>Build-Conflicts</tt> and <tt>Build-Conflicts-Indep</tt>
+	  <tt>Build-Depends-Arch</tt>, <tt>Build-Conflicts</tt>,
+	  <tt>Build-Conflicts-Indep</tt> and <tt>Build-Conflicts-Arch</tt>
 	  may mention "virtual packages".
 	</p>
 
@@ -5500,7 +5504,8 @@ Replaces: mail-transport-agent
       <sect id="sourcebinarydeps">
 	<heading>Relationships between source and binary packages -
 	  <tt>Build-Depends</tt>, <tt>Build-Depends-Indep</tt>,
-	  <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt>
+	  <tt>Build-Depends-Arch</tt>, <tt>Build-Conflicts</tt>,
+	  <tt>Build-Conflicts-Indep</tt>, <tt>Build-Conflicts-Arch</tt>
 	</heading>
 
 	<p>
@@ -5511,8 +5516,9 @@ Replaces: mail-transport-agent
 
         <p>
           This is done using the <tt>Build-Depends</tt>,
-          <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts</tt> and
-          <tt>Build-Conflicts-Indep</tt> control fields.
+          <tt>Build-Depends-Indep</tt>, <tt>Build-Depends-Arch</tt>,
+	  <tt>Build-Conflicts</tt>, <tt>Build-Conflicts-Indep</tt> and
+	  <tt>Build-Conflicts-Arch</tt> control fields.
         </p>
 
         <p>
@@ -5523,41 +5529,31 @@ Replaces: mail-transport-agent
 	<p>
           The dependencies and conflicts they define must be satisfied
           (as defined earlier for binary packages) in order to invoke
-          the targets in <tt>debian/rules</tt>, as follows:<footnote>
-	    <p>
-	      There is no Build-Depends-Arch; this role is essentially
-	      met with Build-Depends.  Anyone building the
-	      <tt>build-indep</tt> and <tt>binary-indep</tt> targets is
-	      assumed to be building the whole package, and therefore
-	      installation of all build dependencies is required.
-	    </p>
-	    <p>
-	      The autobuilders use <tt>dpkg-buildpackage -B</tt>, which
-	      calls <tt>build</tt>, not <tt>build-arch</tt> since it does
-	      not yet know how to check for its existence, and
-	      <tt>binary-arch</tt>.  The purpose of the original split
-	      between <tt>Build-Depends</tt> and
-	      <tt>Build-Depends-Indep</tt> was so that the autobuilders
-	      wouldn't need to install extra packages needed only for the
-	      binary-indep targets.  But without a build-arch/build-indep
-	      split, this didn't work, since most of the work is done in
-	      the build target, not in the binary target.
-	    </p>
-	  </footnote>
+          the targets in <tt>debian/rules</tt>, as follows:
 	  <taglist>
-	    <tag><tt>clean</tt>, <tt>build-arch</tt>, and
-	      <tt>binary-arch</tt></tag>
+	    <tag><tt>clean</tt></tag>
 	    <item>
 	      Only the <tt>Build-Depends</tt> and <tt>Build-Conflicts</tt>
+	      fields must be satisfied when this target is invoked.
+	    </item>
+	    <tag><tt>build-arch</tt>, and <tt>binary-arch</tt></tag>
+	    <item>
+	      The <tt>Build-Depends</tt>, <tt>Build-Conflicts</tt>,
+	      <tt>Build-Depends-Arch</tt>, and <tt>Build-Conflicts-Arch</tt>
+	      fields must be satisfied when these targets are invoked.
+	    </item>
+	    <tag><tt>build-indep</tt>, and <tt>binary-indep</tt></tag>
+	    <item>
+	      The <tt>Build-Depends</tt>, <tt>Build-Conflicts</tt>,
+	      <tt>Build-Depends-Indep</tt>, and <tt>Build-Conflicts-Indep</tt>
 	      fields must be satisfied when these targets are invoked.
 	    </item>
-	    <tag><tt>build</tt>, <tt>build-indep</tt>, <tt>binary</tt>,
-	      and <tt>binary-indep</tt></tag>
+	    <tag><tt>build</tt> and <tt>binary</tt></tag>
 	    <item>
 	      The <tt>Build-Depends</tt>, <tt>Build-Conflicts</tt>,
-	      <tt>Build-Depends-Indep</tt>, and
-	      <tt>Build-Conflicts-Indep</tt> fields must be satisfied when
-	      these targets are invoked.
+	      <tt>Build-Depends-Indep</tt>, <tt>Build-Conflicts-Indep</tt>,
+	      <tt>Build-Depends-Arch</tt>, and <tt>Build-Conflicts-Arch</tt>
+	      fields must be satisfied when these targets are invoked.
 	    </item>
 	  </taglist>
 	</p>
-- 
2.9.3

