[PATCH 0/2] spdx-common: Documentation and extensibility improvements

[PATCH 0/2] spdx-common: Documentation and extensibility improvements

[Stefano Tondo]

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

This small series improves documentation and extensibility for SPDX
configuration variables in spdx-common.bbclass.

Patch 1: Clarify SPDX_NAMESPACE_PREFIX documentation to recommend
organization-specific namespace prefixes, similar to SPDX_UUID_NAMESPACE.

Patch 2: Make SPDX_LICENSES extensible by supporting a list of license
files. This allows layers to add custom license definitions without
copying the entire oe-core license file. Also improves documentation
for when SPDX_LICENSES needs to be set (non-oe-core licenses).

Stefano Tondo (2):
  spdx-common: Add documentation for undocumented SPDX variables
  spdx-common: Clarify documentation and make SPDX_LICENSES extensible

 meta/classes/spdx-common.bbclass | 31 +++++++++++++++++++++++++++++++
 meta/lib/oe/spdx_common.py       | 31 +++++++++++++++++++++++++++----
 2 files changed, 58 insertions(+), 4 deletions(-)

-- 
2.53.0

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

[Stefano Tondo]

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

Add [doc] strings for eight undocumented SPDX-related BitBake
variables in spdx-common.bbclass.

Variables documented:
- SPDX_INCLUDE_SOURCES
- SPDX_INCLUDE_COMPILED_SOURCES
- SPDX_UUID_NAMESPACE
- SPDX_NAMESPACE_PREFIX
- SPDX_PRETTY
- SPDX_LICENSES
- SPDX_CUSTOM_ANNOTATION_VARS
- SPDX_MULTILIB_SSTATE_ARCHS

This makes variables discoverable via bitbake-getvar and IDE
completion, improving usability for SBOM generation.

Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
Cc: "Ross Burton" <Ross.Burton@arm.com>
---
 meta/classes/spdx-common.bbclass | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/meta/classes/spdx-common.bbclass b/meta/classes/spdx-common.bbclass
index 3110230c9e..b8961262f9 100644
--- a/meta/classes/spdx-common.bbclass
+++ b/meta/classes/spdx-common.bbclass
@@ -26,15 +26,38 @@ 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_CONCLUDED_LICENSE ??= ""
 SPDX_CONCLUDED_LICENSE[doc] = "The license concluded by manual or external \
@@ -53,6 +76,9 @@ SPDX_CONCLUDED_LICENSE[doc] = "The license concluded by manual or external \
     SPDX_CONCLUDED_LICENSE:${PN} = 'MIT & Apache-2.0'"
 
 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
-- 
2.53.0

[PATCH 2/2] spdx-common: Clarify documentation and make SPDX_LICENSES extensible

[Stefano Tondo]

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

This commit improves the SPDX variable documentation and enhances
SPDX_LICENSES to support layer-based license extensions.

1. SPDX_NAMESPACE_PREFIX documentation clarification:
   - Clarify that this should be organization-specific
   - Explain the default is for compatibility only
   - Provide example of production override
   - Make it consistent with SPDX_UUID_NAMESPACE guidance

2. SPDX_LICENSES documentation enhancement:
   - Clarify when this variable needs to be set
   - Document the new list behavior
   - Provide example usage with += operator

3. SPDX_LICENSES implementation as extensible list:
   - Change from single file to space-separated list of files
   - Support layer-based license extensions without file copying
   - Later files override earlier ones for duplicate license IDs
   - Backward compatible (single file path still works)
   - Add error handling for missing/invalid files

This enhancement allows layers to add custom licenses without
maintaining a copy of the base spdx-licenses.json file:

  SPDX_LICENSES += "${LAYERDIR}/files/custom-licenses.json"

This is particularly useful for organizations with proprietary or
custom licenses that need to be tracked in SBOMs.

Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
Cc: "Ross Burton" <Ross.Burton@arm.com>
---
 meta/classes/spdx-common.bbclass | 13 +++++++++----
 meta/lib/oe/spdx_common.py       | 31 +++++++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/meta/classes/spdx-common.bbclass b/meta/classes/spdx-common.bbclass
index b8961262f9..024f24c837 100644
--- a/meta/classes/spdx-common.bbclass
+++ b/meta/classes/spdx-common.bbclass
@@ -42,7 +42,10 @@ SPDX_UUID_NAMESPACE[doc] = "The namespace used for generating UUIDs in SPDX \
 
 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."
