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

[Russ Allbery <rra@debian.org>]

One basic question about this before I dive into wording: why is the
Build-Depends field not adequate?

Ansgar Burchardt <ansgar@debian.org> writes:

> A try at this:

>   Some binary packages incorporate material derived from source
>   or compiled code derived from other source packages.  In this case
>   this field must be used to list all other source packages necessary
>   to obtain the full corresponding source code.
>   <footnote (or not?)>
>     It indicates to the archive software to keep the listed source
> packages around until the binary package disappears.
>   </footnote>

I think this is the right idea.  How about:

    <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>

Why are we requiring source packages be listed in Build-Using instead of
binary packages?  The archive software should be able to draw similar
conclusions from a field listing the binary packages that were
incorporated into the build, just by taking one additional step, and a
field listing binary packages is *much* easier to generate.

>> 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>.

> That's also fine with me, though I think having the restrictions for each
> field along with the field's description makes it easier to find them.

I'd rather keep it with Build-Using as well.

Angsar, there are a bunch of proposed changes on this thread.  Would you
be willing to take a shot at generating an updated patch, assuming that
the above looks okay?  Sorry about the delays in discussing this.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>