Re: [docs][PATCH] ref-manual/dev-manual: document new SPDX variables and capabilities

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Tue Mar 17, 2026 at 9:57 AM CET, Stefano Tondo via lists.yoctoproject.org wrote:
> From: Stefano Tondo <stefano.tondo.ext@siemens.com>
>
> Document the new variables and features introduced by the SPDX
> enrichment patch series merged in OE-Core:
>
> New variables in ref-manual/variables.rst:
> - SPDX_FILE_EXCLUDE_PATTERNS: regex-based file exclusion from SBOM
> - SPDX_IMAGE_SUPPLIER: supplier agent for image SBOMs
> - SPDX_SDK_SUPPLIER: supplier agent for SDK SBOMs
> - SPDX_PACKAGE_SUPPLIER: supplier agent for individual packages
> - SPDX_INVOKED_BY: agent that invoked the build
> - SPDX_ON_BEHALF_OF: agent on whose behalf the build runs
>
> Updated dev-manual/sbom.rst:
> - Add bullet points for file exclusion patterns, supplier
>   information, and ecosystem-specific PURL enrichment via
>   bbclasses (cargo_common, go-mod, pypi, npm, cpan)
>
> Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
> ---
>  documentation/dev-manual/sbom.rst      | 13 +++++
>  documentation/ref-manual/variables.rst | 78 ++++++++++++++++++++++++++
>  2 files changed, 91 insertions(+)
>
> diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst
> index 95303ed..6aa771e 100644
> --- a/documentation/dev-manual/sbom.rst
> +++ b/documentation/dev-manual/sbom.rst
> @@ -64,6 +64,19 @@ more information in the output :term:`SPDX` data:
>  
>  -  Add archives of these source files themselves (:term:`SPDX_ARCHIVE_SOURCES`).
>  
> +-  Exclude specific files from the SPDX output using Python regular expressions
> +   (:term:`SPDX_FILE_EXCLUDE_PATTERNS`).
> +
> +-  Attach supplier information to the image SBOM, SDK SBOM, or individual
> +   packages (:term:`SPDX_IMAGE_SUPPLIER`, :term:`SPDX_SDK_SUPPLIER`,
> +   :term:`SPDX_PACKAGE_SUPPLIER`).
> +
> +-  Enrich source downloads with ecosystem-specific Package URLs (PURLs), using
> +   the :ref:`ref-classes-cargo_common`, :ref:`ref-classes-go-mod`,
> +   :ref:`ref-classes-pypi`, :ref:`ref-classes-npm`, and
> +   :ref:`ref-classes-cpan` classes to automatically populate PURL identifiers
> +   for the corresponding language ecosystems.
> +

No mention of SPDX_INVOKED_BY/SPDX_ON_BEHALF_OF/SPDX_INCLUDE_BITBAKE_PARENT_BUILD?

>  Though the toplevel :term:`SPDX` output is available in
>  ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary
>  generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as:
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 9e0c5b0..6f1b5a9 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9063,6 +9063,19 @@ system and gives an overview of their function and contents.
>             }
>           ],
>  
> +   :term:`SPDX_FILE_EXCLUDE_PATTERNS`
> +      A space-separated list of Python regular expressions used to exclude files
> +      from the SPDX output. Files whose paths match any of the patterns (via

I assume this variable only makes sense with SPDX_INCLUDE_SOURCES is set, right?

Maybe you could make that clear by saying it in the first sentence explicitly?

"""
A space-separated list of Python regular expressions used to exclude files
from the SPDX output when :term:`SPDX_INCLUDE_SOURCES` is enabled.
"""

> +      ``re.search``) will be filtered out from the generated SBOM.
> +
> +      By default this variable is empty, meaning no files are excluded.
> +
> +      Example usage::
> +
> +         SPDX_FILE_EXCLUDE_PATTERNS = "\.patch$ \.diff$ /test/ \.pyc$ \.o$"
> +
> +      See also :term:`SPDX_INCLUDE_SOURCES`.
> +
>     :term:`SPDX_INCLUDE_COMPILED_SOURCES`
>        This option allows the same as :term:`SPDX_INCLUDE_SOURCES` but including
>        only the sources used to compile the host tools and the target packages.
> @@ -9161,6 +9174,41 @@ system and gives an overview of their function and contents.
>        increases the SBOM size (potentially by several gigabytes for typical
>        images).
>  
> +   :term:`SPDX_IMAGE_SUPPLIER`
> +      The base variable name describing the Agent (organization or person) who
> +      supplies the image SBOM. When set, the supplier will be attached to all
> +      root elements of the image SBOM using the ``suppliedBy`` property.
> +
> +      This variable acts as a prefix for a group of sub-variables that together
> +      describe the supplier agent. For example, setting
> +      ``SPDX_IMAGE_SUPPLIER = "SPDX_IMAGE_SUPPLIER"`` enables the following
> +      variables:
> +
> +      - ``SPDX_IMAGE_SUPPLIER_name`` — display name of the supplier
> +      - ``SPDX_IMAGE_SUPPLIER_type`` — agent type (``organization`` or ``person``)
> +
> +      Example::
> +
> +         SPDX_IMAGE_SUPPLIER = "SPDX_IMAGE_SUPPLIER"
> +         SPDX_IMAGE_SUPPLIER_name = "Acme Corp"
> +         SPDX_IMAGE_SUPPLIER_type = "organization"

