1.. _west-zephyr-ext-cmds:
2
3Additional Zephyr extension commands
4####################################
5
6This page documents miscellaneous :ref:`west-zephyr-extensions`.
7
8.. _west-boards:
9
10Listing boards: ``west boards``
11*******************************
12
13The ``boards`` command can be used to list the boards that are supported by
14Zephyr without having to resort to additional sources of information.
15
16It can be run by typing::
17
18  west boards
19
20This command lists all supported boards in a default format. If you prefer to
21specify the display format yourself you can use the ``--format`` (or ``-f``)
22flag::
23
24  west boards -f "{arch}:{name}"
25
26Additional help about the formatting options can be found by running::
27
28  west boards -h
29
30.. _west-zephyr-export:
31
32Installing CMake packages: ``west zephyr-export``
33*************************************************
34
35This command registers the current Zephyr installation as a CMake
36config package in the CMake user package registry.
37
38In Windows, the CMake user package registry is found in
39``HKEY_CURRENT_USER\Software\Kitware\CMake\Packages``.
40
41In Linux and MacOS, the CMake user package registry is found in.
42:file:`~/.cmake/packages`.
43
44You may run this command when setting up a Zephyr workspace. If you do,
45application CMakeLists.txt files that are outside of your workspace will be
46able to find the Zephyr repository with the following:
47
48.. code-block:: cmake
49
50   find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
51
52See :zephyr_file:`share/zephyr-package/cmake` for details.
53
54.. _west-spdx:
55
56Software bill of materials: ``west spdx``
57*****************************************
58
59This command generates SPDX 2.2 tag-value documents, creating relationships
60from source files to the corresponding generated build files.
61``SPDX-License-Identifier`` comments in source files are scanned and filled
62into the SPDX documents.
63
64To use this command:
65
66#. Pre-populate a build directory :file:`BUILD_DIR` like this:
67
68   .. code-block:: bash
69
70      west spdx --init -d BUILD_DIR
71
72   This step ensures the build directory contains CMake metadata required for
73   SPDX document generation.
74
75#. Build your application using this pre-created build directory, like so:
76
77   .. code-block:: bash
78
79      west build -d BUILD_DIR [...]
80
81#. Generate SPDX documents using this build directory:
82
83   .. code-block:: bash
84
85      west spdx -d BUILD_DIR
86
87This generates the following SPDX bill-of-materials (BOM) documents in
88:file:`BUILD_DIR/spdx/`:
89
90- :file:`app.spdx`: BOM for the application source files used for the build
91- :file:`zephyr.spdx`: BOM for the specific Zephyr source code files used for
92   the build
93- :file:`build.spdx`: BOM for the built output files
94
95Each file in the bill-of-materials is scanned, so that its hashes (SHA256 and
96SHA1) can be recorded, along with any detected licenses if an
97``SPDX-License-Identifier`` comment appears in the file.
98
99SPDX Relationships are created to indicate dependencies between
100CMake build targets, build targets that are linked together, and
101source files that are compiled to generate the built library files.
102
103``west spdx`` accepts these additional options:
104
105- ``-n PREFIX``: a prefix for the Document Namespaces that will be included in
106  the generated SPDX documents. See `SPDX specification 2.2 section 2.5`_ for
107  details. If ``-n`` is omitted, a default namespace will be generated
108  according to the default format described in section 2.5 using a random UUID.
109
110- ``-s SPDX_DIR``: specifies an alternate directory where the SPDX documents
111  should be written instead of :file:`BUILD_DIR/spdx/`.
112
113- ``--analyze-includes``: in addition to recording the compiled source code
114  files (e.g. ``.c``, ``.S``) in the bills-of-materials, also attempt to
115  determine the specific header files that are included for each ``.c`` file.
116
117  This takes longer, as it performs a dry run using the C compiler for each
118  ``.c`` file using the same arguments that were passed to it for the actual
119  build.
120
121- ``--include-sdk``: with ``--analyze-includes``, also create a fourth SPDX
122  document, :file:`sdk.spdx`, which lists header files included from the SDK.
123
124.. _SPDX specification 2.2 section 2.5:
125   https://spdx.github.io/spdx-spec/2-document-creation-information/
126