dilim/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-07-02 12:47:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

cmSbom: Add documentation for install(SBOM) and export(SBOM)

Browse Source
This commit is contained in:
Taylor Sasser
2025-11-18 15:46:37 -05:00
parent 83671f2d87
commit 8ec5a595cd
3 changed files with 129 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Help/command/export.rst
View File

@@ -162,6 +162,32 @@ converted to lower case.
See :command:`install(PACKAGE_INFO)` for a description of the other options.
Exporting Software Bill of Materials (SBOM) Documents
"""""""""""""""""""""""""""""""""""""""""""""""""""""
.. code-block:: cmake
export(EXPORT <export-name> SBOM <sbom-name>
[PROJECT <project-name>|NO_PROJECT_METADATA]
[DESTINATION <dir>]
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
[LICENSE <license-string>]
[DESCRIPTION <description-string>]
[HOMEPAGE_URL <url-string>]
[PACKAGE_URL <url-string>]
[FORMAT <string>])
.. versionadded:: 4.3
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_GENERATE_SBOM``.
Generates a software bill of materials (SBOM) document describing the targets
in the export ``<export-name>`` and their dependencies in the build tree
See :command:`install(SBOM)` for details about the supported SBOM formats and a
description of the other options.
Exporting Packages
^^^^^^^^^^^^^^^^^^

84
Help/command/install.rst
View File

@@ -21,6 +21,7 @@ Synopsis
install(`EXPORT`_ <export-name> [...])
install(`PACKAGE_INFO`_ <package-name> [...])
install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...])
install(`SBOM`_ <sbom-name> [...])
Introduction
^^^^^^^^^^^^
@@ -1192,6 +1193,87 @@ Signatures
:command:`install_files`, and :command:`install_programs` commands
is not defined.
.. signature::
install(SBOM <sbom-name> [...])
.. versionadded:: 4.3
.. note::
Experimental. Gated by ``CMAKE_EXPERIMENTAL_GENERATE_SBOM``.
Installs a |SBOM| or "SBOM" which describes the project:
.. code-block:: cmake
install(SBOM <sbom-name> EXPORT <export-name>
[PROJECT <project-name>|NO_PROJECT_METADATA]
[DESTINATION <dir>]
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
[LICENSE <license-string>]
[DESCRIPTION <description-string>]
[HOMEPAGE_URL <url-string>]
[PACKAGE_URL <url-string>]
[FORMAT <string>])
The ``SBOM`` form generates a |SBOM| or "SBOM" file for a given project
and installs it as part of the project installation. A |SBOM| is a
machine-readable description of the project's targets, linked libraries,
and related metadata, such as versions and license information. CMake
currently generates SBOM files using the |SPDX|_ 3.0 specification in
its JSON-LD representation, as selected by the ``FORMAT`` option, but
the interface is designed to allow additional SBOM formats or schema
versions to be supported in future CMake releases.
Target installations are associated with the export ``<export-name>``
using the ``EXPORT`` option of the :command:`install(TARGETS)` signature
documented above. If ``DESTINATION`` is not specified, a platform-specific
default is used.
Several options may be used to specify package metadata:
``VERSION <version>``
The package version, specified as a series of non-negative integer components,
i.e. <major>[.<minor>[.<patch>[.<tweak>]]]. See :command:`project(VERSION)` for
more information.
``FORMAT <string>``
The format in which the SBOM should be exported, which must be an expression of
the form ``<format>[-<version>][+<representation>]``. CMake currently supports
the JSON-LD serialization of |SPDX|_ v3.0.1 (``spdx`` or ``spdx-3.0.1+json``),
which is also the default if ``FORMAT`` is not specified.
``HOMEPAGE_URL <url-string>``
An informational canonical home URL for the project.
``PACKAGE_URL <url-string>``
An informational canonical package URL for the project.
``LICENSE <license-string>``
A |SPDX|_ (SPDX) `License Expression`_ that describes the license(s) of the
project as a whole, including documentation, resources, or other materials
distributed with the project, in addition to software artifacts. See the
SPDX `License List`_ for a list of commonly used licenses and their
identifiers.
The license of individual components is taken from the
:prop_tgt:`SPDX_LICENSE` property of their respective targets.
``DESCRIPTION <description-string>``
An informational description of the project. It is recommended that this
description is a relatively short string, usually no more than a few words.
By default, if the specified ``<package-name>`` matches the current CMake
:variable:`PROJECT_NAME`, sbom metadata will be inherited from the
project. The ``PROJECT <project-name>`` option may be used to specify a
different project from which to inherit metadata. If ``NO_PROJECT_METADATA``
is specified, automatic inheritance of sbom metadata will be disabled.
In any case, any metadata values specified in the ``install`` command will
take precedence.
Examples
^^^^^^^^
@@ -1323,3 +1405,5 @@ and by CPack. You can also invoke this script manually with
.. _License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/
.. _License List: https://spdx.org/licenses/
.. |SBOM| replace:: Software Bill of Material

19
Help/dev/experimental.rst
View File

@@ -139,3 +139,22 @@ you need to set the following environment variables:
* ``CTEST_USE_INSTRUMENTATION=1``
* ``CTEST_EXPERIMENTAL_INSTRUMENTATION=ec7aa2dc-b87f-45a3-8022-fe01c5f59984``
Software Bill Of Materials |SBOM|
=================================
In order to activate support for the :command:`install(SBOM)` command,
set
* variable ``CMAKE_EXPERIMENTAL_GENERATE_SBOM`` to
* value ``ca494ed3-b261-4205-a01f-603c95e4cae0``.
This UUID may change in future versions of CMake. Be sure to use the value
documented here by the source tree of the version of CMake with which you are
experimenting.
When activated, this experimental feature provides the following:
* The experimental ``install(SBOM)`` command is available to generate
a Software Bill of Materials or "SBOM" for the current project. See
:command:`install(SBOM)` for a complete overview of the command