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

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

Hi,

On Fri Mar 20, 2026 at 1:56 PM CET, stondo 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_INCLUDE_BITBAKE_PARENT_BUILD: enable parent build tracking
> - 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, ecosystem-specific PURL enrichment via bbclasses
>   (cargo_common, go-mod, pypi, npm, cpan), and build invocation
>   traceability (SPDX_INVOKED_BY/SPDX_ON_BEHALF_OF)
>
> Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
> ---
> Changes in v2:
> - SPDX_FILE_EXCLUDE_PATTERNS: clarify it only applies when
>   SPDX_INCLUDE_SOURCES is enabled (Antonin)
> - SPDX_INCLUDE_BITBAKE_PARENT_BUILD: add new glossary entry (Antonin)
> - SPDX_IMAGE_SUPPLIER: rewrite to explain the agent PREFIX mechanism
>   clearly, add shared-prefix example, state where to set it (Antonin)
> - SPDX_INVOKED_BY: use :term: reference for SPDX_INCLUDE_BITBAKE_PARENT_BUILD,
>   add CI pipeline example, convert note to warning (Antonin)
> - SPDX_ON_BEHALF_OF: add full example, convert note to warning (Antonin)
> - SPDX_PACKAGE_SUPPLIER: state where to set it (local.conf / recipe) (Antonin)
> - SPDX_SDK_SUPPLIER: clarify it applies to both populate_sdk and
>   meta-toolchain (Antonin)
> - dev-manual/sbom.rst: add bullet for build invocation traceability (Antonin)
>
>  documentation/dev-manual/sbom.rst      |  18 +++
>  documentation/ref-manual/variables.rst | 163 +++++++++++++++++++++++++
>  2 files changed, 181 insertions(+)
>
> diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst
> index 95303ed..e0c3ed6 100644
> --- a/documentation/dev-manual/sbom.rst
> +++ b/documentation/dev-manual/sbom.rst
> @@ -64,6 +64,24 @@ 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.
> +
> +-  Record which agent invoked the build and on whose behalf it ran, enabling
> +   CI/CD traceability in the SBOM
> +   (:term:`SPDX_INCLUDE_BITBAKE_PARENT_BUILD`, :term:`SPDX_INVOKED_BY`,
> +   :term:`SPDX_ON_BEHALF_OF`).
> +
>  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..84715af 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -9063,6 +9063,41 @@ 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 when :term:`SPDX_INCLUDE_SOURCES` is enabled.
> +      Files whose paths match any of the patterns (via ``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_BITBAKE_PARENT_BUILD`
> +      When set to ``"1"``, the SPDX output will include a :term:`Build` object

:term:`Build` is not a valid term (valid terms are in
documentation/ref-manual/terms.rst). I think ``Build`` would be more appropriate
here instead.

> +      representing the parent bitbake invocation. This allows consumers of the

s/bitbake/:term:`BitBake`/

> +      SBOM to trace which CI/CD job or orchestration system triggered the build.
> +
> +      This variable is required for :term:`SPDX_INVOKED_BY`,
> +      :term:`SPDX_ON_BEHALF_OF`, and :term:`SPDX_BUILD_HOST` to have any

SPDX_BUILD_HOST is not documented so this creates a docs build error:

/data/yoctoproject/ws/repos/yocto-docs/documentation/ref-manual/variables.rst:9080: WARNING: term not in glossary: 'SPDX_BUILD_HOST' [ref.term]
/data/yoctoproject/ws/repos/yocto-docs/documentation/ref-manual/variables.rst:9093: WARNING: term not in glossary: 'SPDX_BUILD_HOST' [ref.term]

Could you include a definition for it in this patch?

> +      effect.
> +
> +      .. warning::
> +
> +         Enabling this variable will result in non-reproducible SPDX output,
> +         because the build invocation identity changes with every run.
> +
> +      Enable as follows::
> +
> +         SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
> +
> +      See also :term:`SPDX_INVOKED_BY`, :term:`SPDX_ON_BEHALF_OF`,
> +      :term:`SPDX_BUILD_HOST`.
> +
>     :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 +9196,72 @@ 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 name of an agent variable prefix describing the organization or
> +      person who supplies the image SBOM. When set, the supplier is attached
> +      to all root elements of the image SBOM using the ``suppliedBy`` property.
> +
> +      The value of this variable is the BASE PREFIX used to look up the
> +      agent's details. The following sub-variables are read using that prefix:
> +
> +      - ``<PREFIX>_name`` — display name of the supplier (required)
> +      - ``<PREFIX>_type`` — agent type: ``organization``, ``person``,
> +        ``software``, or ``agent`` (optional, defaults to ``agent``)
> +      - ``<PREFIX>_comment`` — free-text comment (optional)
> +      - ``<PREFIX>_id_email`` — contact e-mail address (optional)
> +
> +      The simplest approach is to use the variable itself as its own prefix
> +      (set it to its own name), so that the sub-variable names follow
> +      directly from ``SPDX_IMAGE_SUPPLIER``:
> +
> +      Example (set in the image recipe or in ``local.conf``):: 
> +
> +         SPDX_IMAGE_SUPPLIER = "SPDX_IMAGE_SUPPLIER"
> +         SPDX_IMAGE_SUPPLIER_name = "Acme Corp"
> +         SPDX_IMAGE_SUPPLIER_type = "organization"
> +
> +      Alternatively, you can use any other prefix name, which is useful for
> +      sharing an agent definition across multiple supplier variables::
> +
> +         MY_COMPANY_name = "Acme Corp"
> +         MY_COMPANY_type = "organization"
> +         SPDX_IMAGE_SUPPLIER = "MY_COMPANY"
> +         SPDX_SDK_SUPPLIER   = "MY_COMPANY"
> +
> +      Typically set in the image recipe or in ``local.conf`` to apply it to

s/in ``local.conf``/in a :term:`configuration file`/

> +      all images.
> +
> +      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.
> +      Each Build object in the SPDX output will be linked to this agent

s/Build/``Build``/

> +      with an ``invokedBy`` relationship. Requires
> +      :term:`SPDX_INCLUDE_BITBAKE_PARENT_BUILD` to be set to ``"1"``.
> +
> +      The sub-variables follow the same agent prefix convention as
> +      :term:`SPDX_IMAGE_SUPPLIER`:
> +
> +      - ``SPDX_INVOKED_BY_name`` — display name of the invoking agent
> +      - ``SPDX_INVOKED_BY_type`` — agent type (e.g. ``software`` for a CI system)
> +
> +      Example (CI pipeline invoking the build)::
> +
> +         SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
> +         SPDX_INVOKED_BY = "SPDX_INVOKED_BY"
> +         SPDX_INVOKED_BY_name = "GitLab CI"
> +         SPDX_INVOKED_BY_type = "software"
> +
> +      .. warning::
> +
> +         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_INCLUDE_BITBAKE_PARENT_BUILD`.
> +
>     :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 +9290,58 @@ 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
> +      :term:`SPDX_INCLUDE_BITBAKE_PARENT_BUILD` to be set to ``"1"``.
> +      Has no effect if :term:`SPDX_INVOKED_BY` is not also set.
> +
> +      The sub-variables follow the same agent prefix convention as
> +      :term:`SPDX_IMAGE_SUPPLIER`:
> +
> +      - ``SPDX_ON_BEHALF_OF_name`` — display name of the commissioning agent
> +      - ``SPDX_ON_BEHALF_OF_type`` — agent type (e.g. ``organization``)
> +
> +      Example (CI system building on behalf of a customer organization)::
> +
> +         SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
> +         SPDX_INVOKED_BY = "SPDX_INVOKED_BY"
> +         SPDX_INVOKED_BY_name = "GitLab CI"
> +         SPDX_INVOKED_BY_type = "software"
> +         SPDX_ON_BEHALF_OF = "SPDX_ON_BEHALF_OF"
> +         SPDX_ON_BEHALF_OF_name = "Acme Corp"
> +         SPDX_ON_BEHALF_OF_type = "organization"
> +
> +      .. warning::
> +
> +         Setting this variable will likely result in non-reproducible SPDX
> +         output, because the agent identity will vary across builds.
> +
> +      See also :term:`SPDX_INVOKED_BY`,
> +      :term:`SPDX_INCLUDE_BITBAKE_PARENT_BUILD`.
> +
>     :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.
> +
> +      Typically set in ``local.conf`` to apply globally to all packages, or

s/in ``local.conf``/in a :term:`configuration file`/

> +      in a specific software recipe (or a ``.bbappend``) to apply only to
> +      packages of that recipe. Recipe-level overrides (``SPDX_PACKAGE_SUPPLIER:pn-<recipe>``) are also supported::
> +
> +         # local.conf — apply to all packages

s/local.conf/distro configuration file/

(we try to encourage not to use local.conf for such things and instead encourage
distro configuration files etc.)

> +         SPDX_PACKAGE_SUPPLIER = "SPDX_PACKAGE_SUPPLIER"
> +         SPDX_PACKAGE_SUPPLIER_name = "Acme Corp"
> +         SPDX_PACKAGE_SUPPLIER_type = "organization"
> +
> +      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 +9358,22 @@ 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 is attached to all root elements of the SDK
> +      SBOM using the ``suppliedBy`` property.
> +
> +      Works identically to :term:`SPDX_IMAGE_SUPPLIER` but applies to SDK
> +      builds. This includes image-based SDKs produced by
> +      ``bitbake <image> -c populate_sdk`` as well as toolchain SDKs produced
> +      by ``bitbake meta-toolchain``.
> +
> +      Typically set in the image recipe or in ``local.conf``.

s/in ``local.conf``/in a :term:`configuration file`/

> +
> +      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

Also there is a bit of an ordering issue in variable.rst:

./tools/check-glossaries --docs-dir .
WARNING: ref-manual/variables.rst: entries are not properly sorted:
--- original_list
+++ sorted_list
@@ -712,19 +712,19 @@

 SPDX_ARCHIVE_SOURCES
 SPDX_CUSTOM_ANNOTATION_VARS
 SPDX_FILE_EXCLUDE_PATTERNS
+SPDX_IMAGE_SUPPLIER
 SPDX_INCLUDE_BITBAKE_PARENT_BUILD
 SPDX_INCLUDE_COMPILED_SOURCES
 SPDX_INCLUDE_KERNEL_CONFIG
 SPDX_INCLUDE_PACKAGECONFIG
 SPDX_INCLUDE_SOURCES
-SPDX_IMAGE_SUPPLIER
 SPDX_INVOKED_BY
 SPDX_LICENSES
 SPDX_MULTILIB_SSTATE_ARCHS
 SPDX_NAMESPACE_PREFIX
 SPDX_ON_BEHALF_OF
+SPDX_PACKAGE_SUPPLIER
 SPDX_PACKAGE_URL
-SPDX_PACKAGE_SUPPLIER
 SPDX_PACKAGE_VERSION
 SPDX_PRETTY
 SPDX_SDK_SUPPLIER


Thanks again, this is looking great!
Antonin