159 lines
4.7 KiB
ReStructuredText
159 lines
4.7 KiB
ReStructuredText
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.
|
|
|
|
.. _wheel: https://wheel.readthedocs.io/en/latest/
|