[PATCH v7] ref-manual: Document SPDX 3.0.1 variables

[stondo@gmail.com]

From: Stefano Tondo <stefano.tondo.ext@siemens.com>

Add comprehensive documentation for SPDX-related variables in the
Yocto reference manual. This includes documenting previously
undocumented variables and updating existing documentation with
SPDX 3.0.1 specific information.

New variables documented:
- SPDX_LICENSES: Path to SPDX license identifier mapping file
- SPDX_MULTILIB_SSTATE_ARCHS: Architecture list for dependency collection
- SPDX_UUID_NAMESPACE: Namespace for UUID generation in SPDX documents

Updated existing variables:
- SPDX_INCLUDE_SOURCES: Added SPDX 3.0.1 format information
- SPDX_INCLUDE_COMPILED_SOURCES: Clarified relationship with SPDX_INCLUDE_SOURCES

Note: The langdale (SPDX 2.2) information was already present in the
documentation. This patch adds corresponding information for SPDX 3.0.1
format based on testing with the master branch.

Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
---
 documentation/ref-manual/variables.rst | 74 ++++++++++++++++++++++++--
 1 file changed, 69 insertions(+), 5 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index f0a99aafb..610090bcc 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -9000,10 +9000,28 @@ system and gives an overview of their function and contents.
 
          SPDX_INCLUDE_COMPILED_SOURCES = "1"
 
-      According to our tests, building ``core-image-minimal`` for the
-      ``qemux86-64`` machine, enabling this option compared with the
-      :term:`SPDX_INCLUDE_SOURCES` reduces the size of the  ``tmp/deploy/spdx``
-      directory from 2GB to 1.6GB.
+      For SPDX 2.2 format (release 4.1 "langdale"), building
+      ``core-image-minimal`` for the ``qemux86-64`` machine, this option
+      reduced the size of the ``tmp/deploy/spdx`` directory from 2GB to
+      1.6GB compared to :term:`SPDX_INCLUDE_SOURCES`, as it includes only
+      compiled objects without original source files.
+
+      With SPDX 3.0.1 JSON format, enabling this option includes both
+      compiled sources and original source files (same as
+      ``SPDX_INCLUDE_SOURCES = "1"``), which significantly increases
+      the SBOM size. For example, with ``core-image-minimal`` on
+      ``qemux86-64``, the uncompressed SBOM file can grow from hundreds
+      of megabytes to several gigabytes.
+
+      .. note::
+
+         SPDX 3.0.1 JSON files are not compressed by default, unlike the
+         tar.zst format used in SPDX 2.2. You can compress the output
+         files manually::
+
+            zstd core-image-minimal-qemux86-64.rootfs.spdx.json
+
+         This typically achieves 94-97% compression ratios.
 
    :term:`SPDX_INCLUDE_SOURCES`
       This option allows to add a description of the source files used to build
@@ -9017,7 +9035,7 @@ system and gives an overview of their function and contents.
 
          SPDX_INCLUDE_SOURCES = "1"
 
-      According to our tests on release 4.1 "langdale", building
+      For SPDX 2.2 format (release 4.1 "langdale"), building
       ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
       this option multiplied the total size of the ``tmp/deploy/spdx``
       directory by a factor of 3  (+291 MiB for this image),
@@ -9026,6 +9044,43 @@ system and gives an overview of their function and contents.
       image), compared to just using the :ref:`ref-classes-create-spdx` class
       with no option.
 
+      With SPDX 3.0.1 JSON format, including source files significantly
+      increases the SBOM size (potentially by several gigabytes for typical
+      images).
+
+      .. note::
+
+         SPDX 3.0.1 JSON files are not compressed by default, unlike the
+         tar.zst format used in SPDX 2.2. You can compress the output
+         files manually::
+
+            zstd core-image-minimal-qemux86-64.rootfs.spdx.json
+
+         This typically achieves 94-97% compression ratios.
+
+   :term:`SPDX_LICENSES`
+      Path to the JSON file containing SPDX license identifier mappings.
+      This file maps common license names to official SPDX license
+      identifiers used during SBOM generation.
+
+      The default value points to a copy of the license mappings defined
+      by SPDX (https://github.com/spdx/license-list-data) stored in
+      :term:`OpenEmbedded-Core (OE-Core)`.
+
+      You can override this variable to use a custom license mapping file
+      if your organization uses different license naming conventions.
+
+   :term:`SPDX_MULTILIB_SSTATE_ARCHS`
+      The list of sstate architectures to consider when collecting SPDX
+      dependencies. This includes multilib architectures when multilib is
+      enabled.
+
+      The default value is set to :term:`SSTATE_ARCHS`.
+
+      This variable is used internally by the SPDX generation classes to
+      ensure all relevant dependencies are included in the SBOM,
+      regardless of whether multilib is enabled or not.
+
    :term:`SPDX_NAMESPACE_PREFIX`
       This option could be used in order to change the prefix of ``spdxDocument``
       and the prefix of ``documentNamespace``. It is set by default to
@@ -9053,6 +9108,15 @@ 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_UUID_NAMESPACE`
+      The namespace used for generating UUIDs in SPDX documents. This
+      should be a domain name or unique identifier for your organization
+      to ensure globally unique SPDX IDs across different builds and
+      organizations.
+
+      The default value is set to a domain managed by the OpenEmbedded
+      project. You can override this to use your organization's domain.
+
    :term:`SPDXLICENSEMAP`
       Maps commonly used license names to their SPDX counterparts found in
       ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP`
-- 
2.51.1