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