1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
.. image:: https://img.shields.io/pypi/pyversions/west?logo=python
:target: https://pypi.org/project/west/
.. image:: https://api.securityscorecards.dev/projects/github.com/zephyrproject-rtos/west/badge
:target: https://scorecard.dev/viewer/?uri=github.com/zephyrproject-rtos/west
.. image:: https://codecov.io/gh/zephyrproject-rtos/west/graph/badge.svg
:target: https://codecov.io/gh/zephyrproject-rtos/west
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.
Hacking on West
---------------
This section contains notes for getting started developing west itself.
`pip` offers many different ways to (download and) install Python
software. Below are common ways relevant to `west`; for a complete list
check `<https://pip.pypa.io/en/stable/topics/>`_
Quick Install
~~~~~~~~~~~~~
If you are not interested in source code and git history, GitHub offers
`pip` the ability to download and install a .zip archive of any random
version with a single command. This allows testing work in progress
very quickly. Examples::
pip3 uninstall west
# Pull request 830
pip3 install --dry-run https://github.com/zephyrproject-rtos/west/archive/pull/830/head.zip
# Release v1.4
pip3 install https://github.com/zephyrproject-rtos/west/archive/v1.4-branch.zip
# Someone's random version
pip3 install https://github.com/someone_you_trust/west/archive/some_branch_or_tag.zip
Warning: never install software from people or locations you do not trust!
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.
Creating a wheel package
~~~~~~~~~~~~~~~~~~~~~~~~
You can create a wheel package and distribute it to others.
To build the west wheel file::
pip3 install --upgrade build
python -m build
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.
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.
|