+    This should be a domain name or URI prefix unique to your organization to ensure \
+    globally unique document URIs. The default 'http://spdx.org/spdxdocs' is provided \
+    for compatibility but should be overridden in production environments (e.g., \
+    'https://sbom.example.com')."
 
 SPDX_PRETTY ??= "0"
 SPDX_PRETTY[doc] = "If set to '1', generate human-readable formatted JSON output \
@@ -50,9 +53,11 @@ SPDX_PRETTY[doc] = "If set to '1', generate human-readable formatted 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_LICENSES[doc] = "Space-separated list of JSON files containing SPDX license \
+    identifier mappings. Files are processed in order, with later entries overriding \
+    earlier ones. This allows layers to extend the base license set without copying \
+    the entire file. Set this variable in your layer when using licenses not known \
+    to oe-core (e.g., 'SPDX_LICENSES += \"${LAYERDIR}/files/custom-licenses.json\"')."
 
 SPDX_CUSTOM_ANNOTATION_VARS ??= ""
 SPDX_CUSTOM_ANNOTATION_VARS[doc] = "Space-separated list of variable names whose \
diff --git a/meta/lib/oe/spdx_common.py b/meta/lib/oe/spdx_common.py
index 72c24180d5..8a6cf70fc1 100644
--- a/meta/lib/oe/spdx_common.py
+++ b/meta/lib/oe/spdx_common.py
@@ -42,10 +42,33 @@ def is_work_shared_spdx(d):
 
 
 def load_spdx_license_data(d):
-    with open(d.getVar("SPDX_LICENSES"), "r") as f:
-        data = json.load(f)
-        # Transform the license array to a dictionary
-        data["licenses"] = {l["licenseId"]: l for l in data["licenses"]}
+    """
+    Load SPDX license data from one or more JSON files.
+    SPDX_LICENSES can be a space-separated list of files.
+    Later files override earlier ones for duplicate license IDs.
+    """
+    license_files = d.getVar("SPDX_LICENSES").split()
+
+    # Initialize with empty structure
+    data = {"licenses": {}}
+
+    # Load and merge each file
+    for license_file in license_files:
+        try:
+            with open(license_file, "r") as f:
+                file_data = json.load(f)
+                # Transform the license array to a dictionary and merge
+                if "licenses" in file_data:
+                    for lic in file_data["licenses"]:
+                        data["licenses"][lic["licenseId"]] = lic
+                # Copy over other top-level keys from the last file
+                for key in file_data:
+                    if key != "licenses":
+                        data[key] = file_data[key]
+        except FileNotFoundError:
+            bb.warn(f"SPDX license file not found: {license_file}")
+        except json.JSONDecodeError as e:
+            bb.warn(f"Invalid JSON in SPDX license file {license_file}: {e}")
 
     return data
 
-- 
2.53.0

Re: [PATCH 2/2] spdx-common: Clarify documentation and make SPDX_LICENSES extensible

[Joshua Watt]

