Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Sean Whitton]

control: tag -1 + pending

On Sun 10 Sep 2023 at 10:45am -07, Russ Allbery wrote:

> Russ Allbery  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 (r...@debian.org)  
>
>>From 7ee49f6c892d6057b9a0d2f9eb84ff0f35d1d436 Mon Sep 17 00:00:00 2001
> From: Russ Allbery 
> 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 ` 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-

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Edward Little]

Please remove the following email address:  e.little...@gmail.com

On Sun, Sep 10, 2023 at 1:42 PM Russ Allbery  wrote:

> 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.
>
> --
> Russ Allbery (r...@debian.org)  
>
>

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Russ Allbery]

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

-- 
Russ Allbery (r...@debian.org)  

>From 7ee49f6c892d6057b9a0d2f9eb84ff0f35d1d436 Mon Sep 17 00:00:00 2001
From: Russ Allbery 
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 ` 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 spe

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Russ Allbery]

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.

-- 
Russ Allbery (r...@debian.org)  

>From 6a4e1b261f5f5765fa164e4bfd063f67d40a9a47 Mon Sep 17 00:00:00 2001
From: Russ Allbery 
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 ` 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 

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Holger Levsen]

On Mon, Sep 26, 2022 at 10:15:07AM +0200, Wouter Verhelst wrote:
> Experimental is different because it is an incomplete distribution,
> which needs to default to using packages from unstable except if
> build-depends explicitly lists versions that are only available in
> experimental.
[...]

Thanks, Wouter. I guess backports is rather similar. 


-- 
cheers,
Holger

 ⢀⣴⠾⠻⢶⣦⠀
 ⣾⠁⢠⠒⠀⣿⡁  holger@(debian|reproducible-builds|layer-acht).org
 ⢿⡄⠘⠷⠚⠋⠀  OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C
 ⠈⠳⣄

Money is worth nothing on a dead planet.


signature.asc
Description: PGP signature

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Wouter Verhelst]

On Thu, Sep 22, 2022 at 07:11:38PM -0700, Russ Allbery wrote:
> Wouter Verhelst  writes:
> > On Tue, Sep 20, 2022 at 07:17:17PM -0700, Russ Allbery wrote:
> >> Wouter Verhelst  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.  :)

Oh no, trust me, it wasn't; but I still feel bad for having dropped the
ball, as I always do :-)

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

I think that text is miles better, yes. Seconded.

-- 
 w@uter.{be,co.za}
wouter@{grep.be,fosdem.org,debian.org}

I will have a Tin-Actinium-Potassium mixture, thanks.


signature.asc
Description: PGP signature

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Wouter Verhelst]

On Sat, Sep 24, 2022 at 10:16:12AM +, Holger Levsen wrote:
> On Fri, Sep 23, 2022 at 04:17:04PM +0100, Simon McVittie wrote:
> > On Thu, 22 Sep 2022 at 19:11:38 -0700, Russ Allbery wrote:
> > > 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.
>  
> yup, it's better, thanks.
> 
> > It's perhaps worth mentioning that experimental does something similar
> > (it has used the aptitude and aspcud resolvers at various times, but
> > I'm not sure which one is currently in use).
> 
> I see.
> 
> I think my biggest concern is actually not how it's described but rather
> why/that it is different at all (and then wondering whether it will stay
> that way...)

Experimental is different because it is an incomplete distribution,
which needs to default to using packages from unstable except if
build-depends explicitly lists versions that are only available in
experimental.

When I set up the first experimental autobuilder back in the day, I
hacked the sbuild resolver (it had its own resolver at the time) to
explicitly tell apt which packages to pull from experimental, rather
than doing something like "-t experimental" or some such.

I wrote
https://lists.debian.org/debian-devel-announce/2006/04/msg7.html to
-devel-announce at the time; but since I haven't been involved with
buildd work in a while, I can't really say whether it's still accurate
or relevant today.

-- 
 w@uter.{be,co.za}
wouter@{grep.be,fosdem.org,debian.org}

I will have a Tin-Actinium-Potassium mixture, thanks.

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Holger Levsen]

On Fri, Sep 23, 2022 at 04:17:04PM +0100, Simon McVittie wrote:
> On Thu, 22 Sep 2022 at 19:11:38 -0700, Russ Allbery wrote:
> > 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.
 
yup, it's better, thanks.

> It's perhaps worth mentioning that experimental does something similar
> (it has used the aptitude and aspcud resolvers at various times, but
> I'm not sure which one is currently in use).

I see.

I think my biggest concern is actually not how it's described but rather
why/that it is different at all (and then wondering whether it will stay
that way...)


-- 
cheers,
Holger

 ⢀⣴⠾⠻⢶⣦⠀
 ⣾⠁⢠⠒⠀⣿⡁  holger@(debian|reproducible-builds|layer-acht).org
 ⢿⡄⠘⠷⠚⠋⠀  OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C
 ⠈⠳⣄

Our civilization is being sacrificed for the opportunity of a very small number
of people to continue making enormous amounts of money...  It is the sufferings
of the many  which pay  for the luxuries  of the few...  You say  you love your
children  above all else,  and yet  you are stealing  their future  in front of 
their very eyes... (Greta Thunberg)


signature.asc
Description: PGP signature

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Simon McVittie]

On Thu, 22 Sep 2022 at 19:11:38 -0700, Russ Allbery wrote:
> 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.

It's perhaps worth mentioning that experimental does something similar
(it has used the aptitude and aspcud resolvers at various times, but
I'm not sure which one is currently in use).

smcv

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Russ Allbery]

Wouter Verhelst  writes:
> On Tue, Sep 20, 2022 at 07:17:17PM -0700, Russ Allbery wrote:
>> Wouter Verhelst  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 (r...@debian.org)  

>From 36373c7de4ae7a0ac0051848d5e1b8e181bcf78d Mon Sep 17 00:00:00 2001
From: Russ Allbery 
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 ` 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

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Holger Levsen]

On Tue, Sep 20, 2022 at 07:17:17PM -0700, Russ Allbery wrote:
> +The autobuilders for the Debian backports suite do not perform this
> +transformation and instead use the full alternatives list to resolve
> +dependencies.
 
this sounds like they install all build depends, incl alternative ones?!
is that really the case? (and why?)


-- 
cheers,
Holger

 ⢀⣴⠾⠻⢶⣦⠀
 ⣾⠁⢠⠒⠀⣿⡁  holger@(debian|reproducible-builds|layer-acht).org
 ⢿⡄⠘⠷⠚⠋⠀  OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C
 ⠈⠳⣄

Make facts great again.


signature.asc
Description: PGP signature

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Wouter Verhelst]

On Tue, Sep 20, 2022 at 07:17:17PM -0700, Russ Allbery wrote:
> Wouter Verhelst  writes:
> > On Tue, Aug 11, 2020 at 10:05:42AM -0700, Russ Allbery wrote:
> >> Wouter Verhelst  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 (r...@debian.org)  
> 

> From dd30c5455f13086dd0ef90bf6890c20729a1ac0b Mon Sep 17 00:00:00 2001
> From: Russ Allbery 
> 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
> +` 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 originall

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Russ Allbery]

Wouter Verhelst  writes:
> On Tue, Aug 11, 2020 at 10:05:42AM -0700, Russ Allbery wrote:
>> Wouter Verhelst  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.

-- 
Russ Allbery (r...@debian.org)  

>From dd30c5455f13086dd0ef90bf6890c20729a1ac0b Mon Sep 17 00:00:00 2001
From: Russ Allbery 
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
+` 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.
+
+The autobuilders for the Debian backports suite do not perform this
+transformation and instead use the full alternatives list to resolve
+dependencies.
+
+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, or when building it across
+multiple distributions or releases where a particular dependency is met by
+differently named packages.
+
 .. _s-built-using:
 
 Additional source packages used to build the binary - ``Built-Using``
@@ -666,21 +690,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``