Build System & West Meta-Tool
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Zephyr build system is a complex orchestration of CMake, Ninja, and a specialized meta-tool called West. West serves as the primary interface for developers, managing multiple Git repositories (projects) within a single workspace, providing extension commands for building, flashing, and debugging, and acting as a wrapper for the underlying build engines. While the core build logic resides in CMake, West simplifies the multi-repo topology of the Zephyr Project by handling manifest management and environment configuration.
Sources: doc/develop/west/basics.rst:7-13, doc/develop/west/without-west.rst:7-15
West Meta-Tool Architecture
West is structured as a modular tool consisting of core built-in commands and "extension" commands defined by repositories within the workspace. This architecture allows West to remain agnostic to specific project versions while providing specialized functionality like west build.
Workspace Structure
A West workspace is defined by a top-level directory (topdir) containing a hidden .west folder. This folder holds the local configuration and records the location of the manifest repository.
The diagram above illustrates the typical layout of a Zephyr workspace managed by West.
Sources: doc/develop/west/basics.rst:21-45
Core vs. Extension Commands
- Built-in Commands: Provided by West itself (e.g.,
init,update,config) to manage the workspace and projects. - Extension Commands: Provided by the manifest repository or projects (e.g.,
build,flash,debug,twister). These allow Zephyr-specific workflows to be integrated directly into the West CLI.
Sources: doc/develop/west/basics.rst:58-65, doc/develop/west/zephyr-cmds.rst:11-15
Workspace Management Workflow
The lifecycle of a workspace primarily involves two commands: west init and west update.
- west init: Creates the
.westdirectory, clones the manifest repository, and configures the workspace. - west update: Reads the
west.ymlmanifest file to fetch, clone, or update all defined projects to their specified revisions.
This sequence shows the standard initialization and synchronization flow for a new developer environment.
Sources: doc/develop/west/basics.rst:72-105, doc/develop/west/built-in.rst:13-35
Build System Integration
The build system utilizes zephyr_module.py to bridge the gap between West's multi-repo management and CMake's build requirements. This script parses module.yml files across all projects to generate Kconfig and CMake snippets.
Module Processing Logic
The build system identifies "modules" by looking for zephyr/module.yml or a combination of zephyr/CMakeLists.txt and zephyr/Kconfig in project directories.
| Component | Description | Source Reference |
|---|---|---|
module.yml | Metadata file defining name, build settings, and dependencies. | scripts/zephyr_module.py:155-180 |
ZEPHYR_MODULES | CMake variable containing the list of active modules. | doc/develop/west/without-west.rst:60-65 |
west-zephyr-export | Registers the Zephyr installation in the CMake user package registry. | doc/develop/west/zephyr-cmds.rst:43-52 |
The west build Command
The west build command is a wrapper that executes the following high-level flow:
- Configuration: Invokes CMake to generate a build folder (defaulting to
build/). - Generation: CMake processes the
CMakeLists.txtfiles and modules to create Ninja build files. - Execution: Invokes the Ninja build tool to compile source code and link the final binary (e.g.,
zephyr.elf).
Sources: doc/develop/beyond-GSG.rst:138-150, doc/develop/getting_started/index.rst:452-465
Build System Features & Commands
SPDX Bill of Materials
West includes a west spdx extension to generate Software Bill of Materials (SBOM) documents. It scans source files for SPDX-License-Identifier and generates relationships between sources and build artifacts.
- app.spdx: BOM for application sources.
- zephyr.spdx: BOM for Zephyr kernel sources.
- build.spdx: BOM for final built output.
Sources: doc/develop/west/zephyr-cmds.rst:64-90
Multi-Repo Patches
The west patch command allows applying local changes across multiple repositories in a "star topology" (T2) workspace. This is used for maintaining downstream changes against upstream revisions.
Sources: doc/develop/west/zephyr-cmds.rst:245-265
SDK Management
The west sdk command manages the Zephyr Software Development Kit, allowing users to list and install cross-compilers and host tools.
Sources: doc/develop/west/zephyr-cmds.rst:352-365
Using Zephyr Without West
While not recommended, it is possible to use the build system without West by manually managing Git repositories and passing module paths directly to CMake via the ZEPHYR_MODULES variable.
# Example manual build
cmake -B build -DZEPHYR_MODULES=/path/to/module1;/path/to/module2
ninja -C build
Sources: doc/develop/west/without-west.rst:11-20, doc/develop/west/without-west.rst:55-65
Summary
The Zephyr Build System and West meta-tool provide a scalable environment for multi-repository embedded development. West acts as the central orchestrator for repository lifecycle management and provides a unified CLI, while the underlying CMake-based build system handles the technical compilation, module integration, and Kconfig generation required for diverse hardware targets.