Overview of West

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

Functionality

west is the Zephyr Project’s meta tool that provides a variety of convenient options for building, flashing, and debugging applications, and for 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. consult the `west lopper-install` and `west lopper-command:doc:`Overview <west-lopper-install-and-west-lopper-command-overview> page for more details.

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

west [common-opts] <command> [opts] <args>

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

$ python3 -m west [common-opts] <command> [opts] <args>

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, consult Zephyr’s west init and west update section. An example workspace can look something like:

topdir/                        # west topdir, e.g. for Zephyr it's usually zephyrproject/
├── .west/                     # marks the location of the topdir
│   └── config                 # per-workspace local configuration file
│
│   # The manifest repository, never modified by west after creation:
├── zephyr/                    # .git/ repo
│   ├── west.yml               # manifest file
│   └── [... other files ...]
│
│   # Projects managed by west:
├── modules/
│   └── lib/
│       └── zcbor/             # .git/ project
├── tools/
│   └── net-tools/             # .git/ project
└── [ ... other projects ...]

For a more in-depth explanation of the preceding directories, 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, west, or both 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, after you set up your Zephyr environment by following the Zephyr Getting Started Guide, you can run the following commands to create a test build targeting a supported processor:

$ cd <local path>/zephyr
$ west build -p -b <board> tests/misc/test_build/

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 builds are removed before the application is built.

  3. -b <board>

    1. This flag indicates the board that is being targeted for the build, in this case <board> (substitute the Zephyr board name for your target).

  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:

$ west build -p -b <board> -d foo/bar tests/misc/test_build/

In this case, the build directory is 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.