blob: b72bad1554276cf163f4c882f3d0aa21e6f81728 [file] [log] [blame]
Andrew Geissler517393d2023-01-13 08:55:19 -06001.. 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.
28To make this happen, you must inherit the
29:ref:`ref-classes-create-spdx` class from a configuration file::
30
31 INHERIT += "create-spdx"
32
Patrick Williams39653562024-03-01 08:54:02 -060033Upon building an image, you will then get:
Andrew Geissler517393d2023-01-13 08:55:19 -060034
Patrick Williams39653562024-03-01 08:54:02 -060035- :term:`SPDX` output in JSON format as an ``IMAGE-MACHINE.spdx.json`` file in
36 ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`.
37
38- This toplevel file is accompanied by an ``IMAGE-MACHINE.spdx.index.json``
39 containing an index of JSON :term:`SPDX` files for individual recipes.
40
41- The compressed archive ``IMAGE-MACHINE.spdx.tar.zst`` contains the index
42 and the files for the single recipes.
Andrew Geissler517393d2023-01-13 08:55:19 -060043
44The :ref:`ref-classes-create-spdx` class offers options to include
Patrick Williams39653562024-03-01 08:54:02 -060045more information in the output :term:`SPDX` data:
46
47- Make the json files more human readable by setting (:term:`SPDX_PRETTY`).
48
49- Add compressed archives of the files in the generated target packages by
50 setting (:term:`SPDX_ARCHIVE_PACKAGED`).
51
52- Add a description of the source files used to generate host tools and target
53 packages (:term:`SPDX_INCLUDE_SOURCES`)
54
55- Add archives of these source files themselves (:term:`SPDX_ARCHIVE_SOURCES`).
Andrew Geissler517393d2023-01-13 08:55:19 -060056
57Though the toplevel :term:`SPDX` output is available in
58``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary
59generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as:
60
61- The individual :term:`SPDX` JSON files in the ``IMAGE-MACHINE.spdx.tar.zst``
62 archive.
63
64- Compressed archives of the files in the generated target packages,
65 in ``packages/packagename.tar.zst`` (when :term:`SPDX_ARCHIVE_PACKAGED`
66 is set).
67
68- Compressed archives of the source files used to build the host tools
69 and the target packages in ``recipes/recipe-packagename.tar.zst``
70 (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill
71 "source code access" license requirements.
72
Patrick Williams8e7b46e2023-05-01 14:19:06 -050073See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows
74to associate custom notes to a recipe.
Andrew Geissler517393d2023-01-13 08:55:19 -060075See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX`
76project website for a list of tools to consume and transform the :term:`SPDX`
77data generated by the OpenEmbedded build system.
78
Patrick Williams39653562024-03-01 08:54:02 -060079See also Joshua Watt's presentations
Andrew Geissler6aa7eec2023-03-03 12:41:14 -060080`Automated SBoM generation with OpenEmbedded and the Yocto Project <https://youtu.be/Q5UQUM6zxVU>`__
Patrick Williams39653562024-03-01 08:54:02 -060081at FOSDEM 2023 and
82`SPDX in the Yocto Project <https://fosdem.org/2024/schedule/event/fosdem-2024-3318-spdx-in-the-yocto-project/>`__
83at FOSDEM 2024.