Bug#968226: Move documentation of Build-Depends alternative selection out of footnote
Wouter Verhelst <w@uter.be> writes:
> On Tue, Sep 20, 2022 at 07:17:17PM -0700, Russ Allbery wrote:
>> Wouter Verhelst <wouter@debian.org> writes:
>>> 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.
Apologies, that probably sounded like I was complaining about you not
sending a patch. I only meant to mention that this was a thread from a
long time back, which is why it might seem out of the blue. I have
dropped so many Policy balls that I'm certainly not going to complain
about a bug slipping someone else's mind. :)
> 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)
Here's an updated patch that expands that and also is more explicit, since
I found my own wording a bit hard to read. I also added an example. It
may be a bit verbose now, but this feels like an important topic to be
clear about given how often it comes up.
I also reworded the paragraph about backports to hopefully address
Holger's reading. It's just trying to say that backports uses aptitude in
the normal way and doesn't do anything special to transform the
alternative.
--
Russ Allbery (rra@debian.org) <https://www.eyrie.org/~eagle/>
>From 36373c7de4ae7a0ac0051848d5e1b8e181bcf78d 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..e8978af 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 suite 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
--
2.37.2
Reply to: