Hello,
On Sun 30 Mar 2025 at 05:10pm +02, Johannes Schauer Marin Rodrigues wrote:
> Hi Sean and other policy editors,
>
> it may appear strange to resume a thread that was last discussed seven years
> ago. Yet, we picked up this matter at the Würzburg sprint and iterated a lot on
> the text already present in the BuildProfileSpec, refining and extending it to
> hopefully better fit the language and structure of Debian Policy.
Thank you very much for this. Here is a review.
> +``Build-Profiles``
> +~~~~~~~~~~~~~~~~~~
> +
> +Specifies the condition for which that binary package does or does not
> +build.
... when it doesn't have any FTBFS bugs? :)
How about
Build profiles are <succinct description>. This field expresses
just when the binary package builds, with respect to active and
inactive build profiles. This condition is expressed using the
`restriction formula syntax <s-restrictions>` ...
> + If a binary package stanza in a source package template control file
> + is annotated with a ``Build-Profiles`` field, then that binary
> + package is generated if and only if the condition expressed by the
> + disjunctive normal form expression evaluates to true.
I know what disjunctive normal form means but I don't think Policy
defines it and I'm not sure it is necessary to mention it here.
Why not just say
If a binary package stanza in a source package template control file
has a ``Build-Profiles`` field, then that binary package is
generated if and only if the condition expressed by the field's
value holds.
> +
> --- a/policy/ch-relationships.rst
> +++ b/policy/ch-relationships.rst
> @@ -51,22 +51,76 @@ For example, a list of dependencies might appear as:
> Version: 1.3.17-1
> Depends: libc6 (>= 2.2.1), default-mta | mail-transport-agent
>
> -Relationships may be restricted to a certain set of architectures. This
> -is indicated in brackets after each individual package name and the
> -optional version specification. The brackets enclose a non-empty list of
> -Debian architecture names in the format described in
> -:ref:`s-arch-spec`, separated by whitespace. Exclamation
> -marks may be prepended to each of the names. (It is not permitted for
> -some names to be prepended with exclamation marks while others aren't.)
> +.. _s-restrictions
> +
> +Restrictions
> +~~~~~~~~~~~~
> +
> +Relationships may be restricted to a certain set of architectures or
> +build profiles. This is indicated in brackets after each individual
> +package name and the optional version specification. There are two types
> +of restrictions. Architecture restriction lists are enclosed in a pair
> +of opening and closing rectangular brackets, specifics of which are
> +`described below <s-architecture-restrictions>`.
"*the* specifics of which"
> +Build profile
> +restriction lists are enclosed by pairs of opening and closing angular
> +brackets and are further `described below as well
> +<s-profile-restrictions>`.
s/further described below as well/also described in detail below/
Also, I'd suggest a paragraph break after this sentence.
> +There can only be at most one architecture
> +restriction list per package
Per binary package, right?
> but there can be more than one build
> +profile restriction list. One or more build profile restriction lists
> +form a build profile restriction formula. If both an architecture
> +restriction list as well as a build profile restriction formula are to
> +be applied to a dependency, then the architecture restriction list must
> +come before the build profile restriction formula.
"... must come before the build profile restriction formula *in the field
value*."
> The non-empty set of
> +terms enclosed in either rectangular or angular brackets are separated
> +by whitespace.
This doesn't make sense -- the singular non-empty set has a plural "are
separated". What do you mean?
> +Architecture restriction lists and build profile restriction formulas
> +are evaluated differently but they both evaluate to a boolean decision
> +as to whether the dependency that the restriction was applied to is
> +being kept or should be ignored.
"as to whether the dependency to which the restriction is applied should
be kept or ignored."
> For a dependency to be ignored, it is
> +enough for either the architecture restriction list or the build profile
> +restriction formula to evaluate to false. If the dependency with a
> +restriction is part of a set of alternatives, the alternative for which
> +either restriction does not apply is ignored and the other alternatives
> +remain for evaluation.
"remain for evaluation" seems vague.
I think you are trying to capture how a system consuming these files is
allowed to consider only the first alternative?
Could you just say that each restriction applies separately to each
alternative?
> +A dependency with an architecture restriction list or build profile
> +restriction formula in one of the build relationship fields
> +(``Build-Depends``, ``Build-Depends-Indep``, ``Build-Depends-Arch``,
> +``Build-Conflicts``, ``Build-Conflicts-Indep`` and
> +``Build-Conflicts-Arch``) which does not not match will result in that
> +build dependency to be ignored. If the dependency is used for binary
> +relationship fields and the ``Built-Using`` field, the architecture and
> +build profile restriction syntax is only supported in the source package
> +template control file ``debian/control``. When the corresponding binary
> +package control file is generated, the relationship will either be
> +omitted or included with neither the architecture restriction nor the
> +build profile restriction formula.
This is very dense, let me suggest something like
The sense in which a dependency is ignored depends on the field in
which the restriction appears. A restriction in one of the build
relationship fields (``Build-Depends``...) that does not match means
that the build-dependency is not required to be satisfied for the
package to be built. For example, a restriction specifying that
building a package on a certain architecture requires an additional
dependency doesn't match on other architectures, meaning the package
can be built there without first installing that additional
dependency.
A restriction appearing in a field describing relationships between
binary packages (such as ``Depends``) must appear in only the source
package template control file ``debian/control``. The dependency is
ignored in the sense that it will not appear in the corresponding
binary package control file if the restriction does not match [right?].
> +Build profile restriction formulas
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In contrast to architecture restriction lists, of which at most one can
> +be added to a dependency, build profile restriction formulas consist of
> +multiple restriction lists.
It would be good to rewrite this using must/must
not/required/prohibited -- the Policy normative magic words.
> Each list is enclosed in angular brackets
> +(less than sign and greater than sign). Each of the space separated
> +terms of a restriction list is the optionally negated name of a build
> +profile.
"Each of the space-separated terms of a restriction list is the
possibly-negated name of a build profile."
> Negation happens by prefixing the name with an exclamation
> +mark. In contrast to architecture restriction lists, positive and
> +negative terms can be mixed.
"may be mixed" to use the Policy normative magic words.
> +One or more restriction lists form a restriction formula. A restriction
> +formula can be evaluated as a disjunctive normal form expression. This
> +is, each term within a restriction list is AND-ed together while the
> +restriction lists in a restriction formula are OR-ed together. This also
> +means that the order of terms within restriction lists and the order of
> +restriction lists within a restriction formula does not matter. A
> +profile name in a term evaluates to "true" if the profile with the same
> +name was set for the build and to "false" otherwise. Optional negation
> +with an exclamation mark is applied before evaluating conjunctions and
> +disjunctions.
I think that the sense of "set for the build" should be explained.
Indeed, it would be good to just describe what build profiles are before
getting into how they are evaluated. What sort of things are they used
for? How do they help with bootstrapping?
Probably you want to refer to "debian/rules and DEB_BUILD_PROFILES" and
put the general introduction there.
> +``debian/rules`` and ``DEB_BUILD_PROFILES``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The environment variable ``DEB_BUILD_PROFILES`` may be set to a space
> +separated unordered list of build profiles that are active for this
> +build. All build profiles not listed in that variable are considered
> +disabled and therefore no build profiles are enabled by default. The
> +meaning of the following build profiles has been standardized:
Please rewrite this intro using the normative words.
Policy can standardise them, here.
> +``nocheck``
> + This profile extends the meaning of the ``nocheck`` tag in
> + ``DEB_BUILD_OPTIONS`` and may only be enabled in combination with
> + setting that tag. In addition to disabling build-time testing, it
> + allows skipping the installation of dependencies required for those
> + tests during the build. Note that neither the profile nor the tag
> + may functionally change the emitted binary packages nor the set of
> + binary packages. If tests happen to be installed into a binary
> + package, consider supporting the ``noinsttest`` build profile.
> +
> +``noinsttest``
> + Disable binary packages consisting entirely of automated tests,
> + manual tests, example/demo programs and test tools. Other packages
> + may not functionally change when this profile is enabled. Note that
> + dependencies used for building these tests often con only be dropped
> + when enabling both the ``noinsttest`` and the ``nocheck`` build
> + profile and therefore such dependencies tend to be conditional to
> + ``<!nocheck> <!noinsttest>``.
These should probably be rewritten using the normative words, too.
Thanks again.
--
Sean Whitton
Attachment:
signature.asc
Description: PGP signature