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