.. SPDX-License-Identifier: CC-BY-SA-2.0-UK

Creating a Software Bill of Materials
*************************************

Once you are able to build an image for your project, once the licenses for
each software component are all identified (see
":ref:`dev-manual/licenses:working with licenses`") and once vulnerability
fixes are applied (see ":ref:`dev-manual/vulnerabilities:checking
for vulnerabilities`"), the OpenEmbedded build system can generate
a description of all the components you used, their licenses, their dependencies,
their sources, the changes that were applied to them and the known
vulnerabilities that were fixed.

This description is generated in the form of a *Software Bill of Materials*
(:term:`SBOM`), using the :term:`SPDX` standard.

When you release software, this is the most standard way to provide information
about the Software Supply Chain of your software image and SDK. The
:term:`SBOM` tooling is often used to ensure open source license compliance by
providing the license texts used in the product which legal departments and end
users can read in standardized format.

:term:`SBOM` information is also critical to performing vulnerability exposure
assessments, as all the components used in the Software Supply Chain are listed.

The OpenEmbedded build system doesn't generate such information by default.
To make this happen, you must inherit the
:ref:`ref-classes-create-spdx` class from a configuration file::

   INHERIT += "create-spdx"

You then get :term:`SPDX` output in JSON format as an
``IMAGE-MACHINE.spdx.json`` file in ``tmp/deploy/images/MACHINE/`` inside the
:term:`Build Directory`.

This is a toplevel file accompanied by an ``IMAGE-MACHINE.spdx.index.json``
containing an index of JSON :term:`SPDX` files for individual recipes, together
with an ``IMAGE-MACHINE.spdx.tar.zst`` compressed archive containing all such
files.

The :ref:`ref-classes-create-spdx` class offers options to include
more information in the output :term:`SPDX` data, such as making the generated
files more human readable (:term:`SPDX_PRETTY`), adding compressed archives of
the files in the generated target packages (:term:`SPDX_ARCHIVE_PACKAGED`),
adding a description of the source files used to generate host tools and target
packages (:term:`SPDX_INCLUDE_SOURCES`) and adding archives of these source
files themselves (:term:`SPDX_ARCHIVE_SOURCES`).

Though the toplevel :term:`SPDX` output is available in
``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary
generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as:

-  The individual :term:`SPDX` JSON files in the ``IMAGE-MACHINE.spdx.tar.zst``
   archive.

-  Compressed archives of the files in the generated target packages,
   in ``packages/packagename.tar.zst`` (when :term:`SPDX_ARCHIVE_PACKAGED`
   is set).

-  Compressed archives of the source files used to build the host tools
   and the target packages in ``recipes/recipe-packagename.tar.zst``
   (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill
   "source code access" license requirements.

See also the :term:`SPDX_CUSTOM_ANNOTATION_VARS` variable which allows
to associate custom notes to a recipe.

See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX`
project website for a list of tools to consume and transform the :term:`SPDX`
data generated by the OpenEmbedded build system.

See also Joshua Watt's
`Automated SBoM generation with OpenEmbedded and the Yocto Project <https://youtu.be/Q5UQUM6zxVU>`__
presentation at FOSDEM 2023.