[docs][PATCH] 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_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.
+
 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
+      ``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"
+
+      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.
+
+      .. note::
+
+         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.
+
+      .. note::
+
+         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.
+
+      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.
+
+      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