Skip to content

Commit d3bb3cf

Browse files
Marti Bolivarcarlescufi
Marti Bolivar
authored and
carlescufi
committed
doc: west: add missing parts for zephyr v1.14
- add glossary terms for important concepts we have to explain often, like "west installation" - add autodoc directives for pulling in west API docs - add missing documentation for built-in features like west's configuration, extension commands, etc. - add missing documentation for "west sign" extension - describe the manifest in a self-contained way rather than linking to the relevant pykwalify schema, also adding a missing reference to "west manifest" in the miscellaneous multi-repo commands list - move various details regarding history and motivation to why.rst among other changes to repo-tool.rst, leaving it closer to a "tell me what I really need to know" style overview - update planned features Fixes: #14992 Signed-off-by: Marti Bolivar <[email protected]>
1 parent cd79519 commit d3bb3cf

12 files changed

+1192
-417
lines changed

‎doc/getting_started/index.rst

+3-4
Original file line numberDiff line numberDiff line change
@@ -100,10 +100,9 @@ Clone the Zephyr source code repositories from GitHub using the ``west`` tool:
100100
Running ``west init`` will clone west itself into ``./.west/west`` and
101101
initialize a local installation. Running ``west update`` will pull all the
102102
projects referenced by the manifest file (:file:`zephyr/west.yml`) into the
103-
folders specified in it. See :ref:`west-struct-installation` for additional
104-
details and a list of the folders and files that west will create as part of
105-
the process and :ref:`west-multi-repo` for more on how ``west`` helps manage
106-
multiple repositories.
103+
folders specified in it. See :ref:`west-multi-repo` for additional details, a
104+
list of the folders and files that west will create as part of the process,
105+
and more on how ``west`` helps manage multiple repositories.
107106

108107
.. warning::
109108

‎doc/glossary.rst

+20
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,26 @@ Glossary of Terms
6565
The set of Zephyr-supplied files that implement the Zephyr kernel,
6666
including its core services, device drivers, network stack, and so on.
6767

68+
west
69+
A multi-repo meta-tool developed for the Zephyr project. See :ref:`west`.
70+
71+
west installation
72+
A directory on your system with a :file:`.west` subdirectory and
73+
a :term:`west manifest repository`. You clone the Zephyr source
74+
code onto your system by creating a west installation using the
75+
``west init`` command. See :ref:`west-multi-repo`.
76+
77+
west manifest
78+
A YAML file named :file:`west.yml` which describes projects, or the Git
79+
repositories which make up a :term:`west installation`, along with
80+
additional metadata. See :ref:`west-multi-repo` for general information
81+
and :ref:`west-manifests` for details.
82+
83+
west manifest repository
84+
The Git repository in a :term:`west installation` which contains the
85+
:term:`west manifest`. Its location is given by the :ref:`manifest.path
86+
configuration option <west-config-index>`. See :ref:`west-multi-repo`.
87+
6888
XIP
6989
(eXecute In Place) a method of executing programs directly from long
7090
term storage rather than copying it into RAM, saving writable memory for

‎doc/guides/west/config.rst

