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

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

[stondo]

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 | 77 ++++++++++++++++++++++++--
 1 file changed, 72 insertions(+), 5 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index f0a99aafb..8e2a4d8f3 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,55 @@ 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 +9120,16 @@ 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

Re: [docs] [PATCH v6] ref-manual: Document SPDX 3.0.1 variables

[Antonin Godard]

Hi,

I still can't apply the patch :(

Patch failed at 0001 ref-manual: Document SPDX 3.0.1 variables
error: corrupt patch at line 95
error: could not build fake ancestor

See my other comments below otherwise.

On Tue Nov 25, 2025 at 2:52 PM CET, Stefano Tondo via lists.yoctoproject.org wrote:
> 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 | 77 ++++++++++++++++++++++++--
>  1 file changed, 72 insertions(+), 5 deletions(-)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index f0a99aafb..8e2a4d8f3 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.

Sorry, my previous comment was probably not clear. I thought you used a
*built-in* way to compress the resulting JSON file and that it would be worth
mentioning it here.

So I would remove this note, and perhaps contribute to OE-Core to add support
for compression of this file, and then document that (if it doesn't exist
already).

Thanks,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com