[-- Attachment #1: Type: text/plain, Size: 5781 bytes --]

On Fri, Feb 20, 2026, 9:25 PM Stefano Tondo <stondo@gmail.com> wrote:

> From: Stefano Tondo <stefano.tondo.ext@siemens.com>
>
> This commit improves the SPDX variable documentation and enhances
> SPDX_LICENSES to support layer-based license extensions.
>

Sorry, you can't do this. The spdx license list is specified by spdx, not
us. If you have licenses that are not on the list, the LicenseRef code
should take care of adding their text, but you can't just invent new spdx
license IDs for your licenses


> 1. SPDX_NAMESPACE_PREFIX documentation clarification:
>    - Clarify that this should be organization-specific
>    - Explain the default is for compatibility only
>    - Provide example of production override
>    - Make it consistent with SPDX_UUID_NAMESPACE guidance
>
> 2. SPDX_LICENSES documentation enhancement:
>    - Clarify when this variable needs to be set
>    - Document the new list behavior
>    - Provide example usage with += operator
>
> 3. SPDX_LICENSES implementation as extensible list:
>    - Change from single file to space-separated list of files
>    - Support layer-based license extensions without file copying
>    - Later files override earlier ones for duplicate license IDs
>    - Backward compatible (single file path still works)
>    - Add error handling for missing/invalid files
>
> This enhancement allows layers to add custom licenses without
> maintaining a copy of the base spdx-licenses.json file:
>
>   SPDX_LICENSES += "${LAYERDIR}/files/custom-licenses.json"
>
> This is particularly useful for organizations with proprietary or
> custom licenses that need to be tracked in SBOMs.
>
> Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
> Cc: "Ross Burton" <Ross.Burton@arm.com>
> ---
>  meta/classes/spdx-common.bbclass | 13 +++++++++----
>  meta/lib/oe/spdx_common.py       | 31 +++++++++++++++++++++++++++----
>  2 files changed, 36 insertions(+), 8 deletions(-)
>
> diff --git a/meta/classes/spdx-common.bbclass
> b/meta/classes/spdx-common.bbclass
> index b8961262f9..024f24c837 100644
> --- a/meta/classes/spdx-common.bbclass
> +++ b/meta/classes/spdx-common.bbclass
> @@ -42,7 +42,10 @@ SPDX_UUID_NAMESPACE[doc] = "The namespace used for
> generating UUIDs in SPDX \
>
>  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."
> +    This should be a domain name or URI prefix unique to your
> organization to ensure \
> +    globally unique document URIs. The default 'http://spdx.org/spdxdocs'
> is provided \
> +    for compatibility but should be overridden in production environments
> (e.g., \
> +    'https://sbom.example.com')."
>
>  SPDX_PRETTY ??= "0"
>  SPDX_PRETTY[doc] = "If set to '1', generate human-readable formatted JSON
> output \
> @@ -50,9 +53,11 @@ SPDX_PRETTY[doc] = "If set to '1', generate
> human-readable formatted 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_LICENSES[doc] = "Space-separated list of JSON files containing SPDX
> license \
> +    identifier mappings. Files are processed in order, with later entries
> overriding \
> +    earlier ones. This allows layers to extend the base license set
> without copying \
> +    the entire file. Set this variable in your layer when using licenses
> not known \
> +    to oe-core (e.g., 'SPDX_LICENSES +=
> \"${LAYERDIR}/files/custom-licenses.json\"')."
>
>  SPDX_CUSTOM_ANNOTATION_VARS ??= ""
>  SPDX_CUSTOM_ANNOTATION_VARS[doc] = "Space-separated list of variable
> names whose \
> diff --git a/meta/lib/oe/spdx_common.py b/meta/lib/oe/spdx_common.py
> index 72c24180d5..8a6cf70fc1 100644
> --- a/meta/lib/oe/spdx_common.py
> +++ b/meta/lib/oe/spdx_common.py
> @@ -42,10 +42,33 @@ def is_work_shared_spdx(d):
>
>
>  def load_spdx_license_data(d):
> -    with open(d.getVar("SPDX_LICENSES"), "r") as f:
> -        data = json.load(f)
> -        # Transform the license array to a dictionary
> -        data["licenses"] = {l["licenseId"]: l for l in data["licenses"]}
> +    """
> +    Load SPDX license data from one or more JSON files.
> +    SPDX_LICENSES can be a space-separated list of files.
> +    Later files override earlier ones for duplicate license IDs.
> +    """
> +    license_files = d.getVar("SPDX_LICENSES").split()
> +
> +    # Initialize with empty structure
> +    data = {"licenses": {}}
> +
> +    # Load and merge each file
> +    for license_file in license_files:
> +        try:
> +            with open(license_file, "r") as f:
> +                file_data = json.load(f)
> +                # Transform the license array to a dictionary and merge
> +                if "licenses" in file_data:
> +                    for lic in file_data["licenses"]:
> +                        data["licenses"][lic["licenseId"]] = lic
> +                # Copy over other top-level keys from the last file
> +                for key in file_data:
> +                    if key != "licenses":
> +                        data[key] = file_data[key]
> +        except FileNotFoundError:
> +            bb.warn(f"SPDX license file not found: {license_file}")
> +        except json.JSONDecodeError as e:
> +            bb.warn(f"Invalid JSON in SPDX license file {license_file}:
> {e}")
>
>      return data
>
> --
> 2.53.0
>
>

[-- Attachment #2: Type: text/html, Size: 7605 bytes --]