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. Quoting Johannes Schauer (2014-08-11 09:44:44) > please document the new Build-Depends syntax and fields for build profiles. > The current write-up of the new syntax and fields for build profiles lives at > https://wiki.debian.org/BuildProfileSpec I am really sorry I failed to follow up back then as I really do agree that having something in policy would help a lot. You'll find the result of two days of discussion and iteration among Jochen, Helmut and myself attached. Kind regards Jochen, Helmut and josch
>From 6b2479e7ea23fe9fa5e32c2fde49ca3b88a8b51e Mon Sep 17 00:00:00 2001
From: Johannes Schauer Marin Rodrigues <josch@mister-muffin.de>
Date: Sat, 29 Mar 2025 23:04:56 +0100
Subject: [PATCH] document build profiles
Closes: #757760
---
policy/ch-controlfields.rst | 16 +++++
policy/ch-relationships.rst | 134 ++++++++++++++++++++++++++++++++----
policy/ch-source.rst | 56 +++++++++++++++
3 files changed, 191 insertions(+), 15 deletions(-)
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 3151816..0736cf7 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
@@ -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
+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
+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.
+
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 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
+terms enclosed in either rectangular or angular brackets are separated
+by whitespace.
+
+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. 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.)
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 +188,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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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. 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. 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.
+
+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>
.. _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:
+
+``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>``.
+
+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 on 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:
--
2.39.5
Attachment:
signature.asc
Description: signature