1.. _west-basics:
2
3Basics
4######
5
6This page introduces west's basic concepts and provides references to further
7reading.
8
9West's built-in commands allow you to work with :term:`projects <west project>`
10(Git repositories) under a common :term:`workspace <west workspace>` directory.
11
12West works in the following manner: the ``west init`` command creates the
13:term:`west workspace`, and clones the :term:`manifest repo <west manifest
14repository>`, while the ``west update`` command initially clones, and later updates, the
15:term:`projects <west project>` listed in the manifest in the workspace.
16
17Example workspace
18*****************
19
20If you've followed the :ref:`getting_started`, your local
21:term:`west workspace`, which in this case is the folder named
22:file:`zephyrproject` as well as all its subfolders, looks like this:
23
24.. code-block:: none
25
26   zephyrproject/                 # west topdir
27   ├── .west/                     # marks the location of the topdir
28   │   └── config                 # per-workspace local configuration file
29   │
30   │   # The manifest repository, never modified by west after creation:
31   ├── zephyr/                    # .git/ repo
32   │   ├── west.yml               # manifest file
33   │   └── [... other files ...]
34   │
35   │   # Projects managed by west:
36   ├── modules/
37   │   └── lib/
38   │       └── zcbor/             # .git/ project
39   ├── tools/
40   │   └── net-tools/             # .git/ project
41   └── [ ... other projects ...]
42
43.. _west-workspace:
44
45Workspace concepts
46******************
47
48Here are the basic concepts you should understand about this structure.
49Additional details are in :ref:`west-workspaces`.
50
51topdir
52  Above, :file:`zephyrproject` is the name of the workspace's top level
53  directory, or *topdir*. (The name :file:`zephyrproject` is just an example
54  -- it could be anything, like ``z``, ``my-zephyr-workspace``, etc.)
55
56  You'll typically create the topdir and a few other files and directories
57  using :ref:`west init <west-init-basics>`.
58
59.west directory
60  The topdir contains the :file:`.west` directory. When west needs to find
61  the topdir, it searches for :file:`.west`, and uses its parent directory.
62  The search starts from the current working directory (and starts again from
63  the location in the :envvar:`ZEPHYR_BASE` environment variable as a
64  fallback if that fails).
65
66configuration file
67  The file :file:`.west/config` is the workspace's :ref:`local configuration
68  file <west-config>`.
69
70manifest repository
71  Every west workspace contains exactly one *manifest repository*, which is a
72  Git repository containing a *manifest file*. The location of the manifest
73  repository is given by the :ref:`manifest.path configuration option
74  <west-config-index>` in the local configuration file.
75
76  For upstream Zephyr, :file:`zephyr` is the manifest repository, but you can
77  configure west to use any Git repository in the workspace as the manifest
78  repository. The only requirement is that it contains a valid manifest file.
79  See :ref:`west-topologies` for information on other options, and
80  :ref:`west-manifests` for details on the manifest file format.
81
82manifest file
83  The manifest file is a YAML file that defines *projects*, which are the
84  additional Git repositories in the workspace managed by west. The manifest
85  file is named :file:`west.yml` by default; this can be overridden using the
86  ``manifest.file`` local configuration option.
87
88  You use the :ref:`west update <west-update-basics>` command to update the
89  workspace's projects based on the contents of the manifest file.
90
91projects
92  Projects are Git repositories managed by west. Projects are defined in the
93  manifest file and can be located anywhere inside the workspace. In the above
94  example workspace, ``zcbor`` and ``net-tools`` are projects.
95
96  By default, the Zephyr :ref:`build system <build_overview>` uses west to get
97  the locations of all the projects in the workspace, so any code they contain
98  can be used as :ref:`modules`. Note however that modules and projects
99  :ref:`are conceptually different <modules-vs-projects>`.
100
101extensions
102  Any repository known to west (either the manifest repository or any project
103  repository) can define :ref:`west-extensions`. Extensions are extra west
104  commands you can run when using that workspace.
105
106  The zephyr repository uses this feature to provide Zephyr-specific commands
107  like :ref:`west build <west-building>`. Defining these as extensions keeps
108  west's core agnostic to the specifics of any workspace's Zephyr version,
109  etc.
110
111ignored files
112  A workspace can contain additional Git repositories or other files and
113  directories not managed by west. West basically ignores anything in the
114  workspace except :file:`.west`, the manifest repository, and the projects
115  specified in the manifest file.
116
117west init and west update
118*************************
119
120The two most important workspace-related commands are ``west init`` and ``west
121update``.
122
123.. _west-init-basics:
124
125``west init`` basics
126--------------------
127
128This command creates a west workspace.
129
130.. important::
131
132   West doesn't change your manifest repository contents after ``west init`` is
133   run. Use ordinary Git commands to pull new versions, etc.
134
135You will typically run it once, like this:
136
137.. code-block:: shell
138
139   west init -m https://github.com/zephyrproject-rtos/zephyr --mr v2.5.0 zephyrproject
140
141This will:
142
143#. Create the topdir, :file:`zephyrproject`, along with
144   :file:`.west` and :file:`.west/config` inside it
145#. Clone the manifest repository from
146   https://github.com/zephyrproject-rtos/zephyr, placing it into
147   :file:`zephyrproject/zephyr`
148#. Check out the ``v2.5.0`` git tag in your local zephyr clone
149#. Set ``manifest.path`` to ``zephyr`` in :file:`.west/config`
150#. Set ``manifest.file`` to ``west.yml``
151
152Your workspace is now almost ready to use; you just need to run ``west update``
153to clone the rest of the projects into the workspace to finish.
154
155For more details, see :ref:`west-init`.
156
157.. _west-update-basics:
158
159``west update`` basics
160----------------------
161
162This command makes sure your workspace contains Git repositories matching the
163projects in the manifest file.
164
165.. important::
166
167   Whenever you check out a different revision in your manifest repository, you
168   should run ``west update`` to make sure your workspace contains the
169   project repositories the new revision expects.
170
171The ``west update`` command reads the manifest file's contents by:
172
173#. Finding the topdir. In the ``west init`` example above, that
174   means finding :file:`zephyrproject`.
175#. Loading :file:`.west/config` in the topdir to read the ``manifest.path``
176   (e.g. ``zephyr``) and ``manifest.file`` (e.g. ``west.yml``) options.
177#. Loading the manifest file given by these options (e.g.
178   :file:`zephyrproject/zephyr/west.yml`).
179
180It then uses the manifest file to decide where missing projects should be
181placed within the workspace, what URLs to clone them from, and what Git
182revisions should be checked out locally. Project repositories which already
183exist are updated in place by fetching and checking out their respective Git
184revisions in the manifest file.
185
186For more details, see :ref:`west-update`.
187
188Other built-in commands
189***********************
190
191See :ref:`west-built-in-cmds`.
192
193.. _west-zephyr-extensions:
194
195Zephyr Extensions
196*****************
197
198See the following pages for information on Zephyr's extension commands:
199
200- :ref:`west-build-flash-debug`
201- :ref:`west-sign`
202- :ref:`west-zephyr-ext-cmds`
203- :ref:`west-shell-completion`
204
205Troubleshooting
206***************
207
208See :ref:`west-troubleshooting`.
209