Additional Zephyr extension commands

This page documents miscellaneous Zephyr Extensions.

Listing boards: west boards

The boards command can be used to list the boards that are supported by Zephyr without having to resort to additional sources of information.

It can be run by typing:

west boards

This command lists all supported boards in a default format. If you prefer to specify the display format yourself you can use the --format (or -f) flag:

west boards -f "{arch}:{name}"

Additional help about the formatting options can be found by running:

west boards -h

Shell completion scripts: west completion

The completion extension command outputs shell completion scripts that can then be used directly to enable shell completion for the supported shells.

It currently supports the following shells:

  • bash

  • zsh

  • fish

Additional instructions are available in the command’s help:

west help completion

Installing CMake packages: west zephyr-export

This command registers the current Zephyr installation as a CMake config package in the CMake user package registry.

In Windows, the CMake user package registry is found in HKEY_CURRENT_USER\Software\Kitware\CMake\Packages.

In Linux and MacOS, the CMake user package registry is found in. ~/.cmake/packages.

You may run this command when setting up a Zephyr workspace. If you do, application CMakeLists.txt files that are outside of your workspace will be able to find the Zephyr repository with the following:

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})

See share/zephyr-package/cmake for details.

Software bill of materials: west spdx

This command generates SPDX 2.3 tag-value documents, creating relationships from source files to the corresponding generated build files. SPDX-License-Identifier comments in source files are scanned and filled into the SPDX documents.

To use this command:

  1. Pre-populate a build directory BUILD_DIR like this:

    west spdx --init -d BUILD_DIR

    This step ensures the build directory contains CMake metadata required for SPDX document generation.

  2. Enable CONFIG_BUILD_OUTPUT_META in your project.

  3. Build your application using this pre-created build directory, like so:

    west build -d BUILD_DIR [...]

  4. Generate SPDX documents using this build directory:

    west spdx -d BUILD_DIR

This generates the following SPDX bill-of-materials (BOM) documents in BUILD_DIR/spdx/:

  • app.spdx: BOM for the application source files used for the build

  • zephyr.spdx: BOM for the specific Zephyr source code files used for the build

  • build.spdx: BOM for the built output files

  • modules-deps.spdx: BOM for modules dependencies. Check modules for more details.

Each file in the bill-of-materials is scanned, so that its hashes (SHA256 and SHA1) can be recorded, along with any detected licenses if an SPDX-License-Identifier comment appears in the file.

SPDX Relationships are created to indicate dependencies between CMake build targets, build targets that are linked together, and source files that are compiled to generate the built library files.

west spdx accepts these additional options:

  • -n PREFIX: a prefix for the Document Namespaces that will be included in the generated SPDX documents. See SPDX specification clause 6 for details. If -n is omitted, a default namespace will be generated according to the default format described in section 2.5 using a random UUID.

  • -s SPDX_DIR: specifies an alternate directory where the SPDX documents should be written instead of BUILD_DIR/spdx/.

  • --analyze-includes: in addition to recording the compiled source code files (e.g. .c, .S) in the bills-of-materials, also attempt to determine the specific header files that are included for each .c file.

    This takes longer, as it performs a dry run using the C compiler for each .c file using the same arguments that were passed to it for the actual build.

  • --include-sdk: with --analyze-includes, also create a fourth SPDX document, sdk.spdx, which lists header files included from the SDK.

Working with binary blobs: west blobs

The blobs command allows users to interact with binary blobs declared in one or more modules via their module.yml file.

The blobs command has three sub-commands, used to list, fetch or clean (i.e. delete) the binary blobs themselves.

You can list binary blobs while specifying the format of the output:

west blobs list -f '{module}: {type} {path}'

For the full set of variables available in -f/--format run west blobs -h.

Fetching blobs works in a similar manner:

west blobs fetch

Note that, as described in the modules section, fetched blobs are stored in a zephyr/blobs/ folder relative to the root of the corresponding module repository.

As does deleting them:

west blobs clean

Additionally the tool allows you to specify the modules you want to list, fetch or clean blobs for by typing the module names as a command-line parameter.

Twister wrapper: west twister

This command is a wrapper for twister.

Twister can then be invoked via west as follows:

west twister -help
west twister -T tests/ztest/base

Working with binary descriptors: west bindesc

The bindesc command allows users to read binary descriptors of executable files. It currently supports .bin, .hex, .elf and .uf2 files as input.

You can search for a specific descriptor in an image, for example:

west bindesc search KERNEL_VERSION_STRING build/zephyr/zephyr.bin

You can search for a custom descriptor by type and ID, for example:

west bindesc custom_search STR 0x200 build/zephyr/zephyr.bin

You can dump all of the descriptors in an image using:

west bindesc dump build/zephyr/zephyr.bin

You can list all known standard descriptor names using:

west bindesc list

You can print the offset of the descriptors inside the image using:

west bindesc get_offset