Bug#641153: document Built-Using field for binary packages

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Jakub Wilk wrote:
> * Charles Plessy <plessy@debian.org>, 2011-12-30, 15:39:

>>+	  A <tt>Build-Using</tt> field must list the corresponding source
>>+	  package for any such binary package incorporated during the build
>
> s/Build-/Built-/
>
>>+	    The archive software might reject packages that refer to
>>+	    non-existant sources.
>
> s/existant/existent/

Here's the same patch with the above fixes applied.  Sensible?

From: Charles Plessy <plessy@debian.org>
Date: Thu, 29 Dec 2011 20:23:19 +0100
Subject: Documents the Built-Using field.

Thanks to Ansgar Burchardt <ansgar@debian.org>.
Closes: #641153

[jrnieder@gmail.com: with spelling fixes from Jakub Wilk]
---
 policy.sgml |   52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/policy.sgml b/policy.sgml
index 52dbb26a..aa42b5d0 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2646,6 +2646,7 @@ Package: libc6
 	    <item><qref id="binarydeps"><tt>Depends</tt> et al</qref></item>
 	    <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+	    <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
 	  </list>
 	</p>
 
@@ -2701,6 +2702,7 @@ Package: libc6
 	    <item><qref id="f-Maintainer"><tt>Maintainer</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Description"><tt>Description</tt></qref> (mandatory)</item>
 	    <item><qref id="f-Homepage"><tt>Homepage</tt></qref></item>
+	    <item><qref id="built-using"><tt>Built-Using</tt></qref></item>
 	  </list>
 	</p>
       </sect>
@@ -4677,7 +4679,8 @@ Build-Depends: kernel-headers-2.2.10 [!hurd-i386],
 	</p>
 
 	<p>
-	  For binary relationship fields, the architecture restriction
+	  For binary relationship fields and the <tt>Built-Using</tt>
+	  field, the architecture restriction
 	  syntax is only supported in the source package control
 	  file <file>debian/control</file>.  When the corresponding binary
 	  package control file is generated, the relationship will either
@@ -5401,6 +5404,53 @@ Replaces: mail-transport-agent
 	  </taglist>
 	</p>
       </sect>
+
+      <sect id="built-using">
+	<heading>Additional source packages used to build the binary
+	  - <tt>Built-Using</tt>
+	</heading>
+
+	<p>
+	  Some binary packages incorporate parts of other packages when built
+	  but do not have to depend on those packages.  Examples include
+	  linking with static libraries or incorporating source code from
+	  another package during the build.  In this case, the source packages
+	  of those other packages are a required part of the complete source
+	  (the binary package is not reproducible without them).
+	</p>
+
+	<p>
+	  A <tt>Built-Using</tt> field must list the corresponding source
+	  package for any such binary package incorporated during the build
+	  <footnote>
+	    <tt>Build-Depends</tt> in the source package is not adequate since
+	    it (rightfully) does not document the exact version used in the
+	    build.
+	  </footnote>,
+	  including an "exactly equal" ("=") version relation on the version
+	  that was used to build that binary package<footnote>
+	    The archive software might reject packages that refer to
+	    non-existent sources.
+	  </footnote>.
+	</p>
+
+	<p>
+	  A package using the source code from the gcc-4.6-source
+	  binary package built from the gcc-4.6 source package would
+	  have this field in its control file:
+	  <example compact="compact">
+Built-Using: gcc-4.6 (= 4.6.0-11)
+	  </example>
+	</p>
+
+	<p>
+	  A package including binaries from grub2 and loadlin would
+	  have this field in its control file:
+	  <example compact="compact">
+Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
+	  </example>
+	</p>
+      </sect>
     </chapt>
 
 
-- 
1.7.10.4