1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Creating a Software Bill of Materials 4************************************* 5 6Once you are able to build an image for your project, once the licenses for 7each software component are all identified (see 8":ref:`dev-manual/licenses:working with licenses`") and once vulnerability 9fixes are applied (see ":ref:`dev-manual/vulnerabilities:checking 10for vulnerabilities`"), the OpenEmbedded build system can generate 11a description of all the components you used, their licenses, their dependencies, 12their sources, the changes that were applied to them and the known 13vulnerabilities that were fixed. 14 15This description is generated in the form of a *Software Bill of Materials* 16(:term:`SBOM`), using the :term:`SPDX` standard. 17 18When you release software, this is the most standard way to provide information 19about the Software Supply Chain of your software image and SDK. The 20:term:`SBOM` tooling is often used to ensure open source license compliance by 21providing the license texts used in the product which legal departments and end 22users can read in standardized format. 23 24:term:`SBOM` information is also critical to performing vulnerability exposure 25assessments, as all the components used in the Software Supply Chain are listed. 26 27The OpenEmbedded build system doesn't generate such information by default, 28though the :term:`Poky` reference distribution has it enabled out of the box. 29 30To enable it, inherit the :ref:`ref-classes-create-spdx` class from a 31configuration file:: 32 33 INHERIT += "create-spdx" 34 35In the :term:`Poky` reference distribution, :term:`SPDX` generation does 36consume some build time resources and thus if needed it can be disabled from a 37:term:`configuration file`:: 38 39 INHERIT:remove = "create-spdx" 40 41Upon building an image, you will then get: 42 43- :term:`SPDX` output in JSON format as an ``IMAGE-MACHINE.spdx.json`` file in 44 ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`. 45 46- This toplevel file is accompanied by an ``IMAGE-MACHINE.spdx.index.json`` 47 containing an index of JSON :term:`SPDX` files for individual recipes. 48 49- The compressed archive ``IMAGE-MACHINE.spdx.tar.zst`` contains the index 50 and the files for the single recipes. 51 52The :ref:`ref-classes-create-spdx` class offers options to include 53more information in the output :term:`SPDX` data: 54 55- Make the json files more human readable by setting (:term:`SPDX_PRETTY`). 56 57- Add compressed archives of the files in the generated target packages by 58 setting (:term:`SPDX_ARCHIVE_PACKAGED`). 59 60- Add a description of the source files used to generate host tools and target 61 packages (:term:`SPDX_INCLUDE_SOURCES`) 62 63- Add archives of these source files themselves (:term:`SPDX_ARCHIVE_SOURCES`). 64 65Though the toplevel :term:`SPDX` output is available in 66``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary 67generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as: 68 69- The individual :term:`SPDX` JSON files in the ``IMAGE-MACHINE.spdx.tar.zst`` 70 archive. 71 72- Compressed archives of the files in the generated target packages, 73 in ``packages/packagename.tar.zst`` (when :term:`SPDX_ARCHIVE_PACKAGED` 74 is set). 75 76- Compressed archives of the source files used to build the host tools 77 and the target packages in ``recipes/recipe-packagename.tar.zst`` 78 (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill 79 "source code access" license requirements. 80 81See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows 82to associate custom notes to a recipe. 83See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX` 84project website for a list of tools to consume and transform the :term:`SPDX` 85data generated by the OpenEmbedded build system. 86 87See also Joshua Watt's presentations 88`Automated SBoM generation with OpenEmbedded and the Yocto Project <https://youtu.be/Q5UQUM6zxVU>`__ 89at FOSDEM 2023 and 90`SPDX in the Yocto Project <https://fosdem.org/2024/schedule/event/fosdem-2024-3318-spdx-in-the-yocto-project/>`__ 91at FOSDEM 2024. 92