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. Signed-off-by: Stefano Tondo <[email protected]> --- 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(-) diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index a80ef364e..f2c8a1d9a 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -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";. -- 2.51.1
-=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#226747): https://lists.openembedded.org/g/openembedded-core/message/226747 Mute This Topic: https://lists.openembedded.org/mt/116459716/21656 Group Owner: [email protected] Unsubscribe: https://lists.openembedded.org/g/openembedded-core/unsub [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
