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
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
Using 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
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
(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. 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/master/west.yml>`_, but west
|
|
|
|
|
doesn't care if the manifest repository is a Zephyr tree or not.
|
|
|
|
|
|
|
|
|
|
For more details, see `Multiple Repository Management
|
|
|
|
|
<https://docs.zephyrproject.org/latest/guides/west/repo-tool.html>`_ in the
|
|
|
|
|
west documentation.
|
|
|
|
|
|
|
|
|
|
Example usage using the upstream manifest file::
|
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
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
- ``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.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
- ``west update`` clones the other repositories named in the manifest file,
|
|
|
|
|
creating working trees in the installation directory ``zephyrproject``.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
Use ``west init -m`` to specify another manifest repository. Use ``--mr`` to
|
|
|
|
|
use a revision other than ``master``.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
Additional Commands
|
|
|
|
|
-------------------
|
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
|
2019-07-23 07:22:42 +08:00
|
|
|
command with ``west <command> -h``.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
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.
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
Running the Tests
|
|
|
|
|
-----------------
|
2018-06-09 05:51:00 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
First, 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
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
Then, run the test suite locally from the top level directory::
|
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
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
Installing from Source
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
2018-06-05 00:04:47 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
The `wheel`_ package is required to install west from source. See "Installing
|
|
|
|
|
Wheel" below if you don't have ``wheel`` installed.
|
2018-09-21 02:43:41 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
To build the west wheel file::
|
2018-09-21 02:43:41 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
# macOS, Linux
|
2018-09-21 02:43:41 +08:00
|
|
|
python3 setup.py bdist_wheel
|
|
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
# Windows
|
2018-09-21 02:43:41 +08:00
|
|
|
py -3 setup.py bdist_wheel
|
|
|
|
|
|
|
|
|
|
This will create a file named ``dist/west-x.y.z-py3-none-any.whl``,
|
2019-07-23 07:22:42 +08:00
|
|
|
where ``x.y.z`` is the current version in setup.py.
|
|
|
|
|
|
|
|
|
|
To install the wheel::
|
2018-09-21 02:43:41 +08:00
|
|
|
|
|
|
|
|
pip3 install -U dist/west-x.y.z-py3-none-any.whl
|
|
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
You can ``pip3 uninstall west`` to remove this wheel before re-installing the
|
|
|
|
|
version from PyPI, etc.
|
|
|
|
|
|
|
|
|
|
Editable Install
|
|
|
|
|
~~~~~~~~~~~~~~~~
|
2018-09-21 02:43:41 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
To run west "live" from the current source code tree, run this command from the
|
|
|
|
|
top level directory in the west repository::
|
2018-09-21 02:43:41 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
pip3 install -e .
|
2018-09-21 02:43:41 +08:00
|
|
|
|
2019-07-23 07:22:42 +08:00
|
|
|
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.
|
2018-09-21 02:43:41 +08:00
|
|
|
|
|
|
|
|
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/
|