2018-09-01 01:56:05 +08:00
|
|
|
This is the Zephyr RTOS meta tool, ``west``.
|
2018-06-05 00:04:47 +08:00
|
|
|
|
2019-05-15 23:55:13 +08:00
|
|
|
https://docs.zephyrproject.org/latest/guides/west/index.html
|
2018-09-14 07:36:19 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
Installation
|
|
|
|
|
------------
|
2018-06-05 00:04:47 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
Install west's bootstrapper with pip::
|
2018-06-05 00:04:47 +08:00
|
|
|
|
2018-11-29 01:11:11 +08:00
|
|
|
pip3 install west
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
Then install the rest of west and a Zephyr development environment in
|
|
|
|
|
a directory of your choosing::
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
mkdir zephyrproject && cd zephyrproject
|
|
|
|
|
west init
|
2019-01-25 23:43:07 +08:00
|
|
|
west update
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
What just happened:
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
- ``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.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-01-25 23:43:07 +08:00
|
|
|
- ``west update`` clones the repositories in the manifest, creating
|
2018-09-01 01:56:05 +08:00
|
|
|
working trees in the installation directory. In this case, the
|
2019-01-25 23:43:07 +08:00
|
|
|
bootstrapper notices the command (``update``) is not ``init``, and
|
2018-09-01 01:56:05 +08:00
|
|
|
delegates handling to the "main" west implementation in the source
|
|
|
|
|
repository it cloned in the previous step.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
(For those familiar with it, this is similar to how Android's Repo
|
|
|
|
|
tool works.)
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-10-31 01:41:45 +08:00
|
|
|
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.
|
|
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
Usage
|
|
|
|
|
-----
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
West has multiple sub-commands. After running ``west init``, you can
|
|
|
|
|
run them from anywhere under ``zephyrproject``.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
For a list of available commands, run ``west -h``. Get help on a
|
|
|
|
|
command with ``west <command> -h``. For example::
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
$ 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]
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
Test Suite
|
|
|
|
|
----------
|
2018-06-09 05:51:00 +08:00
|
|
|
|
tests: use tox and overhaul project testing
To properly test the project commands, it would be best to have a
fresh west bootstrapper package created and installed on PATH, so it
could be used to run commands exactly as they'd happen if we package
and ship the working tree.
To make that easier, add a dependency on tox and use it for testing:
https://tox.readthedocs.io/en/latest/
From now on, we'll test west by running 'tox' from the repository
root. This has several advantages over running pytest directly:
- "Just run tox": there are no longer any differences in test invocation
between POSIX OSes and Windows.
- tox creates an sdist package of the current tree using our setup.py
and installs it into a new virtual environment, then runs tests
there. This removes interference from other packages installed on
the host (like released bootstrappers that are also installed)
- we get to run multiple shell commands in order, should that ever be needed,
in our test procedures in a way that won't affect users
With that done, we can re-work the multirepo command testing to invoke
the bootstrapper in the virtual environment, adding various tests and
filling in longstanding testing gaps by adding increased checking of
the results (currently, much of the testing just checks whether
commands do or do not error out, which isn't enough).
These changes were made with a view towards the upcoming changes which
are planned before releasing west "into the wild": the test case code
should be mostly the same before and after the changes, so this serves
as a good baseline against regressions introduced by those upcoming
changes.
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] debugging shippable results
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] just test one py3
shutil.which west is picking up a 3.4 version in the 3.6 test, oddly
Signed-off-by: Marti Bolivar <marti@foundries.io>
2019-01-05 05:41:24 +08:00
|
|
|
Before running tests, install tox::
|
2018-06-09 05:51:00 +08:00
|
|
|
|
tests: use tox and overhaul project testing
To properly test the project commands, it would be best to have a
fresh west bootstrapper package created and installed on PATH, so it
could be used to run commands exactly as they'd happen if we package
and ship the working tree.
To make that easier, add a dependency on tox and use it for testing:
https://tox.readthedocs.io/en/latest/
From now on, we'll test west by running 'tox' from the repository
root. This has several advantages over running pytest directly:
- "Just run tox": there are no longer any differences in test invocation
between POSIX OSes and Windows.
- tox creates an sdist package of the current tree using our setup.py
and installs it into a new virtual environment, then runs tests
there. This removes interference from other packages installed on
the host (like released bootstrappers that are also installed)
- we get to run multiple shell commands in order, should that ever be needed,
in our test procedures in a way that won't affect users
With that done, we can re-work the multirepo command testing to invoke
the bootstrapper in the virtual environment, adding various tests and
filling in longstanding testing gaps by adding increased checking of
the results (currently, much of the testing just checks whether
commands do or do not error out, which isn't enough).
These changes were made with a view towards the upcoming changes which
are planned before releasing west "into the wild": the test case code
should be mostly the same before and after the changes, so this serves
as a good baseline against regressions introduced by those upcoming
changes.
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] debugging shippable results
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] just test one py3
shutil.which west is picking up a 3.4 version in the 3.6 test, oddly
Signed-off-by: Marti Bolivar <marti@foundries.io>
2019-01-05 05:41:24 +08:00
|
|
|
# macOS, Windows
|
|
|
|
|
pip3 install tox
|
2018-09-21 02:33:34 +08:00
|
|
|
|
tests: use tox and overhaul project testing
To properly test the project commands, it would be best to have a
fresh west bootstrapper package created and installed on PATH, so it
could be used to run commands exactly as they'd happen if we package
and ship the working tree.
To make that easier, add a dependency on tox and use it for testing:
https://tox.readthedocs.io/en/latest/
From now on, we'll test west by running 'tox' from the repository
root. This has several advantages over running pytest directly:
- "Just run tox": there are no longer any differences in test invocation
between POSIX OSes and Windows.
- tox creates an sdist package of the current tree using our setup.py
and installs it into a new virtual environment, then runs tests
there. This removes interference from other packages installed on
the host (like released bootstrappers that are also installed)
- we get to run multiple shell commands in order, should that ever be needed,
in our test procedures in a way that won't affect users
With that done, we can re-work the multirepo command testing to invoke
the bootstrapper in the virtual environment, adding various tests and
filling in longstanding testing gaps by adding increased checking of
the results (currently, much of the testing just checks whether
commands do or do not error out, which isn't enough).
These changes were made with a view towards the upcoming changes which
are planned before releasing west "into the wild": the test case code
should be mostly the same before and after the changes, so this serves
as a good baseline against regressions introduced by those upcoming
changes.
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] debugging shippable results
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] just test one py3
shutil.which west is picking up a 3.4 version in the 3.6 test, oddly
Signed-off-by: Marti Bolivar <marti@foundries.io>
2019-01-05 05:41:24 +08:00
|
|
|
# Linux
|
|
|
|
|
pip3 install --user tox
|
2018-09-21 02:33:34 +08:00
|
|
|
|
tests: use tox and overhaul project testing
To properly test the project commands, it would be best to have a
fresh west bootstrapper package created and installed on PATH, so it
could be used to run commands exactly as they'd happen if we package
and ship the working tree.
To make that easier, add a dependency on tox and use it for testing:
https://tox.readthedocs.io/en/latest/
From now on, we'll test west by running 'tox' from the repository
root. This has several advantages over running pytest directly:
- "Just run tox": there are no longer any differences in test invocation
between POSIX OSes and Windows.
- tox creates an sdist package of the current tree using our setup.py
and installs it into a new virtual environment, then runs tests
there. This removes interference from other packages installed on
the host (like released bootstrappers that are also installed)
- we get to run multiple shell commands in order, should that ever be needed,
in our test procedures in a way that won't affect users
With that done, we can re-work the multirepo command testing to invoke
the bootstrapper in the virtual environment, adding various tests and
filling in longstanding testing gaps by adding increased checking of
the results (currently, much of the testing just checks whether
commands do or do not error out, which isn't enough).
These changes were made with a view towards the upcoming changes which
are planned before releasing west "into the wild": the test case code
should be mostly the same before and after the changes, so this serves
as a good baseline against regressions introduced by those upcoming
changes.
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] debugging shippable results
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] just test one py3
shutil.which west is picking up a 3.4 version in the 3.6 test, oddly
Signed-off-by: Marti Bolivar <marti@foundries.io>
2019-01-05 05:41:24 +08:00
|
|
|
Then, to run the test suite locally::
|
2018-09-21 02:33:34 +08:00
|
|
|
|
tests: use tox and overhaul project testing
To properly test the project commands, it would be best to have a
fresh west bootstrapper package created and installed on PATH, so it
could be used to run commands exactly as they'd happen if we package
and ship the working tree.
To make that easier, add a dependency on tox and use it for testing:
https://tox.readthedocs.io/en/latest/
From now on, we'll test west by running 'tox' from the repository
root. This has several advantages over running pytest directly:
- "Just run tox": there are no longer any differences in test invocation
between POSIX OSes and Windows.
- tox creates an sdist package of the current tree using our setup.py
and installs it into a new virtual environment, then runs tests
there. This removes interference from other packages installed on
the host (like released bootstrappers that are also installed)
- we get to run multiple shell commands in order, should that ever be needed,
in our test procedures in a way that won't affect users
With that done, we can re-work the multirepo command testing to invoke
the bootstrapper in the virtual environment, adding various tests and
filling in longstanding testing gaps by adding increased checking of
the results (currently, much of the testing just checks whether
commands do or do not error out, which isn't enough).
These changes were made with a view towards the upcoming changes which
are planned before releasing west "into the wild": the test case code
should be mostly the same before and after the changes, so this serves
as a good baseline against regressions introduced by those upcoming
changes.
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] debugging shippable results
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] just test one py3
shutil.which west is picking up a 3.4 version in the 3.6 test, oddly
Signed-off-by: Marti Bolivar <marti@foundries.io>
2019-01-05 05:41:24 +08:00
|
|
|
tox
|
2018-09-21 02:33:34 +08:00
|
|
|
|
tests: use tox and overhaul project testing
To properly test the project commands, it would be best to have a
fresh west bootstrapper package created and installed on PATH, so it
could be used to run commands exactly as they'd happen if we package
and ship the working tree.
To make that easier, add a dependency on tox and use it for testing:
https://tox.readthedocs.io/en/latest/
From now on, we'll test west by running 'tox' from the repository
root. This has several advantages over running pytest directly:
- "Just run tox": there are no longer any differences in test invocation
between POSIX OSes and Windows.
- tox creates an sdist package of the current tree using our setup.py
and installs it into a new virtual environment, then runs tests
there. This removes interference from other packages installed on
the host (like released bootstrappers that are also installed)
- we get to run multiple shell commands in order, should that ever be needed,
in our test procedures in a way that won't affect users
With that done, we can re-work the multirepo command testing to invoke
the bootstrapper in the virtual environment, adding various tests and
filling in longstanding testing gaps by adding increased checking of
the results (currently, much of the testing just checks whether
commands do or do not error out, which isn't enough).
These changes were made with a view towards the upcoming changes which
are planned before releasing west "into the wild": the test case code
should be mostly the same before and after the changes, so this serves
as a good baseline against regressions introduced by those upcoming
changes.
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] debugging shippable results
Signed-off-by: Marti Bolivar <marti@foundries.io>
[wip] just test one py3
shutil.which west is picking up a 3.4 version in the 3.6 test, oddly
Signed-off-by: Marti Bolivar <marti@foundries.io>
2019-01-05 05:41:24 +08:00
|
|
|
See the tox configuration file, tox.ini, for more details.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
Hacking on West
|
|
|
|
|
---------------
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
West is distributed as two Python packages:
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-01-25 23:43:07 +08:00
|
|
|
1. A ``west._bootstrap`` package, which is distributed via PyPI. Running
|
2018-09-01 01:56:05 +08:00
|
|
|
``pip3 install west`` installs this **bootstrapper package only**.
|
|
|
|
|
2. The "main" ``west`` package, which is fetched by the bootstrapper
|
|
|
|
|
when ``west init`` is run.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
This somewhat unusual arrangement is because:
|
2018-06-05 00:04:47 +08:00
|
|
|
|
2018-09-01 01:56:05 +08:00
|
|
|
- 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.
|
2019-01-25 23:43:07 +08:00
|
|
|
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.
|
2018-06-05 00:04:47 +08:00
|
|
|
|
2018-09-21 02:43:41 +08:00
|
|
|
Using a Custom "Main" West
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
2018-11-22 20:19:10 +08:00
|
|
|
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.
|
2018-09-01 01:56:05 +08:00
|
|
|
|
|
|
|
|
To use another manifest repository (optionally with ``--mr
|
|
|
|
|
some-manifest-branch``)::
|
|
|
|
|
|
2019-01-25 23:43:07 +08:00
|
|
|
west init -m https://example.com/your-manifest-repository.git zephyrproject
|
2018-09-01 01:56:05 +08:00
|
|
|
|
2019-01-25 23:43:07 +08:00
|
|
|
After ``init`` time, you can hack on the west tree in
|
|
|
|
|
``zephyrproject/.west/west``.
|
2018-09-01 01:56:05 +08:00
|
|
|
|
2018-09-21 02:43:41 +08:00
|
|
|
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::
|
2018-09-01 01:56:05 +08:00
|
|
|
|
2018-09-21 02:43:41 +08:00
|
|
|
pip3 install wheel
|
2018-09-01 01:56:05 +08:00
|
|
|
|
2018-09-21 02:43:41 +08:00
|
|
|
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.
|
2018-09-01 01:56:05 +08:00
|
|
|
|
2018-09-21 02:43:41 +08:00
|
|
|
.. _wheel: https://wheel.readthedocs.io/en/latest/
|