doc: add docs for west spdx

These are based on the commit log in
fd31b9b.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

doc/guides/west/zephyr-cmds.rst

@@ -50,3 +50,76 @@ able to find the Zephyr repository with the following:
    find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
 
 See :zephyr_file:`share/zephyr-package/cmake` for details.
+
+.. _west-spdx:
+
+Software bill of materials: ``west spdx``
+*****************************************
+
+This command generates SPDX 2.2 tag-value documents, creating relationships
+from source files to the corresponding generated build files.
+``SPDX-License-Identifier`` comments in source files are scanned and filled
+into the SPDX documents.
+
+To use this command:
+
+#. Pre-populate a build directory :file:`BUILD_DIR` like this:
+
+   .. code-block:: bash
+
+      west spdx --init -d BUILD_DIR
+
+   This step ensures the build directory contains CMake metadata required for
+   SPDX document generation.
+
+#. Build your application using this pre-created build directory, like so:
+
+   .. code-block:: bash
+
+      west build -d BUILD_DIR [...]
+
+#. Generate SPDX documents using this build directory:
+
+   .. code-block:: bash
+
+      west spdx -d BUILD_DIR
+
+This generates the following SPDX bill-of-materials (BOM) documents in
+:file:`BUILD_DIR/spdx/`:
+
+- :file:`app.spdx`: BOM for the application source files used for the build
+- :file:`zephyr.spdx`: BOM for the specific Zephyr source code files used for
+   the build
+- :file:`build.spdx`: BOM for the built output files
+
+Each file in the bill-of-materials is scanned, so that its hashes (SHA256 and
+SHA1) can be recorded, along with any detected licenses if an
+``SPDX-License-Identifier`` comment appears in the file.
+
+SPDX Relationships are created to indicate dependencies between
+CMake build targets, build targets that are linked together, and
+source files that are compiled to generate the built library files.
+
+``west spdx`` accepts these additional options:
+
+- ``-n PREFIX``: a prefix for the Document Namespaces that will be included in
+  the generated SPDX documents. See `SPDX specification 2.2 section 2.5`_ for
+  details. If ``-n`` is omitted, a default namespace will be generated
+  according to the default format described in section 2.5 using a random UUID.
+
+- ``-s SPDX_DIR``: specifies an alternate directory where the SPDX documents
+  should be written instead of :file:`BUILD_DIR/spdx/`.
+
+- ``--analyze-includes``: in addition to recording the compiled source code
+  files (e.g. ``.c``, ``.S``) in the bills-of-materials, also attempt to
+  determine the specific header files that are included for each ``.c`` file.
+
+  This takes longer, as it performs a dry run using the C compiler for each
+  ``.c`` file using the same arguments that were passed to it for the actual
+  build.
+
+- ``--include-sdk``: with ``--analyze-includes``, also create a fourth SPDX
+  document, :file:`sdk.spdx`, which lists header files included from the SDK.
+
+.. _SPDX specification 2.2 section 2.5:
+   https://spdx.github.io/spdx-spec/2-document-creation-information/

scripts/west_commands/spdx.py

@@ -32,6 +32,8 @@ def do_add_parser(self, parser_adder):
                 help=self.help,
                 description = self.description)
 
+        # If you update these options, make sure to keep the docs in
+        # doc/guides/west/zephyr-cmds.rst up to date.
         parser.add_argument('-i', '--init', action="store_true",
                 help="initialize CMake file-based API")
         parser.add_argument('-d', '--build-dir',