West, Zephyr's meta-tool

104
78
Python

This is the Zephyr RTOS meta tool, west.

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

Installation

Using pip::

pip3 install west

(Use pip3 uninstall west to uninstall it.)

Basic Usage

West lets you manage multiple Git repositories under a single directory using a
single file, called the west manifest file, or manifest for short.
By default the manifest file is named west.yml.
You use west init to set up this directory, then west update to fetch
and/or update the repositories named in the manifest.

By default, west uses upstream Zephyr's manifest file <https://github.com/zephyrproject-rtos/zephyr/blob/main/west.yml>_, but west
doesn’t care if the manifest repository is zephyr or not. You can and are
encouraged to make your own manifest repositories to meet your needs.

For more details, see the West guide <https://docs.zephyrproject.org/latest/guides/west/index.html>_ in the Zephyr
documentation.

Example usage using the upstream manifest file::

mkdir zephyrproject && cd zephyrproject
west init
west update

What just happened:

  • west init clones the upstream west manifest repository, which in this
    case is the zephyr repository. The manifest repository contains west.yml,
    a YAML description of the Zephyr installation, including Git repositories and
    other metadata.

  • west update clones the other repositories named in the manifest file,
    creating working trees in the installation directory zephyrproject.

Use west init -m to specify another manifest repository. Use --mr to
use a revision to inialize from; if not given, the remote’s default branch is used.
Use --mf to use a manifest file other than west.yml.

Additional Commands

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.

West is extensible: you can add new commands to west without modifying its
source code. See Extensions <https://docs.zephyrproject.org/latest/guides/west/extensions.html>_ in the
documentation for details.

Running the Tests

First, install tox::

macOS, Windows

pip3 install tox

Linux

pip3 install --user tox

Then, run the test suite locally from the top level directory::

tox

You can use -- to tell tox to pass arguments to pytest. This is
especially useful to focus on specific tests and save time. Examples::

Run a subset of tests

tox – tests/test_project.py

Debug the test_update_narrow() code with pdb (but not the

west code which is running in subprocesses)

tox – --verbose --exitfirst --trace -k test_update_narrow

Run all tests with “import” in their name and let them log to the

current terminal

tox – -v -k import --capture=no

The tests cannot be run with pytest directly, they require the tox
environment.

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

Hacking on West

This section contains notes for getting started developing west itself.

Editable Install


To run west "live" from the current source code tree, run this command from the
top level directory in the west repository::

  pip3 install -e .

This is useful if you are actively working on west and don't want to re-package
and install a wheel each time you run it.

Installing from Source

You can create and install a wheel package to install west as well.
The wheel_ Python package is required to do this. See “Installing Wheel”
below if you need to do this.

To build the west wheel file::

macOS, Linux

python3 setup.py bdist_wheel

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.

To install the wheel::

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

You can pip3 uninstall west to remove this wheel before re-installing the
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.

.. _wheel: https://wheel.readthedocs.io/en/latest/