diff --git a/Help/command/export.rst b/Help/command/export.rst index 96738698cd..f525db0521 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -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 SBOM + [PROJECT |NO_PROJECT_METADATA] + [DESTINATION ] + [VERSION [.[.[.]]]] + [LICENSE ] + [DESCRIPTION ] + [HOMEPAGE_URL ] + [PACKAGE_URL ] + [FORMAT ]) + +.. 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 ```` 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 ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/install.rst b/Help/command/install.rst index 68caf6818a..c57af233f4 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -21,6 +21,7 @@ Synopsis install(`EXPORT`_ [...]) install(`PACKAGE_INFO`_ [...]) install(`RUNTIME_DEPENDENCY_SET`_ [...]) + install(`SBOM`_ [...]) Introduction ^^^^^^^^^^^^ @@ -1192,6 +1193,87 @@ Signatures :command:`install_files`, and :command:`install_programs` commands is not defined. +.. signature:: + install(SBOM [...]) + + .. 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 EXPORT + [PROJECT |NO_PROJECT_METADATA] + [DESTINATION ] + [VERSION [.[.[.]]]] + [LICENSE ] + [DESCRIPTION ] + [HOMEPAGE_URL ] + [PACKAGE_URL ] + [FORMAT ]) + + 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 ```` + 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 `` + The package version, specified as a series of non-negative integer components, + i.e. [.[.[.]]]. See :command:`project(VERSION)` for + more information. + + ``FORMAT `` + The format in which the SBOM should be exported, which must be an expression of + the form ``[-][+]``. 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 `` + + An informational canonical home URL for the project. + + ``PACKAGE_URL `` + + An informational canonical package URL for the project. + + ``LICENSE `` + + 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 `` + + 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 ```` matches the current CMake + :variable:`PROJECT_NAME`, sbom metadata will be inherited from the + project. The ``PROJECT `` 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 diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst index 0c0e618c66..1a599104d8 100644 --- a/Help/dev/experimental.rst +++ b/Help/dev/experimental.rst @@ -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