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- powershell (board qualifiers only) 44 45Additional instructions are available in the command's help:: 46 47 west help completion 48 49.. _west-zephyr-export: 50 51Installing CMake packages: ``west zephyr-export`` 52************************************************* 53 54This command registers the current Zephyr installation as a CMake 55config package in the CMake user package registry. 56 57In Windows, the CMake user package registry is found in 58``HKEY_CURRENT_USER\Software\Kitware\CMake\Packages``. 59 60In Linux and MacOS, the CMake user package registry is found in. 61:file:`~/.cmake/packages`. 62 63You may run this command when setting up a Zephyr workspace. If you do, 64application CMakeLists.txt files that are outside of your workspace will be 65able to find the Zephyr repository with the following: 66 67.. code-block:: cmake 68 69 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) 70 71See :zephyr_file:`share/zephyr-package/cmake` for details. 72 73.. _west-spdx: 74 75Software bill of materials: ``west spdx`` 76***************************************** 77 78This command generates SPDX 2.2 or 2.3 tag-value documents, creating relationships 79from source files to the corresponding generated build files. 80``SPDX-License-Identifier`` comments in source files are scanned and filled 81into the SPDX documents. 82 83To use this command: 84 85#. Pre-populate a build directory :file:`BUILD_DIR` like this: 86 87 .. code-block:: bash 88 89 west spdx --init -d BUILD_DIR 90 91 This step ensures the build directory contains CMake metadata required for 92 SPDX document generation. 93 94#. Enable :file:`CONFIG_BUILD_OUTPUT_META` in your project. 95 96#. Build your application using this pre-created build directory, like so: 97 98 .. code-block:: bash 99 100 west build -d BUILD_DIR [...] 101 102#. Generate SPDX documents using this build directory: 103 104 .. code-block:: bash 105 106 west spdx -d BUILD_DIR 107 108 By default, this generates SPDX 2.3 documents. To generate SPDX 2.2 documents instead: 109 110 .. code-block:: bash 111 112 west spdx -d BUILD_DIR --spdx-version 2.2 113 114.. note:: 115 116 When building with :ref:`sysbuild`, make sure you target the actual application 117 which you want to generate the SBOM for. For example, if the application is 118 named ``hello_world``: 119 120 .. code-block:: bash 121 122 west spdx --init -d BUILD_DIR/hello_world 123 west build -d BUILD_DIR/hello_world 124 west spdx -d BUILD_DIR/hello_world 125 126This generates the following SPDX bill-of-materials (BOM) documents in 127:file:`BUILD_DIR/spdx/`: 128 129- :file:`app.spdx`: BOM for the application source files used for the build 130- :file:`zephyr.spdx`: BOM for the specific Zephyr source code files used for the build 131- :file:`build.spdx`: BOM for the built output files 132- :file:`modules-deps.spdx`: BOM for modules dependencies. Check 133 :ref:`modules <modules-vulnerability-monitoring>` for more details. 134 135Each file in the bill-of-materials is scanned, so that its hashes (SHA256 and 136SHA1) can be recorded, along with any detected licenses if an 137``SPDX-License-Identifier`` comment appears in the file. 138 139Copyright notices are extracted using the third-party :command:`reuse` tool from the REUSE group. 140When found, these notices are added to SPDX documents as ``FileCopyrightText`` fields. 141 142.. note:: 143 Copyright extraction uses heuristics that may not capture complete notice text, so 144 ``FileCopyrightText`` content is best-effort. This aligns with SPDX specification recommendations. 145 146SPDX Relationships are created to indicate dependencies between 147CMake build targets, build targets that are linked together, and 148source files that are compiled to generate the built library files. 149 150``west spdx`` accepts these additional options: 151 152- ``-n PREFIX``: a prefix for the Document Namespaces that will be included in 153 the generated SPDX documents. See `SPDX specification clause 6`_ for 154 details. If ``-n`` is omitted, a default namespace will be generated 155 according to the default format described in section 2.5 using a random UUID. 156 157- ``-s SPDX_DIR``: specifies an alternate directory where the SPDX documents 158 should be written instead of :file:`BUILD_DIR/spdx/`. 159 160- ``--spdx-version {2.2,2.3}``: specifies which SPDX specification version to use. 161 Defaults to ``2.3``. SPDX 2.3 includes additional fields like ``PrimaryPackagePurpose`` 162 that are not available in SPDX 2.2. 163 164- ``--analyze-includes``: in addition to recording the compiled source code 165 files (e.g. ``.c``, ``.S``) in the bills-of-materials, also attempt to 166 determine the specific header files that are included for each ``.c`` file. 167 168 This takes longer, as it performs a dry run using the C compiler for each 169 ``.c`` file using the same arguments that were passed to it for the actual 170 build. 171 172- ``--include-sdk``: with ``--analyze-includes``, also create a fourth SPDX 173 document, :file:`sdk.spdx`, which lists header files included from the SDK. 174 175.. warning:: 176 177 The generation of SBOM documents for the ``native_sim`` platform is currently not supported. 178 179.. _SPDX specification clause 6: 180 https://spdx.github.io/spdx-spec/v2.2.2/document-creation-information/ 181 182.. _west-blobs: 183 184Working with binary blobs: ``west blobs`` 185***************************************** 186 187The ``blobs`` command allows users to interact with :ref:`binary blobs 188<bin-blobs>` declared in one or more :ref:`modules <modules>` via their 189:ref:`module.yml <module-yml>` file. 190 191The ``blobs`` command has three sub-commands, used to list, fetch or clean (i.e. 192delete) the binary blobs themselves. 193 194You can list binary blobs while specifying the format of the output:: 195 196 west blobs list -f '{module}: {type} {path}' 197 198For the full set of variables available in ``-f/--format`` run 199``west blobs -h``. 200 201Fetching blobs works in a similar manner:: 202 203 west blobs fetch 204 205Note that, as described in :ref:`the modules section <modules-bin-blobs>`, 206fetched blobs are stored in a :file:`zephyr/blobs/` folder relative to the root 207of the corresponding module repository. 208 209As does deleting them:: 210 211 west blobs clean 212 213Additionally the tool allows you to specify the modules you want to list, 214fetch or clean blobs for by typing the module names as a command-line 215parameter. 216 217.. _west-twister: 218 219Twister wrapper: ``west twister`` 220********************************* 221This command is a wrapper for :ref:`twister <twister_script>`. 222 223Twister can then be invoked via west as follows:: 224 225 west twister -help 226 west twister -T tests/ztest/base 227 228.. _west-bindesc: 229 230Working with binary descriptors: ``west bindesc`` 231************************************************* 232 233The ``bindesc`` command allows users to read :ref:`binary descriptors<binary_descriptors>` 234of executable files. It currently supports ``.bin``, ``.hex``, ``.elf`` and ``.uf2`` files 235as input. 236 237You can search for a specific descriptor in an image, for example:: 238 239 west bindesc search KERNEL_VERSION_STRING build/zephyr/zephyr.bin 240 241You can search for a custom descriptor by type and ID, for example:: 242 243 west bindesc custom_search STR 0x200 build/zephyr/zephyr.bin 244 245You can dump all of the descriptors in an image using:: 246 247 west bindesc dump build/zephyr/zephyr.bin 248 249You can list all known standard descriptor names using:: 250 251 west bindesc list 252 253You can print the offset of the descriptors inside the image using:: 254 255 west bindesc get_offset 256 257Indexing the sources with GNU Global: ``west gtags`` 258**************************************************** 259 260.. important:: You must install the ``gtags`` and ``global`` programs provided 261 by `GNU Global`_ to use this command. 262 263The ``west gtags`` command lets you create a GNU Global tags file for the entire 264west workspace:: 265 266 west gtags 267 268.. _GNU Global: https://www.gnu.org/software/global/ 269 270This will create a tags file named ``GTAGS`` in the workspace :ref:`topdir 271<west-workspace>` (it will also create other Global-related metadata files 272named ``GPATH`` and ``GRTAGS`` in the same place). 273 274You can then run the ``global`` command anywhere inside the 275workspace to search for symbol locations using this tags file. 276 277For example, to search for definitions of the ``arch_system_halt()`` function, 278starting from the ``zephyr/drivers`` directory:: 279 280 $ cd zephyr/drivers 281 $ global -x arch_system_halt 282 arch_system_halt 65 ../arch/arc/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 283 arch_system_halt 455 ../arch/arm64/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 284 arch_system_halt 137 ../arch/nios2/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 285 arch_system_halt 18 ../arch/posix/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 286 arch_system_halt 17 ../arch/x86/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 287 arch_system_halt 126 ../arch/xtensa/core/fatal.c FUNC_NORETURN void arch_system_halt(unsigned int reason) 288 arch_system_halt 21 ../kernel/fatal.c FUNC_NORETURN __weak void arch_system_halt(unsigned int reason) 289 290This prints the search symbol, the line it is defined on, a relative path to 291the file it is defined in, and the line itself, for all places where the symbol 292is defined. 293 294Additional tips: 295 296- This can also be useful to search for vendor HAL function definitions. 297 298- See the ``global`` command's manual page for more information on how to use 299 this tool. 300 301- You should run ``global``, **not** ``west global``. There is no need for a 302 separate ``west global`` command since ``global`` already searches for the 303 ``GTAGS`` file starting from your current working directory. This is why you 304 need to run ``global`` from inside the workspace. 305 306.. _west-patch: 307 308Working with patches: ``west patch`` 309************************************ 310 311The ``patch`` command allows users to apply patches to Zephyr or Zephyr modules 312in a controlled manner that makes automation and tracking easier for external applications that 313use the :ref:`T2 star topology <west-t2>`. The :ref:`patches.yml <patches-yml>` file stores 314metadata about patch files and fills-in the gaps between official Zephyr releases, so that users 315can easily see the status of any upstreaming efforts, and determine which patches to drop before 316upgrading to the next Zephyr release. 317 318There are several sub-commands available to manage patches for Zephyr or other modules in the 319workspace: 320 321* ``apply``: apply patches listed in ``patches.yml`` 322* ``clean``: remove all patches that have been applied, and reset to the manifest checkout state 323* ``list``: list all patches in ``patches.yml`` 324* ``gh-fetch``: fetch patches from a GitHub pull request 325 326.. code-block:: none 327 328 west-workspace/ 329 └── application/ 330 ... 331 ├── west.yml 332 └── zephyr 333 ├── module.yml 334 ├── patches 335 │ ├── bootloader 336 │ │ └── mcuboot 337 │ │ └── my-tweak-for-mcuboot.patch 338 │ └── zephyr 339 │ └── my-zephyr-change.patch 340 └── patches.yml 341 342In this example, the :ref:`west manifest <west-manifests>` file, ``west.yml``, would pin to a 343specific Zephyr revision (e.g. ``v4.1.0``) and apply patches against that revision of Zephyr and 344the specific revisions of other modules used in the application. However, this application needs 345two changes in order to meet requirements; one for Zephyr and another for MCUBoot. 346 347.. _patches-yml: 348 349.. code-block:: yaml 350 351 patches: 352 - path: zephyr/my-zephyr-change.patch 353 sha256sum: c676cd376a4d19dc95ac4e44e179c253853d422b758688a583bb55c3c9137035 354 module: zephyr 355 author: Obi-Wan Kenobi 356 email: obiwan@jedi.org 357 date: 2025-05-04 358 upstreamable: false 359 comments: | 360 An application-specific change we need for Zephyr. 361 - path: bootloader/mcuboot/my-tweak-for-mcuboot.patch 362 sha256sum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 363 module: mcuboot 364 author: Darth Sidious 365 email: sidious@sith.org 366 date: 2025-05-04 367 merge-pr: https://github.com/zephyrproject-rtos/zephyr/pull/<pr-number> 368 issue: https://github.com/zephyrproject-rtos/zephyr/issues/<issue-number> 369 merge-status: true 370 merge-commit: 1234567890abcdef1234567890abcdef12345678 371 merge-date: 2025-05-06 372 apply-command: git apply 373 comments: | 374 A change to mcuboot that has been merged already. We can remove this 375 patch when we are ready to upgrade to the next Zephyr release. 376 377Patches can easily be applied in an automated manner. For example: 378 379.. code-block:: bash 380 381 west init -m <manifest repo> <workspace> 382 cd <workspace> 383 west update 384 west patch apply 385 386When it is time to update to a newer version of Zephyr, the ``west.yml`` file can be updated to 387point at the next Zephyr release, e.g. ``v4.2.0``. Patches that are no longer needed, like 388``my-tweak-for-mcuboot.patch`` in the example above, can be removed from ``patches.yml`` and from 389the external application repository, and then the following commands can be run. 390 391.. code-block:: bash 392 393 west patch clean 394 west update 395 west patch apply --roll-back # roll-back all patches if one does not apply cleanly 396 397If a patch needs to be reworked, remember to update the ``patches.yml`` file with the new SHA256 398checksum. 399 400.. code-block:: bash 401 402 sha256sum zephyr/patches/zephyr/my-zephyr-change.patch 403 7d57ca78d5214f422172cc47fed9d0faa6d97a0796c02485bff0bf29455765e9 404 405It is also possible to use ``west patch gh-fetch`` to fetch patches from a GitHub pull request and 406automatically create or update the ``patches.yml`` file. This can be useful when the author already 407has a number of changes captured in existing upstream pull requests. 408 409.. code-block:: bash 410 411 west patch gh-fetch --owner zephyrproject-rtos --repo zephyr --pull-request <pr-number> \ 412 --module zephyr --split-commits 413 414The above command will create the directory and file structure below, which includes patches for 415each individual commit associated with the given pull request. 416 417.. code-block:: none 418 419 zephyr 420 ├── patches 421 │ ├── first-commit-from-pr.patch 422 │ ├── second-commit-from-pr.patch 423 │ └── third-commit-from-pr.patch 424 └── patches.yml 425