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

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 <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
 ^^^^^^^^^^^^^^^^^^
 

Help/command/install.rst

@@ -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

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