Document the Built-Using field

Thanks to Ansgar Burchardt <ansgar@debian.org>.
Closes: #641153
[jrnieder@gmail.com: with spelling fixes from Jakub Wilk]

diff --git a/policy.sgml b/policy.sgml
index 52dbb26aabe2dc7a8444aa07ff961154b65de073..aa42b5d078c84b822aa89a1b04eeb7b931713432 100644 (file)
--- 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>