+152
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
.. _west-config:
2+
3+
Configuration
4+
#############
5+
6+
This page documents west's configuration file system, the ``west config``
7+
command, and configuration options used by built-in commands. For API
8+
documentation on the ``west.configuration`` module, see
9+
:ref:`west-apis-configuration`.
10+
11+
West Configuration Files
12+
------------------------
13+
14+
West's configuration file syntax is INI-like; here is an example file:
15+
16+
.. code-block:: ini
17+
18+
[manifest]
19+
path = zephyr
20+
21+
[zephyr]
22+
base = zephyr
23+
24+
Above, the ``manifest`` section has option ``path`` set to ``zephyr``. Another
25+
way to say the same thing is that ``manifest.path`` is ``zephyr`` in this file.
26+
27+
There are three types of configuration file:
28+
29+
1. **System**: Settings in this file affect west's behavior for every user
30+
logged in to the computer. Its location depends on the platform:
31+
32+
- Linux: :file:`/etc/westconfig`
33+
- macOS: :file:`/usr/local/etc/westconfig`
34+
- Windows: :file:`%PROGRAMDATA%\\west\\config`
35+
36+
2. **Global** (per user): Settings in this file affect how west behaves when
37+
run by a particular user on the computer.
38+
39+
- All platforms: the default is :file:`.westconfig` in the user's home
40+
directory.
41+
- Linux note: if the environment variable :envvar:`XDG_CONFIG_HOME` is set,
42+
then :file:`$XDG_CONFIG_HOME/west/config` is used.
43+
- Windows note: the following environment variables are tested to find the
44+
home directory: :envvar:`%HOME%`, then :envvar:`%USERPROFILE%`, then a
45+
combination of :envvar:`%HOMEDRIVE%` and :envvar:`%HOMEPATH%`.
46+
47+
3. **Local**: Settings in this file affect west's behavior for the
48+
current :term:`west installation`. The file is :file:`.west/config`, relative
49+
to the installation's root directory.
50+
51+
A setting in a file which appears lower down on this list overrides an earlier
52+
setting. For example, if ``color.ui`` is ``true`` in the system's configuration
53+
file, but ``false`` in the installation's, then the final value is
54+
``false``. Similarly, settings in the user configuration file override system
55+
settings, and so on.
56+
57+
.. _west-config-cmd:
58+
59+
West ``config`` Command
60+
-----------------------
61+
62+
The built-in ``config`` command can be used to get and set configuration
63+
values. You can pass ``west config`` the options ``--system``, ``--global``, or
64+
``--local`` to specify which configuration file to use. Only one of these can
65+
be used at a time. If none is given, then writes default to ``--local``, and
66+
reads show the final value after applying overrides.
67+
68+
Some examples for common uses follow; run ``west config -h`` for detailed help,
69+
and see :ref:`west-config-index` for more details on built-in options.
70+
71+
To set ``manifest.path`` to :file:`some-other-manifest`:
72+
73+
.. code-block:: console
74+
75+
west config manifest.path some-other-manifest
76+
77+
Doing the above means that commands like ``west update`` will look for the
78+
:term:`west manifest` inside the :file:`some-other-manifest` directory
79+
(relative to the installation root directory) instead of the directory given to
80+
``west init``, so be careful!
81+
82+
To read ``zephyr.base``, the value which will be used as ``ZEPHYR_BASE`` if it
83+
is unset in the calling environment (also relative to the installation root):
84+
85+
.. code-block:: console
86+
87+
west config zephyr.base
88+
89+
You can switch to another zephyr repository without changing ``manifest.path``
90+
-- and thus the behavior of commands like ``west update`` -- using:
91+
92+
.. code-block:: console
93+
94+
west config zephyr.base some-other-zephyr
95+
96+
This can be useful if you use commands like ``git worktree`` to create your own
97+
zephyr directories, and want commands like ``west build`` to use them instead
98+
of the zephyr repository specified in the manifest. (You can go back to using
99+
the directory in the upstream manifest by running ``west config zephyr.base
100+
zephyr``.)
101+
102+
To set ``color.ui`` to ``false`` in the global (user-wide) configuration file,
103+
so that west will no longer print colored output for that user when run in any
104+
installation:
105+
106+
.. code-block:: console
107+
108+
west config --global color.ui false
109+
110+
To undo the above change:
111+
112+
.. code-block:: console
113+
114+
west config --global color.ui true
115+
116+
.. _west-config-index:
117+
118+
Built-in Configuration Options
119+
------------------------------
120+
121+
The following table documents configuration options supported by west's built-in
122+
commands.
123+
124+
.. NOTE: docs authors: keep this table sorted by section, then option.
125+
126+
.. list-table::
127+
:widths: 10 30
128+
:header-rows: 1
129+
130+
* - Option
131+
- Description
132+
* - ``color.ui``
133+
- Boolean. If ``true`` (the default), then west output is colorized when
134+
stdout is a terminal.
135+
* - ``commands.allow_extensions``
136+
- Boolean, default ``true``, disables :ref:`west-extensions` if ``false``
137+
* - ``manifest.path``
138+
- String, relative path from the :term:`west installation` root directory
139+
to the manifest repository used by ``west update`` and other commands
140+
which parse the manifest. Set locally by ``west init``.
141+
* - ``zephyr.base``
142+
- String, default value to set for the :envvar:`ZEPHYR_BASE` environment
143+
variable while the west command is running. By default, this is set to
144+
the path to the manifest project with path :file:`zephyr` (if there is
145+
one) during ``west init``. If the variable is already set, then this
146+
setting is ignored unless ``zephyr.base-prefer`` is ``"configfile"``.
147+
* - ``zephyr.base-prefer``
148+
- String, one the values ``"env"`` and ``"configfile"``. If set to
149+
``"env"`` (the default), setting :envvar:`ZEPHYR_BASE` in the calling
150+
environment overrides the value of the ``zephyr.base`` configuration
151+
option. If set to ``"configfile"``, the configuration option wins
152+
instead.

0 commit comments

Comments
 (0)