This page introduces west’s basic concepts and provides references to further reading.
West’s built-in commands allow you to work with projects (Git repositories) under a common workspace directory.
If you’ve followed the upstream Zephyr getting started guide, your workspace looks like this:
zephyrproject/ # west topdir ├── .west/ # marks the location of the topdir │ └── config # per-workspace local configuration file │ │ # The manifest repository, never modified by west after creation: ├── zephyr/ # .git/ repo │ ├── west.yml # manifest file │ └── [... other files ...] │ │ # Projects managed by west: ├── modules/ │ └── lib/ │ └── tinycbor/ # .git/ project ├── net-tools/ # .git/ project └── [ ... other projects ...]
Here are the basic concepts you should understand about this structure. Additional details are in Workspaces.
zephyrprojectis the name of the workspace’s top level directory, or topdir. (The name
zephyrprojectis just an example – it could be anything, like
You’ll typically create the topdir and a few other files and directories using west init.
- .west directory
The topdir contains the
.westdirectory. When west needs to find the topdir, it searches for
.west, and uses its parent directory. The search starts from the current working directory (and starts again from the location in the
ZEPHYR_BASEenvironment variable as a fallback if that fails).
- configuration file
.west/configis the workspace’s local configuration file.
- manifest repository
Every west workspace contains exactly one manifest repository, which is a Git repository containing a manifest file. The location of the manifest repository is given by the manifest.path configuration option in the local configuration file.
For upstream Zephyr,
zephyris the manifest repository, but you can configure west to use any Git repository in the workspace as the manifest repository. The only requirement is that it contains a valid manifest file. See Topologies supported for information on other options, and West Manifests for details on the manifest file format.
- manifest file
The manifest file is a YAML file that defines projects, which are the additional Git repositories in the workspace managed by west. The manifest file is named
west.ymlby default; this can be overridden using the
manifest.filelocal configuration option.
You use the west update command to update the workspace’s projects based on the contents of the manifest file.
Projects are Git repositories managed by west. Projects are defined in the manifest file and can be located anywhere inside the workspace. In the above example workspace,
Any repository known to west (either the manifest repository or any project repository) can define Extensions. Extensions are extra west commands you can run when using that workspace.
The zephyr repository uses this feature to provide Zephyr-specific commands like west build. Defining these as extensions keeps west’s core agnostic to the specifics of any workspace’s Zephyr version, etc.
- ignored files
A workspace can contain additional Git repositories or other files and directories not managed by west. West basically ignores anything in the workspace except
.west, the manifest repository, and the projects specified in the manifest file.
west init and west update
The two most important workspace-related commands are
west init and
west init basics
This command creates a west workspace.
West doesn’t change your manifest repository contents after
west init is
run. Use ordinary Git commands to pull new versions, etc.
You will typically run it once, like this:
west init -m https://github.com/zephyrproject-rtos/zephyr --mr v2.5.0 zephyrproject
Create the topdir,
zephyrproject, along with
Clone the manifest repository from https://github.com/zephyrproject-rtos/zephyr, placing it into
Check out the
v2.5.0git tag in your local zephyr clone
Your workspace is now almost ready to use; you just need to run
to clone the rest of the projects into the workspace to finish.
For more details, see west init.
west update basics
This command makes sure your workspace contains Git repositories matching the projects in the manifest file.
Whenever you check out a different revision in your manifest repository, you
west update to make sure your workspace contains the
project repositories the new revision expects.
west update command reads the manifest file’s contents by:
Finding the topdir. In the
west initexample above, that means finding
.west/configin the topdir to read the
Loading the manifest file given by these options (e.g.
It then uses the manifest file to decide where missing projects should be placed within the workspace, what URLs to clone them from, and what Git revisions should be checked out locally. Project repositories which already exist are updated in place by fetching and checking out their respective Git revisions in the manifest file.
For more details, see west update.
Other built-in commands
See Built-in commands.
See the following pages for information on Zephyr’s extension commands:
See Troubleshooting West.