west 0.5.5

Zephyr RTOS Project meta-tool (wrapper and bootstrap)

This is the Zephyr RTOS meta tool, west.

For more information about west, see:

https://docs.zephyrproject.org/latest/tools/west/index.html

Installation

Install west’s bootstrapper with pip:

pip3 install west

Then install the rest of west and a Zephyr development environment in a directory of your choosing:

mkdir zephyrproject && cd zephyrproject
west init
west update

What just happened:

• west init runs the bootstrapper, which clones the west source repository and a west manifest repository. The manifest contains a YAML description of the Zephyr installation, including Git repositories and other metadata. The init command is the only one supported by the bootstrapper itself; all other commands are implemented in the west source repository it clones.

• west update clones the repositories in the manifest, creating working trees in the installation directory. In this case, the bootstrapper notices the command (update) is not init, and delegates handling to the “main” west implementation in the source repository it cloned in the previous step.

(For those familiar with it, this is similar to how Android’s Repo tool works.)

Command auto-completion for Bash

The scripts/west-completion.bash script adds auto-completion for West subcommands and flags. See the top of file for installation instructions.

Usage

West has multiple sub-commands. After running west init, you can run them from anywhere under zephyrproject.

For a list of available commands, run west -h. Get help on a command with west <command> -h. For example:

$ west -h
usage: west [-h] [-z ZEPHYR_BASE] [-v]
            {build,flash,debug,debugserver,attach,list-projects,fetch,pull,rebase,branch,checkout,diff,status,forall}
            ...
[snip]
$ west flash -h
usage: west flash [-h] [-H] [-d BUILD_DIR] ...
[snip]

Test Suite

Before running tests, install tox:

# macOS, Windows
pip3 install tox

# Linux
pip3 install --user tox

Then, to run the test suite locally:

tox

See the tox configuration file, tox.ini, for more details.

Hacking on West

West is distributed as two Python packages:

1. A west._bootstrap package, which is distributed via PyPI. Running pip3 install west installs this bootstrapper package only.

2. The “main” west package, which is fetched by the bootstrapper when west init is run.

This somewhat unusual arrangement is because:

• One of west’s jobs is to manage a Zephyr installation’s Git repositories, including its own.

• It allows easy customization of the version of west that’s shipped with non-upstream distributions of Zephyr.

• West is experimental and is not stable. Users need to stay in sync with upstream, and this allows west to automatically update itself. Once things have settled down, we plan on making the pip package contain the core west and the multi-repo commands, with other features to be provided by projects in extension commands, but time will tell.

Using a Custom “Main” West

To initialize west from a non-default location add a section west in the manifest .yml file that points to a url and revision of your choice.

To use another manifest repository (optionally with --mr some-manifest-branch):

west init -m https://example.com/your-manifest-repository.git zephyrproject

After init time, you can hack on the west tree in zephyrproject/.west/west.

Using a Custom West Bootstrapper

To package and install the west bootstrapper from a west repository checkout, wheel must be installed. It probably already is, but see “Installing Wheel” below if these instructions fail.

To build the west bootstrapper wheel file:

python3 setup.py bdist_wheel

On Windows:

py -3 setup.py bdist_wheel

This will create a file named dist/west-x.y.z-py3-none-any.whl, where x.y.z is the current version in setup.py. Install it with:

pip3 install -U dist/west-x.y.z-py3-none-any.whl

You can then run west init with a bootstrapper created from the current repository contents. (On Linux, make sure ~/.local/bin is in your PATH.)

To uninstall this bootstrapper, use:

pip3 uninstall west

You can then reinstall the mainline version from PyPI, etc.

Installing Wheel

On macOS and Windows, you can install wheel with:

pip3 install wheel

That also works on Linux, but you may want to install wheel from your system package manager instead – e.g. if you installed pip from your system package manager. The wheel package is likely named something like python3-wheel in that case.