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 223Indexing the sources with GNU Global: ``west gtags`` 224**************************************************** 225 226.. important:: You must install the ``gtags`` and ``global`` programs provided 227 by `GNU Global`_ to use this command. 228 229The ``west gtags`` command lets you create a GNU Global tags file for the entire 230west workspace:: 231 232 west gtags 233 234.. _GNU Global: https://www.gnu.org/software/global/ 235 236This will create a tags file named ``GTAGS`` in the workspace :ref:`topdir 237<west-workspace>` (it will also create other Global-related metadata files 238named ``GPATH`` and ``GRTAGS`` in the same place). 239 240You can then run the ``global`` command anywhere inside the 241workspace to search for symbol locations using this tags file. 242 243For example, to search for definitions of the ``arch_system_halt()`` function, 244starting from the ``zephyr/drivers`` directory:: 245 246 $ cd zephyr/drivers 247 $ global -x arch_system_halt 248 arch_system_halt 65 ../arch/arc/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 249 arch_system_halt 455 ../arch/arm64/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 250 arch_system_halt 137 ../arch/nios2/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 251 arch_system_halt 18 ../arch/posix/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 252 arch_system_halt 17 ../arch/x86/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 253 arch_system_halt 126 ../arch/xtensa/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 254 arch_system_halt 21 ../kernel/fatal.c FUNC_NORETURN __weak void arch_system_halt(unsigned int reason) 255 256This prints the search symbol, the line it is defined on, a relative path to 257the file it is defined in, and the line itself, for all places where the symbol 258is defined. 259 260Additional tips: 261 262- This can also be useful to search for vendor HAL function definitions. 263 264- See the ``global`` command's manual page for more information on how to use 265 this tool. 266 267- You should run ``global``, **not** ``west global``. There is no need for a 268 separate ``west global`` command since ``global`` already searches for the 269 ``GTAGS`` file starting from your current working directory. This is why you 270 need to run ``global`` from inside the workspace. 271