From this I have a hard time understanding if I'm really supposed to set
SPDX_IMAGE_SUPPLIER to "SPDX_IMAGE_SUPPLIER" (a variable that contains its
variable name as a value)? Why is this needed?

Isn't setting:

SPDX_IMAGE_SUPPLIER_name = "Acme Corp"
SPDX_IMAGE_SUPPLIER_type = "organization"

enough?

Would setting SPDX_IMAGE_SUPPLIER to any other value work?

Maybe I'm missing something! :)

> +
> +      If not set, no supplier information is added to the image SBOM.
> +
> +      See also :term:`SPDX_PACKAGE_SUPPLIER` and :term:`SPDX_SDK_SUPPLIER`.
> +
> +   :term:`SPDX_INVOKED_BY`
> +      The base variable name describing the Agent that invoked the build.
> +      Builds will be linked to this agent if specified. Requires
> +      ``SPDX_INCLUDE_BITBAKE_PARENT_BUILD`` to be set.

"""
Requires :term:`SPDX_INCLUDE_BITBAKE_PARENT_BUILD` to be set to "1".
"""

We would also need a quick description of SPDX_INCLUDE_BITBAKE_PARENT_BUILD in
the glossary, which can be a copy of the class' [doc] flag + references to all
dependent variables (SPDX_ON_BEHALF_OF/SPDX_INVOKED_BY/SPDX_BUILD_HOST. Would
you mind adding it to your patch?

Also, could you provide an example?

> +
> +      .. note::

Reading the sentence below, I'd convert this to a '.. warning::' block.

> +
> +         Setting this variable will likely result in non-reproducible SPDX
> +         output, because the invoking agent identity will vary across builds.
> +
> +      See also :term:`SPDX_ON_BEHALF_OF`.
> +
>     :term:`SPDX_LICENSES`
>        Path to the JSON file containing SPDX license identifier mappings.
>        This file maps common license names to official SPDX license
> @@ -9189,12 +9237,31 @@ system and gives an overview of their function and contents.
>        and the prefix of ``documentNamespace``. It is set by default to
>        ``http://spdx.org/spdxdoc``.
>  
> +   :term:`SPDX_ON_BEHALF_OF`
> +      The base variable name describing the Agent on whose behalf the invoking
> +      Agent (:term:`SPDX_INVOKED_BY`) is running the build. Requires
> +      ``SPDX_INCLUDE_BITBAKE_PARENT_BUILD`` to be set.

Could you provide an example?

> +
> +      .. note::

Again, reading the sentence below, I'd convert this to a '.. warning::' block.

> +
> +         Setting this variable will likely result in non-reproducible SPDX
> +         output.
> +
> +      See also :term:`SPDX_INVOKED_BY`.
> +
>     :term:`SPDX_PACKAGE_URL`
>        Provides a place for the SPDX data creator to record the package URL
>        string (``software_packageUrl``, in accordance with the Package URL
>        specification) for a software Package. The default value of this variable
>        is an empty string.
>  
> +   :term:`SPDX_PACKAGE_SUPPLIER`
> +      The base variable name describing the Agent who supplies the artifacts
> +      produced by the build. Works identically to :term:`SPDX_IMAGE_SUPPLIER`
> +      but applies to individual packages rather than the image SBOM.

One question for me here is: where should I set these variables?

I would guess:

- SPDX_IMAGE_SUPPLIER in the image recipe
- SPDX_PACKAGE_SUPPLIER in any software recipe
- SPDX_SDK_SUPPLIER in the image recipe

?

This would need to be stated in the definitions.

> +
> +      See also :term:`SPDX_IMAGE_SUPPLIER` and :term:`SPDX_SDK_SUPPLIER`.
> +
>     :term:`SPDX_PACKAGE_VERSION`
>        This variable controls the package version as seen in the SPDX 3.0 JSON
>        output (``software_packageVersion``). The default value for this variable
> @@ -9211,6 +9278,17 @@ system and gives an overview of their function and contents.
>        this option is recommended if you want to inspect the SPDX
>        output files with a text editor.
>  
> +   :term:`SPDX_SDK_SUPPLIER`
> +      The base variable name describing the Agent who supplies the SDK SBOM.
> +      When set, the supplier will be attached to all root elements of the SDK
> +      SBOM using the ``suppliedBy`` property.
> +
> +      Works identically to :term:`SPDX_IMAGE_SUPPLIER` but for SDK builds.

You mean image-based SDKs, right? (-c populate_sdk).

You can also build generic SDKs with `bitbake meta-toolchain`. Would that
variable apply to it too?

> +
> +      If not set, no supplier information is added to the SDK SBOM.
> +
> +      See also :term:`SPDX_IMAGE_SUPPLIER` and :term:`SPDX_PACKAGE_SUPPLIER`.
> +
>     :term:`SPDX_UUID_NAMESPACE`
>        The namespace used for generating UUIDs in SPDX documents. This
>        should be a domain name or unique identifier for your organization

Thanks a lot!
Antonin