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

[stondo@gmail.com]

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
+      representing the parent bitbake invocation. This allows consumers of the
+      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
+      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
+      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
+      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
+      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
+         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``.
+
+      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
-- 
2.53.0