This page provides an overview of west’s core functionality and most common commands.

Table of Contents

Functionality

west is the Zephyr Project’s meta tool that provides a variety of convenient options for building, flashing, and debugging applications as well as managing multiple repositories. AMD has extended west by adding the lopper-install and lopper-command extensions that allow users to add lopper (link) to their environment. Please consult the `west lopper-install` and `west lopper-command` OverviewPreview page for more details.

west takes commands in the form of common options, a command, then options and arguments for that command:

From west version 0.8 on, it can also be run through python by using python -m:

You can always run west --help or west <command> -h for detailed help.

To set up a west workspace, run west init and west update. west init creates a west workspace and clones the manifest repository, while west update clones or updates the projects listed in your manifest file (typically called west.yml). For a more thorough explanation of how exactly these commands work, please consult Zephyr’s west init and west update section. An example workspace can look something like:

For a more in-depth explanation of the directories above, please consult Zephyr’s workspace concepts section.

Integration and Usage

west is maintained in its own repository. It is recommended to install west in a Python virtual environment dedicated to a specific version of Zephyr. This can be useful in general to maintain a sanitized development environment, but also lets you have a separate virtual environment if you wanted to have multiple versions of Zephyr and/or west installed on your machine. It can also remove packages incompatibilities that can happen if you have other projects using Python on the same machine.

As an example, if you follow the steps to set up your Zephyr environment for AMD’s 2024.2 release, you will be able to run the following commands to create a test build targeting the MicroBlaze V 32-bit processor:

Here is a breakdown of the command:

1. west build

   1. The build command tells Zephyr to build an application from a source.

      1. If there is a Zephyr build directory named build in your current working directory, or if you are in a Zephyr build directory, it is incrementally re-compiled.

      2. Otherwise, if no build directory is found, a new one is created and the application is compiled in it.

2. -p

   1. This is a flag that indicates a pristine build. A pristine build is essentially a new build, all byproducts from any previous build(s) are removed before the application is built.

3. -b mbv32

   1. This flag indicates the board that is being targeted for the build, in this case mbv32 (link).

4. tests/misc/test_build/

   1. This flag indicates the source directory of the application you’re trying to build. The source directory is the directory that contains CMakeLists.txt.

You can also change the build directory by using the --build-dir flag (or -d for shorthand). The updated command looks like:

In this case, the build directory would be bar.

Conclusion

west is a powerful meta tool for developers working on Zephyr-based projects. Its core commands (init, update, build) simplify cloning repositories, creating workspaces, and building applications. west offers an adaptable foundation for both small-scale development and more complex, multi-project workspaces.