Bug#641153: document Built-Using field for binary packages
Le Sat, Sep 10, 2011 at 10:44:49PM +0200, Ansgar Burchardt a écrit :
>
> some months ago support for the Built-Using field was added to the
> archive software. It is used by binary packages to refer to additional
> source packages that were used during the build and need to stay in the
> archive to have the full source available.
>
> I would like to have this field documented in policy, a first patch is
> attached.
Dear Ansgar,
thanks for documenting Built-Using in the Policy. I have a couple of
comments about your patch.
@@ -3061,7 +3061,8 @@ Package: libc6
<tt>Depends</tt>, <tt>Pre-Depends</tt>,
<tt>Recommends</tt>, <tt>Suggests</tt>,
<tt>Breaks</tt>, <tt>Conflicts</tt>,
- <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>
+ <tt>Provides</tt>, <tt>Replaces</tt>, <tt>Enhances</tt>,
+ <tt>Built-Using</tt>
</heading>
This adds Built-Using in §5.6.10 (“Package interrelationship fields: Depends,
Pre-Depends, Recommends, Suggests, Breaks, Conflicts, Provides, Replaces,
Enhances”). In Policy's chapter 5, the fields in that list are documented to
be present in source package control files (§5.2) and binary package control
files (§5.3). However, dpkg-source does not allow the field in source package
control files (allowed => ALL_PKG, see scripts/Dpkg/Control/Fields.pm).
I propose to list Built-Using separately from the ‘Depends et al’ fields in
Policy's chapter 5 section about binary package control files (§5.3).
<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>Built-Using</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
This adds Built-Using in the second paragraph of §7.1, which would allow the following:
Built-Using: foo (= 4.4) | bar (= 8.7)
Since the only purpose of this paragraph is to allow to list pipe-separated
alternatives, I propose to not add Built-Using to that paragraph, as in my
undersanding it is not expected to list alternatives.
@@ -5317,6 +5319,45 @@ Replaces: mail-transport-agent
</sect1>
</sect>
+ <sect id="built-using">
+ <heading>Additional source packages used to build the binary
+ - <tt>Built-Using</tt>
+ </heading>
This would add the new section ‘Additional source packages used to build…’ as
§7.7, which would renumber the current §7.7 (‘Relationships between source and
binary…’). I think that the current practice in the policy is to add new sections
in chronological order rather than trying to group them by topic, in order to
preserve old links and references. I propose to move the section you added after
the current §7.7.
+ <p>
+ Additional source packages might be involved in creating a
+ binary package. These must be listed in
+ the <tt>Built-Using</tt> field to enable the archive
+ software to keep the full source code.
+ </p>
That part was very difficult to understand for me:
- Source packages build-depend on binary packages, and therefore
directly ‘involve’ binary packages only, but
- Replacing ‘source’ by ‘binary’ suggests that Built-Using field is mandatory in
the sense of §5.3, and that it would list all the packages and their
dependancies pulled throught Build-Depends, which is not the case.
I got confused a long time about how to use the field, and propose to rephrase
the paragraph above using some elements from from deb-control(5) and the
minutes of the FTP team meeting. I kept the ‘must’, as it derives from
a license requirement.
Some binary packages incorporate material derived from source or compiled
code distributed in other source packages, without depending on a corresponding
binary package. This field must be used to list these source packages and
their version number in order to follow requirements of licenses like the GNU
GPL, as it will indicate to the archive maintenance software that these extra
source packages must be kept whilst this binary package is maintained.
+ <p>
+ For every source package, the version used must be
+ specified using an "exactly equal" ("=") relation.
+ <footnote>
+ The archive software might reject packages that refer to
+ non-existant sources.
+ </footnote>
+ </p>
To be consistent with the structure of chapter 7, the description of syntax
could be moved to §7.1, for instance by changing its third paragraph:
All of the fields except for Provides may restrict their applicability to
particular versions of each named package. Packages listed in the
<tt>Built-Using</tt> must be restricted on an exactly equal version.<footnote>
The archive maintenance software is likely to refuse an upload which declares
a <tt>Built-Using</tt> relationship which cannot be satisfied within the
archive</footnote>.
Also, §7.1 specifies differently the architecture restrictions for build
relationship fields (Build-Depends, Build-Depends-Indep, Build-Conflicts and
Build-Conflicts-Indep) and binary relationship fields. According to what is
expected for Built-Using, §7.1 could be updated as well.
Again, thank you very much for sending your patch. At your convenience, I can
prepare an updated patch according to how the discussion follows.
Have a nice day,
--
Charles Plessy
Tsurumi, Kanagawa, Japan
Reply to: