Bug#757760: debian-policy: please document build profiles
Hi!
On Mon, 2025-11-17 at 11:39:52 +0100, Helmut Grohne wrote:
> >From a1ae345e117194c42539c6d2da8b7d537b57753f 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
> +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
Unless I missed it, I don't see any definition of what is a valid
build profile name, and that would match with the current implementation
in dpkg, which did not either. I think this was a mistake, because
in contrast to architecture names which get defined first in dpkg
(although you can use anything you want but dpkg will still validate
its format, that is alphanumeric and «-»), with build profiles, those
get defined outside of dpkg, so there's no vetting.
As I mentioned in a recent thread in debian-devel, this has already
caused at least two issues with colliding characters usage in different
context.
One is with the use of «.» as namespace separator in a format where
package names are involved, where «.» is a valid package name
character (I still think this should be progressively be switched to
use «/»).
The other has been in the mapping of the formulas in the Package-List
field, where «+» is being used and is a valid package name, which
means parsing the field is ambiguous. I've solved this now by
deprecating the profile keyword with a new profile:v1 one.
While making the parser more strict to catch invalid syntaxes, I've
now also reduced the allowed characters for the build profiles to the
following Perl regex:
qr{
!?
# Be lenient for now. Accept operators for extensibility, uppercase,
# and package name characters.
[
?/;:=@%*~_
A-Z
a-z0-9+.\-
]+
}x
So, starting with an optional «!», package characters [a-z0-9+.-],
uppercase [A-Z], and operators [?/;:=@%*~_]. But I'm considering
reducing the last one at least to include «/» and perhaps some other
choice characters? But I think the above regex should be the maximum
accepted in any case.
> 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>`_.
This reads as if that page would still be the canonical source for the
specification, which once in policy I'd say becomes a bit fuzzy, so
perhaps worth clarifying what to take as canonical going forward.
For dpkg specs, I tend to mark the wiki pages for them, as no longer
canonical once they have been integrated into the dpkg documentation
(man pages, and refer to them as such).
Thanks,
Guillem
Reply to: