documentation: Add comprehensive SPDX variable documentation
PATCH v3 1/1 documentation: Add comprehensive SPDX variable documentation
From: Stefano Tondo <[email protected]>
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 with SPDX 3.0.1 data:
- SPDX_INCLUDE_SOURCES: Documented distributed architecture behavior
- SPDX_INCLUDE_COMPILED_SOURCES: Updated with SPDX 3.0.1 format information
Testing on core-image-minimal for qemux86-64 with SPDX 3.0.1 shows that the rootfs SBOM file is approximately 5-6 MB regardless of source inclusion settings. This is due to SPDX 3.0.1's distributed architecture where per-package SPDX documents are stored in tmp/deploy/spdx/ (~130 MB), while the rootfs SBOM contains only relationships and references.
Note: SPDX 3.0.1 JSON files are not compressed by default, unlike the tar.zst compression used in SPDX 2.2. Manual compression with zstd typically achieves 94-97% file size reduction.
These variables are defined in meta/classes/spdx-common.bbclass.
---
Changes in v3:
- Fixed terminology: Changed "JSON-LD" to "JSON" throughout for clarity
- Removed untested SPDX_INCLUDE_COMPILED_SOURCES size claims for SPDX 3.0.1
- Converted note paragraphs to proper RST ".. note::" blocks
- Added concrete compression instructions with zstd command
- Replaced hardcoded variable values with generic descriptions
- Added compression ratio data (94-97% reduction with zstd)
- Linked SPDX_LICENSES to upstream SPDX license-list-data repository
Changes in v2:
- Fixed unintended removal of non-SPDX variables (CCACHE_DISABLE, IMAGE_EXTRA_PARTITION_FILES, REQUIRED_*_FEATURES)
- Fixed unintended change to LAYERDEPENDS description
- Only SPDX-related variables are now modified
documentation/ref-manual/variables.rst | 77 ++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 10 deletions(-)
documentation/ref-manual/variables.rst +65 -6
@@ -8962,10 +8962,18 @@ 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. + According to our tests on release 4.1 "langdale", building + ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this + option compared with the :term:`SPDX_INCLUDE_SOURCES` reduced the size + of the ``tmp/deploy/spdx`` directory from 2GB to 1.6GB. + + .. note:: + + The above measurements are for SPDX 2.2 format. Size characteristics + may differ with SPDX 3.0.1 JSON format. The key benefit of this option + is including only compiled files (object files, binaries) rather than + all source code, which reduces the amount of data while still providing + information about build artifacts. :term:`SPDX_INCLUDE_SOURCES` This option allows to add a description of the source files used to build
@@ -8979,8 +8987,8 @@ system and gives an overview of their function and contents. SPDX_INCLUDE_SOURCES = "1" - According to our tests on release 4.1 "langdale", building - ``core-image-minimal`` for the ``qemux86-64`` machine, enabling + According to our tests on release 4.1 "langdale" (SPDX 2.2 format), + 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), and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in
@@ -8988,6 +8996,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, the uncompressed rootfs SBOM file + (``core-image-minimal-qemux86-64.rootfs.spdx.json``) is approximately + **5-6 MB regardless of source inclusion settings**. Unlike SPDX 2.2, + the SPDX 3.0.1 implementation uses a distributed architecture where + per-package SPDX documents are stored in ``tmp/deploy/spdx/`` + (~130 MB for core-image-minimal), while the rootfs SBOM contains + only relationships and references to these package documents. + + .. note:: + + SPDX 3.0.1 JSON files are not compressed by default, unlike the + tar.zst format used in SPDX 2.2. To reduce file size, compress the + files manually using ``zstd``:: + + zstd core-image-minimal-qemux86-64.rootfs.spdx.json + + This typically reduces file size by 94-97%. For example, a 5.4 MB + SBOM compresses to ~350 KB. + + :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)`. + + For additional information, see the :term:`LICENSE` and + :term:`SPDXLICENSEMAP` variables. + + :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`, which automatically + includes all relevant architectures for the current build configuration. + + This variable is used internally by the SPDX generation process and + typically does not need to be modified. + + :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. + + The default value is set to the OpenEmbedded project namespace. If you + are generating SBOMs for your own organization, set this to your own + domain name (e.g., ``SPDX_UUID_NAMESPACE = "sbom.example.com"``). + :term:`SPDX_NAMESPACE_PREFIX`
This variable allows to set a custom namespace prefix in the SPDX output. The default is "http://spdx.org/spdxdocs".
Signature · 1 line
2.51.1
Hi,
This was sent to the wrong list and should be sent to [email protected].
I'm also struggling to apply the patch:
Applying: documentation: Add comprehensive SPDX variable documentation
error: corrupt patch at line 118
error: could not build fake ancestor
Patch failed at 0001 documentation: Add comprehensive SPDX variable documentation
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Can you check?
Thanks,
Antonin
Signature · 3 lines
Antonin Godard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Hi Antonin,
Sorry for the troubles.
I've now addressed v4 to [email protected]
The v3 patch had formatting issues. I've regenerated it from a clean rebase on the latest master branch.
The v4 patch:
- Applies cleanly to current yocto-docs master (tested with git am)
- Rebased on latest master (bcb6a7c8a)
- Same content as v3, just properly formatted
I'll send v4 to [email protected] shortly.
Thanks again for catching this!
Best regards,
Stefano
________________________________
From: Antonin Godard <[email protected]>
Sent: Tuesday, November 25, 2025 09:38
To: Stefano Tondo <[email protected]>; [email protected] <[email protected]>
Cc: Marko, Peter (FT D EU SK BFS1) <[email protected]>; Freihofer, Adrian (SI B PRO TI EAC CCP) <[email protected]>; Tondo, Stefano (ext) (SI B PRO AUT PD ZUG SW 2) <[email protected]>
Subject: Re: [OE-core][PATCH v3] documentation: Add comprehensive SPDX variable documentation
[You don't often get email from [email protected]. Learn why this is important at https://aka.ms/LearnAboutSenderIdentification ]
Hi,
This was sent to the wrong list and should be sent to [email protected].
I'm also struggling to apply the patch:
Applying: documentation: Add comprehensive SPDX variable documentation
error: corrupt patch at line 118
error: could not build fake ancestor
Patch failed at 0001 documentation: Add comprehensive SPDX variable documentation
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config set advice.mergeConflict false"
Can you check?
Thanks,
Antonin
--
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://eur01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbootlin.com%2F&data=05%7C02%7Cstefano.tondo.ext%40siemens.com%7C8a0d15d7ce75402075db08de2bfe05e9%7C38ae3bcd95794fd4addab42e1495d55a%7C1%7C0%7C638996567198621877%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=K0tlXq9jj%2BAZKbLB0o51Uxk0uhN759%2FrvvGrzyQ23Oc%3D&reserved=0<https://bootlin.com/>