Skip to contentSkip to conversation

SPDX 3.0.1 documentation and bugfix

PATCH Superseded Stefano Tondo 1 participant 3 messages Nov 13, 2025

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover SPDX 3.0.1 documentation and bugfix

From: Stefano Tondo <[email protected]>

This series adds documentation for undocumented SPDX variables and fixes a critical bug in the custom annotations feature.

Patch 1/2: Fixes NameError in SPDX_CUSTOM_ANNOTATION_VARS feature by
correcting method call syntax. Adds regression test to prevent future occurrences.

Patch 2/2: Adds [doc] strings for 8 SPDX variables in spdx-common.bbclass.
Makes variables discoverable via bitbake-getvar and IDE completion.

Note: A companion patch for yocto-docs will add three of these variables to the reference manual (SPDX_UUID_NAMESPACE, SPDX_LICENSES, and SPDX_MULTILIB_SSTATE_ARCHS).

Both patches have been tested with core-image-minimal builds.

Stefano Tondo (2):
spdx30_tasks: Fix SPDX_CUSTOM_ANNOTATION_VARS implementation
spdx-common: Add documentation for undocumented SPDX variables

 meta/classes/spdx-common.bbclass     | 26 ++++++++++
 meta/lib/oe/spdx30_tasks.py          |  4 +-
 meta/lib/oeqa/selftest/cases/spdx.py | 74 ++++++++++++++++++++++++++++
 3 files changed, 101 insertions(+), 3 deletions(-)
Signature · 1 line
2.51.1
#1 lore raw

PATCH 1/2 spdx30_tasks: Fix SPDX_CUSTOM_ANNOTATION_VARS implementation

From: Stefano Tondo <[email protected]>

Fix incorrect function call when processing SPDX_CUSTOM_ANNOTATION_VARS. The code was calling new_annotation() as a standalone function, but it should be called as a method on the build_objset object.

Error:
new_annotation(d, build_objset, build, ...)

Corrected to:
build_objset.new_annotation(d, build_objset, build, ...)

This bug would cause a NameError at runtime if SPDX_CUSTOM_ANNOTATION_VARS was set to a non-empty value, preventing SPDX document generation.

The fix aligns with how new_annotation() is called elsewhere in the codebase and matches the SBOMObjset class method signature.

---
 meta/lib/oe/spdx30_tasks.py          |  4 +-
 meta/lib/oeqa/selftest/cases/spdx.py | 74 ++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 3 deletions(-)
meta/lib/oe/spdx30_tasks.py +1 -3
index f2f133005d..4d11b3c289 100644
@@ -498,9 +498,7 @@ def create_spdx(d):
     build_objset.set_is_native(is_native)
 
     for var in (d.getVar("SPDX_CUSTOM_ANNOTATION_VARS") or "").split():
-        new_annotation(
-            d,
-            build_objset,
+        build_objset.new_annotation(
             build,
             "%s=%s" % (var, d.getVar(var)),
             oe.spdx30.AnnotationType.other,
meta/lib/oeqa/selftest/cases/spdx.py +74 -0

77 lines not on this page · raw message

Signature · 1 line
2.51.1
#2 lore raw

PATCH 2/2 spdx-common: Add documentation for undocumented SPDX variables

In reply to Stefano Tondo

From: Stefano Tondo <[email protected]>

Add missing [doc] strings for seven SPDX-related BitBake variables that were previously undocumented in the spdx-common bbclass.

Variables documented:
- SPDX_INCLUDE_SOURCES: Control source file inclusion in SBOM
- SPDX_INCLUDE_COMPILED_SOURCES: Control compiled source inclusion
- SPDX_UUID_NAMESPACE: Namespace for UUID generation
- SPDX_NAMESPACE_PREFIX: URI prefix for SPDX documents
- SPDX_PRETTY: JSON output formatting control
- SPDX_LICENSES: Path to SPDX license mapping file
- SPDX_CUSTOM_ANNOTATION_VARS: Custom annotation variables
- SPDX_MULTILIB_SSTATE_ARCHS: Multilib sstate architecture list

This improves discoverability of these configuration options and helps users understand how to customize SPDX/SBOM generation.

---
 meta/classes/spdx-common.bbclass | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
meta/classes/spdx-common.bbclass +26 -0
index ca0416d1c7..6bd1b56d96 100644
@@ -26,17 +26,43 @@ SPDX_TOOL_VERSION ??= "1.0"
 SPDXRUNTIMEDEPLOY = "${SPDXDIR}/runtime-deploy"
 
 SPDX_INCLUDE_SOURCES ??= "0"
+SPDX_INCLUDE_SOURCES[doc] = "If set to '1', include source code files in the \
+    SPDX output. This will create File objects for all source files used during \
+    the build. Note: This significantly increases SBOM size and generation time."
+
 SPDX_INCLUDE_COMPILED_SOURCES ??= "0"
+SPDX_INCLUDE_COMPILED_SOURCES[doc] = "If set to '1', include compiled source \
+    files (object files, etc.) in the SPDX output. This automatically enables \
+    SPDX_INCLUDE_SOURCES. Note: This significantly increases SBOM size."
 
 SPDX_UUID_NAMESPACE ??= "sbom.openembedded.org"
+SPDX_UUID_NAMESPACE[doc] = "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."
+
 SPDX_NAMESPACE_PREFIX ??= "http://spdx.org/spdxdocs"
+SPDX_NAMESPACE_PREFIX[doc] = "The URI prefix used for SPDX document namespaces. \
+    Combined with other identifiers to create unique document URIs."
+
 SPDX_PRETTY ??= "0"
+SPDX_PRETTY[doc] = "If set to '1', generate human-readable formatted JSON output \
+    with indentation and line breaks. If '0', generate compact JSON output. \
+    Pretty formatting makes files larger but easier to read."
 
 SPDX_LICENSES ??= "${COREBASE}/meta/files/spdx-licenses.json"
+SPDX_LICENSES[doc] = "Path to the JSON file containing SPDX license identifier \
+    mappings. This file maps common license names to official SPDX license \
+    identifiers."
 
 SPDX_CUSTOM_ANNOTATION_VARS ??= ""
+SPDX_CUSTOM_ANNOTATION_VARS[doc] = "Space-separated list of variable names whose \
+    values will be added as custom annotations to SPDX documents. Each variable's \
+    name and value will be recorded as an annotation for traceability."
 
 SPDX_MULTILIB_SSTATE_ARCHS ??= "${SSTATE_ARCHS}"
+SPDX_MULTILIB_SSTATE_ARCHS[doc] = "The list of sstate architectures to consider \
+    when collecting SPDX dependencies. This includes multilib architectures when \
+    multilib is enabled. Defaults to SSTATE_ARCHS."
 
 python () {
     from oe.cve_check import extend_cve_status
Signature · 1 line
2.51.1