Bug#968226: Move documentation of Build-Depends alternative selection out of footnote
On Tue, Sep 20, 2022 at 07:17:17PM -0700, Russ Allbery wrote:
> Wouter Verhelst <wouter@debian.org> writes:
> > On Tue, Aug 11, 2020 at 10:05:42AM -0700, Russ Allbery wrote:
> >> Wouter Verhelst <wouter@debian.org> writes:
>
> >>> -policy: this is a question that has come up before
> >>> (https://lists.debian.org/debian-devel/2016/12/msg00470.html is
> >>> another example that springs to mind, but I'm pretty sure there are
> >>> more), so I think we should document in Policy that a) buildd only
> >>> looks at the first dependency in alternative build-dependencies, and
> >>> b) why this is the case.
>
> >> Policy already says:
>
> >> While Build-Depends, Build-Depends-Indep and Build-Depends-Arch
> >> permit the use of alternative dependencies, these are not normally
> >> used by the Debian autobuilders. To avoid inconsistency between
> >> repeated builds of a package, the autobuilders will default to
> >> selecting the first alternative, after reducing any
> >> architecture-specific restrictions for the build architecture in
> >> question. While this may limit the usefulness of alternatives in a
> >> single release, they can still be used to provide flexibility in
> >> building the same package across multiple distributions or
> >> releases, where a particular dependency is met by differently named
> >> packages.
>
> >> in 7.1. However, it's hidden in a footnote. Perhaps we should make it
> >> more prominant (and make it clear that it's normative), and tweak the
> >> wording.
>
> > Thanks, yeah, I missed that. I'll have a stab at a patch some time soon
> > (probably after debconf though)
>
> Here, a couple of years later, is a patch that does this, and which I
> think is ready for seconds.
Whoops, sorry; this completely slipped my mind.
> --
> Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
>
> From dd30c5455f13086dd0ef90bf6890c20729a1ac0b Mon Sep 17 00:00:00 2001
> From: Russ Allbery <rra@debian.org>
> Date: Tue, 20 Sep 2022 19:11:54 -0700
> Subject: [PATCH] Improve alternative build dependency discussion
>
> Alternatives in build dependencies are normally (except for
> backports) handled specially by autobuilders to try to maintain
> consistent builds. This was documented in Policy, but in a
> footnote that people often didn't see.
>
> Move this text into the main body of the discussion of build
> dependencies and reword it for additional clarity. Add a pointer
> to this discussion where alternative dependencies are introduced.
> ---
> policy/ch-relationships.rst | 41 ++++++++++++++++++++++---------------
> 1 file changed, 25 insertions(+), 16 deletions(-)
>
> diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> index 5074428..f177885 100644
> --- a/policy/ch-relationships.rst
> +++ b/policy/ch-relationships.rst
> @@ -15,7 +15,10 @@ control fields of the package, which declare dependencies on other
> packages, the package names listed may also include lists of alternative
> package names, separated by vertical bar (pipe) symbols ``|``. In such a
> case, that part of the dependency can be satisfied by any one of the
> -alternative packages. [#]_
> +alternative packages. (Alternative dependencies in ``Build-Depends``,
> +``Build-Depends-Indep``, and ``Build-Depends-Arch`` are normally used in a
> +restricted way. See :ref:`Relationships between source and binary packages
> +<s-sourcebinarydeps>` for more details.)
>
> All of the fields may restrict their applicability to particular versions
> of each named package. This is done in parentheses after each individual
> @@ -620,6 +623,27 @@ earlier for binary packages) in order to invoke the targets in
> ``Build-Conflicts-Arch`` fields must be satisfied when these targets
> are invoked.
>
> +Alternative dependencies are allowed in the ``Build-Depends``,
> +``Build-Depends-Indep``, and ``Build-Depends-Arch`` fields, but Debian's
> +autobuilders normally interpret them in a restricted way. After
> +dependencies that do not apply to the current architecture are removed,
> +all alternatives specifying different package names than the first
> +alternative are dropped. (Alternatives specifying the same package name
> +are kept to permit relationships such as ``foo (<= x) | foo (>= y)``.)
> +The effect, therefore, is to use only the first alternative that is valid
> +on the relevant architecture. This is done to reduce the risk of
> +inconsistencies between repeated builds.
I think this could be expanded a bit?
"This is done to reduce the risk of inconsistencies between repeated
builds, in case a package is temporarily not available to be installed
on a given architecture (which due to the nature of the unstable
distribution might happen for any number of reasons) at the time of the
(re-)build of a package."
or something along those lines. The point is to make it clear how these
inconsistencies are caused, which I think will help with understanding.
(I realize your text is what the footnote originally said, but I think
this suggestion would improve matters)
--
w@uter.{be,co.za}
wouter@{grep.be,fosdem.org,debian.org}
I will have a Tin-Actinium-Potassium mixture, thanks.
Reply to: