Re: Bug#757760: debian-policy: please document build profiles
Some suggestions
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -152,6 +152,8 @@ The fields in the binary package stanzas are:
>
> - :ref:`Package-Type <s-f-Package-Type>`
>
> +- :ref:`Build-Profiles <s-f-Build-Profiles>`
> +
> The syntax and semantics of the fields are described below.
>
> These fields are used by ``dpkg-gencontrol`` to generate control files
> @@ -1243,6 +1245,20 @@ or set it to ``binary-targets`` if it has been requested to test
> whether the package it builds correctly implements the fall-back for
> legacy builders.
>
> +``Build-Profiles``
> +~~~~~~~~~~~~~~~~~~
> +
> +Specifies the condition for which that binary package does or does
> not
"a" not "that" (or if there is meant to be some more specifc "that", the
text is missing an explaination of what 'that' refers to)
> +build. To express that condition, the same `restriction formula syntax
> +<s-restrictions>` from the ``Build-Depends`` field is used. If a binary
> +package stanza in a source package template control file does not
> +contain a ``Build-Profiles`` field, then it implicitly means that it
> +builds unconiditionally with respect to build profiles. If a binary
^^^^^^^^^^^^^^^^
typo
> +package stanza in a source package template control file is annotated
i wonder if you need to say "template" here? the sentence is quite hard to read,
and "template" makes it sound like it isnt in the package?
> +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.
seems to be something missing after "expression" - it is not clear
where the 'expression' is to be defined
> +
> Remarks
> ^^^^^^^
>
> diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> index fb9dae8..ca07d1d 100644
> --- 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>`. Build profile
> +restriction lists
here it is called a "restriction list", but later it talks about restruction formulas.
i cant tell if this is inconsistent drafting or if something has not
been defined (the reader will likely assume the former, so if this
"list" is intended to be a list of formulas then some more explanation
is needed!)
> are enclosed by pairs of opening and closing angular
> +brackets and are further `described below as well
> +<s-profile-restrictions>`. There can only be at most one architecture
> +restriction list per package 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. The non-empty set of
another formula/list here
would it also be allowed to include an example of the syntax somewhere - this
para is quite dense?
> +terms enclosed in either rectangular or angular brackets are separated
> +by whitespace.
> +
> +Architecture restriction lists and build profile restriction formulas
formulas? or lists?
> +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. 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.
> +
> +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.
> +
> +Note that the binary package relationship fields such as ``Depends``
> +appear in one of the binary package stanzas of the template control
> +file, whereas the build-time relationships such as ``Build-Depends``
> +appear in the source package stanza of the template control file (which
> +is the first section).
> +
> +.. _s-architecture-restrictions
> +
> +Architecture restrictions
> +^^^^^^^^^^^^^^^^^^^^
> +
> +Architecture restriction lists consist of Debian :ref:`architecture
> +specification strings <s-arch-spec>`. 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.)
this was there before, but usually in written english you spell out "are
not", it currently reads like the sentence ends too soon
>
> For build relationship fields (``Build-Depends``,
> ``Build-Depends-Indep``, ``Build-Depends-Arch``, ``Build-Conflicts``,
> ``Build-Conflicts-Indep`` and ``Build-Conflicts-Arch``), if the current
> Debian host architecture is not in this list
"this list" is slightly ambiguous here, it could be read as the "a build
relationship field", the list in brackets in this sentence, or even the
"architecture restriction list" in the previous sentence
> +.. _s-profile-restrictions
> +
> +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.
now i am very confused about the list/formula distinction!
> 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. Negation happens by prefixing the name with an exclamation
> +mark. In contrast to architecture restriction lists, positive and
> +negative terms can be mixed.
> +
> +One or more restriction lists form a restriction formula.
aha - i suggest that this sentence be explained much earlier in the
patch
> A restriction
> +formula can be evaluated as a disjunctive normal form expression.
surely it "is" a dnf expression rather than "can be evaluated as" one?
or is there some other way it can be evaluated?
> This
> +is, each term within a restriction list is AND-ed together while| the
seems to be a stray | after "while" here
> +restriction lists in a restriction formula are OR-ed together. This
> also
i dont think the word "also" is helping clarity here.
Could also shorten to "The order of ... does not matter"
> +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.
would it be possible to link to instructions on how to set a profile here?
(eg a link to the next section would do it)
> Optional negation
> +with an exclamation mark is applied before evaluating conjunctions and
> +disjunctions.
> +
> +In the following example, the package would depend on ``foo`` when built
> +for ``i386`` or 32bit ARM architectures and if one of the ``nocheck``
> +and ``cross`` profiles is not enabled by the builder:
> +
> +::
> +
> + Build-Depends: foo (>= 1.0) [i386 any-arm] <!nocheck> <!cross>, bar
> +
> +In the following example, the source package would build depend on
> +``foo`` only if both, the ``nocheck`` profile and the ``cross`` profile
> +are enabled at the same time.
> +
> +::
> +
> + Build-Depends: foo <nocheck cross>
> +
> +In the next example, the source package would build depend on ``foo`` if
> +``nopython`` is disabled and at least one of ``nocheck`` and
> +``nopython`` is disabled.
> +
> +::
> +
> + Build-Depends: foo <!nopython !nocheck> <!nopython !noinsttest>
> +
> +The last example can also be rewritten to this alternative form which is
> +equal in meaning:
> +
> +::
> +
> + Build-Depends: foo <!nopython !nocheck>, foo <!nopython !noinsttest>
>
is there is list of supported profile names? does any no<srcpackage> work?
> .. _s-binarydeps:
>
> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index a2aa4cc..ee292ce 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -621,6 +621,62 @@ order to make it work for your package.
> # Code to run the package test suite.
> endif
>
> +``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:
would it flow better to have this section before the one about the fields?
on the wiki page https://wiki.debian.org/BuildProfileSpec there are
other profiles not included here, not sure if that was deliberate. eg
documenting pkg.$sourcepackage.$anything might be helpful?
> +
> +``nocheck``
> + This profile extends the meaning of the ``nocheck`` tag in
> + ``DEB_BUILD_OPTIONS``
can you link to where that tag is documented?
Reply to: