Bug#641153: document Built-Using field for binary packages
Dear all,
here is a proposed patch that uses a slimed version of the paragraphs proposed
by Russ (quoted below) and keeps the original examples. It documents the field
as new section, number 7.8, the last one of its chapter, because it introduces
a new type of relationship, from binary package to source package. This said,
I agree with Russ that a binary/binary relationship may be preferrable. For
instance, it might avoid rare corner cases when depending on a source package
that was binNMUed. This patch also lists Built-Using together with binary
relationship packages in the paragraph explaining how architecture restrictions
in source control files are used to produce binary control files.
Le Sat, Dec 24, 2011 at 10:37:16AM -0800, Russ Allbery a écrit :
>
> <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), but there is
> no other binary package control field to capture this relationship.
> Build-Depends in the source package is not adequate since it
> (rightfully) does not document the exact version used in the build.
> </p>
>
> <p>
> Therefore, in cases like this where a part of another package is
> incorporated into a binary package, the <tt>Build-Using</tt> field
> must list the corresponding source package for any such binary
> package incorporated during the build, including an "exactly equal"
> ("=") version relation on the version that was used to build that
> binary package.
> </p>
--
Charles Plessy
Tsurumi, Kanagawa, Japan
>From 9134f3e29dc8f3270896bb2906bbbdb2006b619a Mon Sep 17 00:00:00 2001
From: Charles Plessy <plessy@debian.org>
Date: Thu, 29 Dec 2011 20:23:19 +0100
Subject: [PATCH] Documents the Built-Using field.
Thanks to Ansgar Burchardt <ansgar@debian.org>.
Closes: #641153
---
policy.sgml | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 51 insertions(+), 1 deletions(-)
diff --git a/policy.sgml b/policy.sgml
index 854fde6..e673341 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -2632,6 +2632,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>
@@ -2687,6 +2688,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>
@@ -4661,7 +4663,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
@@ -5385,6 +5388,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>Build-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-existant 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.7.3
Reply to: