Groups | Search | Server Info | Login | Register

Groups > linux.debian.policy > #9056

Bug#757760: debian-policy: please document build profiles

Cross-posted to 2 groups.

Show all headers | View raw

[Multipart message — attachments visible in raw view] - view raw

Hi Sean,

thank you for your review. Please excuse the delay of our response. I 
happened to run into Nattie again and she helped me a lot in improving 
the text in combination with your remarks.  Also Colin reviewed it and 
Stefano Rivera helped on a few paragraphs.

On Sun, Jun 01, 2025 at 11:12:31AM +0100, Sean Whitton wrote:
> > +``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>` ...

We found the paragraph hard to read, agreed with your criticism and 
significantly rephrased it.

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

We do explain disjuntive normal form later. Indeed there is little value 
in mentioning it here.

> > +
> > --- 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"

Yes, thanks

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

Yes, both, thanks.

> > +There can only be at most one architecture
> > +restriction list per package
> 
> Per binary package, right?

I found that ambiguous as well and went for "dependency alternative" 
instead. Hope that also makes sense to you and others.

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

Yes, thanks.

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

It's the set that should have been plural and the sets that should be 
separated. Thank you.

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

Rewritten instead.

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

You are not the only one being confused. Rewritten. Thanks.

> > +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?].

Thank you. Accepted with minor changes.

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

Significantly rephrased.

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

Yes, thanks.

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

Yes, thanks.

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

The reference definitely makes sense and I readily added it. We further 
rephrased it to improve readability, but I disagree about going into 
bootstrapping here as build profiles are a wider concept applicable way 
beyond bootstrapping.

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

I was struggling to see how this is not normative. Nevertheless, we 
found it difficult to read and rephrased it hoping that you may find it 
more normative now.

> Policy can standardise them, here.

I'm not sure what you want me to change 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.

Rephrased, thanks.

As much as we may continue word smithing this text, I suggest that the 
perfect is the enemy of the good. By now, not having this text in policy 
seems worse to me than having a buggy description of build profiles.

Helmut

Back to linux.debian.policy | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

Bug#757760: debian-policy: please document build profiles Johannes Schauer Marin Rodrigues <josch@debian.org> - 2025-03-30 17:20 +0200
  Bug#757760: debian-policy: please document build profiles Sean Whitton <spwhitton@spwhitton.name> - 2025-03-31 05:00 +0200
  Bug#757760: debian-policy: please document build profiles Sean Whitton <spwhitton@spwhitton.name> - 2025-06-01 12:30 +0200
    Bug#757760: debian-policy: please document build profiles Helmut Grohne <helmut@subdivi.de> - 2025-11-16 18:20 +0100
      Bug#757760: debian-policy: please document build profiles Johannes Schauer Marin Rodrigues <josch@debian.org> - 2025-11-17 10:20 +0100
        Bug#757760: debian-policy: please document build profiles Helmut Grohne <helmut@subdivi.de> - 2025-11-18 10:20 +0100
          Bug#757760: debian-policy: please document build profiles Guillem Jover <guillem@debian.org> - 2025-12-05 13:30 +0100
            Bug#757760: debian-policy: please document build profiles Guillem Jover <guillem@debian.org> - 2025-12-18 14:50 +0100
          Bug#757760: debian-policy: please document build profiles Sean Whitton <spwhitton@spwhitton.name> - 2026-02-26 21:20 +0100
            Bug#757760: debian-policy: please document build profiles Johannes Schauer Marin Rodrigues <josch@debian.org> - 2026-03-26 09:00 +0100
              Bug#757760: debian-policy: please document build profiles Sean Whitton <spwhitton@spwhitton.name> - 2026-03-26 14:30 +0100
                Bug#757760: debian-policy: please document build profiles Johannes Schauer Marin Rodrigues <josch@debian.org> - 2026-03-26 17:30 +0100
                Bug#757760: debian-policy: please document build profiles Guillem Jover <guillem@debian.org> - 2026-03-26 18:20 +0100
                Bug#757760: debian-policy: please document build profiles Johannes Schauer Marin Rodrigues <josch@debian.org> - 2026-03-26 19:20 +0100
      Bug#757760: debian-policy: please document build profiles Sean Whitton <spwhitton@spwhitton.name> - 2025-11-25 13:10 +0100

csiph-web