Bug#968226: Move documentation of Build-Depends alternative selection out of footnote
- To: Russ Allbery <rra@debian.org>
- Cc: 968226@bugs.debian.org
- Subject: Bug#968226: Move documentation of Build-Depends alternative selection out of footnote
- From: Sean Whitton <spwhitton@spwhitton.name>
- Date: Sat, 24 Feb 2024 10:28:05 +0800
- Message-id: <[🔎] 87h6hytx3e.fsf@melete.silentflame.com>
- Reply-to: Sean Whitton <spwhitton@spwhitton.name>, 968226@bugs.debian.org
- In-reply-to: <87a5ttx6pi.fsf@hope.eyrie.org> (Russ Allbery's message of "Sun, 10 Sep 2023 10:45:45 -0700")
- References: <20200811070014.GA9686@pc181009.be.zetes.internal> <20200811070014.GA9686@pc181009.be.zetes.internal> <87o8nh8655.fsf@hope.eyrie.org> <20200811070014.GA9686@pc181009.be.zetes.internal> <20200814152228.GE26036@pc181009.be.zetes.internal> <87czbph3o2.fsf_-_@hope.eyrie.org> <20200811070014.GA9686@pc181009.be.zetes.internal> <YyrCPhOKtzogwGl4@pc220518.home.grep.be> <20200811070014.GA9686@pc181009.be.zetes.internal> <878rmahmat.fsf@hope.eyrie.org> <20200811070014.GA9686@pc181009.be.zetes.internal> <87il8ivsgh.fsf@hope.eyrie.org> <20200811070014.GA9686@pc181009.be.zetes.internal> <87a5ttx6pi.fsf@hope.eyrie.org> <20200811070014.GA9686@pc181009.be.zetes.internal>
control: tag -1 + pending
On Sun 10 Sep 2023 at 10:45am -07, Russ Allbery wrote:
> Russ Allbery <rra@debian.org> writes:
>
>> This patch from a while back is still waiting for one more second before
>> it can be merged for the next Policy release. It previously got one
>> second from Wouter. I revised the patch to mention the experimental
>> suite as well as the backports suites.
>
> Argh, wrong patch, sorry. Here is the one that was actually updated to
> include experimental.
Seconded and applied. I think the whole thing might be non-normative,
but certainly the mere addition of experimental is.
> --
> Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
>
>>From 7ee49f6c892d6057b9a0d2f9eb84ff0f35d1d436 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 | 61 +++++++++++++++++++++++++++----------
> 1 file changed, 45 insertions(+), 16 deletions(-)
>
> diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> index 5074428..ffafbf1 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 interpreted
> +specially by Debian autobuilders. 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,47 @@ 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 discard the dependencies after the first. This is
> +done to give alternative dependencies a consistent interpretation that
> +reduces the risk of inconsistencies between repeated builds. If, for
> +example, the first-listed dependency would normally be available but is
> +temporarily not installable, the autobuilder fails rather than install a
> +subsequent dependency that may significantly change the behavior of the
> +package.
> +
> +More specifically, Debian autobuilders perform the following
> +transformation on alternative dependencies in the ``Build-Depends``,
> +``Build-Depends-Indep``, and ``Build-Depends-Arch`` fields:
> +
> +#. Discard any alternatives that are restricted to architectures that do
> + not match the host architecture.
> +#. Discard any alternatives specifying different package names than the
> + now-first alternative. (Alternatives specifying the same package name
> + are kept to permit relationships such as ``foo (<= x) | foo (>= y)``.)
> +
> +For example, an autobuilder for the ``amd64`` architecture would treat the
> +following dependency::
> +
> + foo-special [armhf] | foo (<= 4) | foo (>= 4.2) | bar
> +
> +as if it were::
> +
> + foo (<= 4) | foo (>= 4.2)
> +
> +The normal effect is to use only the first alternative that is valid on
> +the relevant architecture and fail if that alternative is not installable.
> +
> +While this rule for build dependencies may limit the usefulness of
> +alternatives, they can still be used to provide flexibility when building
> +the package outside of Debian's autobuilders.
> +
> +The autobuilders for the Debian backports and experimental suites do not
> +perform this transformation and instead use the same dependency resolution
> +rules as normal package installations to choose which alternative
> +dependency to install.
> +
> .. _s-built-using:
>
> Additional source packages used to build the binary - ``Built-Using``
> @@ -666,21 +710,6 @@ requirements to retain the referenced source packages. It should not
> be added solely as a way to locate packages that need to be rebuilt
> against newer versions of their build dependencies.
>
> -.. [#]
> - While ``Build-Depends``, ``Build-Depends-Indep`` and
> - ``Build-Depends-Arch`` permit the use of alternative dependencies,
> - those are only used for the backports suite on the Debian autobuilders.
> - On the other suites, after reducing any architecture-specific restrictions
> - for the build architecture in question, all but the first alternative are
> - discarded except if the alternative is the same package name as the first.
> - The latter exception is useful to specify version ranges like
> - ``foo (rel x) | foo (rel y)``. This is to reduce the risk of inconsistencies
> - between repeated rebuilds. 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.
> -
> .. [#]
> The relations ``<`` and ``>`` were previously allowed, but they were
> confusingly defined to mean earlier/later or equal rather than
--
Sean Whitton
Reply to: