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-completion: 31 32Shell completion scripts: ``west completion`` 33********************************************* 34 35The ``completion`` extension command outputs shell completion scripts that can 36then be used directly to enable shell completion for the supported shells. 37 38It currently supports the following shells: 39 40- bash 41- zsh 42- fish 43 44Additional instructions are available in the command's help:: 45 46 west help completion 47 48.. _west-zephyr-export: 49 50Installing CMake packages: ``west zephyr-export`` 51************************************************* 52 53This command registers the current Zephyr installation as a CMake 54config package in the CMake user package registry. 55 56In Windows, the CMake user package registry is found in 57``HKEY_CURRENT_USER\Software\Kitware\CMake\Packages``. 58 59In Linux and MacOS, the CMake user package registry is found in. 60:file:`~/.cmake/packages`. 61 62You may run this command when setting up a Zephyr workspace. If you do, 63application CMakeLists.txt files that are outside of your workspace will be 64able to find the Zephyr repository with the following: 65 66.. code-block:: cmake 67 68 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) 69 70See :zephyr_file:`share/zephyr-package/cmake` for details. 71 72.. _west-spdx: 73 74Software bill of materials: ``west spdx`` 75***************************************** 76 77This command generates SPDX 2.3 tag-value documents, creating relationships 78from source files to the corresponding generated build files. 79``SPDX-License-Identifier`` comments in source files are scanned and filled 80into the SPDX documents. 81 82To use this command: 83 84#. Pre-populate a build directory :file:`BUILD_DIR` like this: 85 86 .. code-block:: bash 87 88 west spdx --init -d BUILD_DIR 89 90 This step ensures the build directory contains CMake metadata required for 91 SPDX document generation. 92 93#. Enable :file:`CONFIG_BUILD_OUTPUT_META` in your project. 94 95#. Build your application using this pre-created build directory, like so: 96 97 .. code-block:: bash 98 99 west build -d BUILD_DIR [...] 100 101#. Generate SPDX documents using this build directory: 102 103 .. code-block:: bash 104 105 west spdx -d BUILD_DIR 106 107This generates the following SPDX bill-of-materials (BOM) documents in 108:file:`BUILD_DIR/spdx/`: 109 110- :file:`app.spdx`: BOM for the application source files used for the build 111- :file:`zephyr.spdx`: BOM for the specific Zephyr source code files used for the build 112- :file:`build.spdx`: BOM for the built output files 113- :file:`modules-deps.spdx`: BOM for modules dependencies. Check 114 :ref:`modules <modules-vulnerability-monitoring>` for more details. 115 116Each file in the bill-of-materials is scanned, so that its hashes (SHA256 and 117SHA1) can be recorded, along with any detected licenses if an 118``SPDX-License-Identifier`` comment appears in the file. 119 120SPDX Relationships are created to indicate dependencies between 121CMake build targets, build targets that are linked together, and 122source files that are compiled to generate the built library files. 123 124``west spdx`` accepts these additional options: 125 126- ``-n PREFIX``: a prefix for the Document Namespaces that will be included in 127 the generated SPDX documents. See `SPDX specification clause 6`_ for 128 details. If ``-n`` is omitted, a default namespace will be generated 129 according to the default format described in section 2.5 using a random UUID. 130 131- ``-s SPDX_DIR``: specifies an alternate directory where the SPDX documents 132 should be written instead of :file:`BUILD_DIR/spdx/`. 133 134- ``--analyze-includes``: in addition to recording the compiled source code 135 files (e.g. ``.c``, ``.S``) in the bills-of-materials, also attempt to 136 determine the specific header files that are included for each ``.c`` file. 137 138 This takes longer, as it performs a dry run using the C compiler for each 139 ``.c`` file using the same arguments that were passed to it for the actual 140 build. 141 142- ``--include-sdk``: with ``--analyze-includes``, also create a fourth SPDX 143 document, :file:`sdk.spdx`, which lists header files included from the SDK. 144 145.. _SPDX specification clause 6: 146 https://spdx.github.io/spdx-spec/v2.2.2/document-creation-information/ 147 148.. _west-blobs: 149 150Working with binary blobs: ``west blobs`` 151***************************************** 152 153The ``blobs`` command allows users to interact with :ref:`binary blobs 154<bin-blobs>` declared in one or more :ref:`modules <modules>` via their 155:ref:`module.yml <module-yml>` file. 156 157The ``blobs`` command has three sub-commands, used to list, fetch or clean (i.e. 158delete) the binary blobs themselves. 159 160You can list binary blobs while specifying the format of the output:: 161 162 west blobs list -f '{module}: {type} {path}' 163 164For the full set of variables available in ``-f/--format`` run 165``west blobs -h``. 166 167Fetching blobs works in a similar manner:: 168 169 west blobs fetch 170 171Note that, as described in :ref:`the modules section <modules-bin-blobs>`, 172fetched blobs are stored in a :file:`zephyr/blobs/` folder relative to the root 173of the corresponding module repository. 174 175As does deleting them:: 176 177 west blobs clean 178 179Additionally the tool allows you to specify the modules you want to list, 180fetch or clean blobs for by typing the module names as a command-line 181parameter. 182 183.. _west-twister: 184 185Twister wrapper: ``west twister`` 186********************************* 187This command is a wrapper for :ref:`twister <twister_script>`. 188 189Twister can then be invoked via west as follows:: 190 191 west twister -help 192 west twister -T tests/ztest/base 193 194.. _west-bindesc: 195 196Working with binary descriptors: ``west bindesc`` 197************************************************* 198 199The ``bindesc`` command allows users to read :ref:`binary descriptors<binary_descriptors>` 200of executable files. It currently supports ``.bin``, ``.hex``, ``.elf`` and ``.uf2`` files 201as input. 202 203You can search for a specific descriptor in an image, for example:: 204 205 west bindesc search KERNEL_VERSION_STRING build/zephyr/zephyr.bin 206 207You can search for a custom descriptor by type and ID, for example:: 208 209 west bindesc custom_search STR 0x200 build/zephyr/zephyr.bin 210 211You can dump all of the descriptors in an image using:: 212 213 west bindesc dump build/zephyr/zephyr.bin 214 215You can list all known standard descriptor names using:: 216 217 west bindesc list 218 219You can print the offset of the descriptors inside the image using:: 220 221 west bindesc get_offset 222
