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

Sean Whitton <[email protected]> Thu, 26 Feb 2026 20:13:06 +0000
Newsgroups	gmane.linux.debian.devel.policy
Message-ID	<877brz2rhp.fsf__9086.73209357715$1772136935$gmane$org@melete.silentflame.com>
Helmut Grohne [17/Nov 11:39am +01] wrote:
> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 9f06cc9..b492790 100644
> --- 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
> @@ -1251,6 +1253,23 @@ 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``
> +~~~~~~~~~~~~~~~~~~
> +
> +This field occurs in the binary package sections of a source template
> +control file. It expresses whether the binary package is being
> +produced, given a set of enabled build profiles.  The condition uses
> +the same `restriction formula syntax <s-restrictions>` from the
> +``Build-Depends`` field.
> +
> +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 unconditionally with respect to build profiles.  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 field's value
> +evaluates to true.
> +
>  Remarks
>  ^^^^^^^
>
> diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> index fb9dae8..89a8277 100644
> --- a/policy/ch-relationships.rst
> +++ b/policy/ch-relationships.rst
> @@ -51,22 +51,73 @@ 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 square brackets, the specifics of which are
> +`described below <s-architecture-restrictions>`. Build profile
> +restriction lists are enclosed by pairs of opening and closing angle
> +brackets and are also `described in detail below
> +<s-profile-restrictions>`.
> +
> +There can be at most one architecture restriction list per dependency
> +alternative, 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 and a
> +build profile restriction formula are to be applied to a dependency
> +alternative, then the architecture restriction list must come before the
> +build profile restriction formula in the field value. The non-empty sets
> +of terms enclosed in either square or angle brackets must be separated
> +by whitespace.
> +
> +Architecture restriction lists and build profile restriction formulas
> +are evaluated differently. Both can be evaluated to booleans, given a
> +host architecture and a set of enabled build profiles. Their results
> +indicate whether the dependency alternative should be considered or
> +ignored. For a dependency alternative to be considered, the architecture
> +restriction list (if any) and the build profile restriction formula (if
> +any) must evaluate to true. A dependency is ignored if none of its
> +alternatives apply.
> +
> +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 might specify that building a package
> +on a certain architecture requires an additional dependency; such a
> +restriction does not 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 only appear in 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.
> +
> +.. _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.)
>
>  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 and there are no
>  exclamation marks in the list, or it is in the list with a prepended
> -exclamation mark, the package name and the associated version
> -specification are ignored completely for the purposes of defining the
> -relationships.
> +exclamation mark, the restriction list evaluates to false.  This means
> +that the package name and the associated version specification are
> +ignored completely for the purposes of defining the relationships.
>
>  For example:
>
> @@ -134,11 +185,61 @@ is equivalent to ``foo`` on architectures using the Linux kernel and any
>  cpu, ``bar`` on architectures using any kernel and an i386 cpu, and
>  ``baz`` on any architecture using a kernel other than Linux.
>
> -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-profile-restrictions
> +
> +Build profile restriction formulas
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +A build profile restriction formula is a sequence of build profile
> +restriction lists. In contrast, there must not be more than one
> +architecture restriction list per dependency alternative.  Each list
> +is enclosed in angle brackets (less than sign and greater than
> +sign). 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. Unlike architecture
> +restriction lists, positive and negative terms may be mixed.
> +
> +A restriction formula may be evaluated as a disjunctive normal form
> +expression, given a set of :ref:`enabled build profiles
> +<s-rules-build-profiles>`. In other words, each term within a
> +restriction list is AND-ed together while the restriction lists in a
> +restriction formula are OR-ed together. Therefore, 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 its name is enabled for the
> +build and to "false" otherwise. The result may be negated by
> +prefixing the profile name with an exclamation mark.
> +
> +In the following example, the package would depend on ``foo`` when built
> +for ``i386`` or 32-bit 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
> +``noinsttest`` 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>
>
>  .. _s-binarydeps:
>
> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index a2aa4cc..fed0468 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -621,6 +621,66 @@ order to make it work for your package.
>              # Code to run the package test suite.
>      endif
>
> +.. _s-rules-build-profiles
> +
> +``debian/rules`` and ``DEB_BUILD_PROFILES``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +If the ``DEB_BUILD_PROFILES`` environment variable is defined during the
> +build of a source package, it specifies which build profiles are
> +enabled. Its value is a space-separated, unordered list of enabled build
> +profile names. By default, no build profiles are enabled. The meaning of
> +the following build profiles has been standardized:
> +
> +``nocheck``
> +    This profile extends the meaning of the ``nocheck`` tag in
> +    ``DEB_BUILD_OPTIONS`` and must not be enabled unless combined with
> +    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 enabling the profile or the tag must not
> +    functionally change the emitted binary packages and also must not
> +    change the set of binary packages being produced. If tests happen to
> +    be installed into a binary package, consider supporting the
> +    ``noinsttest`` build profile.
> +
> +``noinsttest``
> +    This profile disables the emission of binary packages consisting
> +    entirely of automated tests, manual tests, example/demo programs,
> +    and test tools. Other packages must not functionally change when
> +    this profile is enabled. Note that in many cases, it is only
> +    possible to drop such dependencies used for building when enabling
> +    both the ``noinsttest`` and the ``nocheck`` build profile
> +    concurrently.  Therefore such dependencies tend to be conditional to
> +    ``<!nocheck> <!noinsttest>``.
> +
> +A larger list of commonly used build profiles can be found in the `Build
> +Profile Spec
> +<https://wiki.debian.org/BuildProfileSpec#Registered_profile_names>`_.
> +
> +The following makefile snippet is an example of how to enable python for
> +all builds except when the package is built with the ``nopython`` build
> +profile active.
> +
> +.. code-block:: Makefile
> +
> +    ifneq ($(filter nopython,$(DEB_BUILD_PROFILES)),)
> +        # nopython build profile was activated -- disable python
> +        CONFIGURE_SWITCHES += --disable-python
> +    else
> +        CONFIGURE_SWITCHES += --enable-python
> +    endif
> +
> +Alternatively, one may defer the evaluation of restriction formulas in
> +general (including architecture restrictions) to ``debhelper``.
> +
> +.. code-block:: Makefile
> +
> +    ifneq ($(filter foo,$(shell dh_listpackages)),)
> +        # foo is being built
> +        CONFIGURE_SWITCHES += --enable-foo
> +    else
> +        CONFIGURE_SWITCHES += --disable-foo
> +    endif
>
>  .. _s-debianrules-gainrootapi:

Seconded, but:

- I wonder what you think about upgrading "If tests happen to be
  installed into a binary package, consider supporting the
  ``noinsttest`` build profile." to Policy advice by saying that it is
  *recommended* to do this?  That would be a normative change.

- When you say "the following build profiles has been standardized" I
  will change that to "the following build profiles are standard" to
  make it clear we're standardising them by putting them in Policy, not
  that they are standardised elsewhere.

- I think I wrote a couple of paragraphs so perhaps I could be
  Co-authored-by too? :)

- I will do some other minor wording fixes after committing the change.

Thanks for the updated patch.

-- 
Sean Whitton
signature.asc (application/pgp-signature, 869 B)