West (Zephyr RTOS Meta-Tool)

1.5.0 · active · verified Sat Apr 11

West is the Zephyr RTOS project's meta-tool, designed to manage multiple Git repositories under a single directory using a manifest file. It provides commands for initializing workspaces, updating repositories, building, flashing, and debugging Zephyr applications. While primarily a command-line interface tool, `west` also exposes Python APIs for advanced programmatic interaction and extending its functionality. It maintains an active development cycle with frequent releases, often including alpha versions before stable major/minor updates.

Warnings

breaking Python 3.8 support was dropped in West v1.3.0. Users must use Python 3.9 or later.
Fix: Upgrade your Python environment to version 3.9 or higher.
breaking West v1.0 and later versions are not compatible with Zephyr v1.14 LTS releases. For Zephyr v1.14, West v0.14 or earlier must be used.
Fix: For Zephyr v1.14 LTS, downgrade west to version 0.14 or earlier (e.g., `pip install west==0.14.0`). For newer Zephyr versions, ensure you are using a compatible west version as specified by the Zephyr documentation.
breaking Starting with West v1.0, abbreviated command-line arguments are no longer accepted (e.g., `--keep-d` for `--keep-descendants`). Full argument names are now required.
Fix: Update scripts and commands to use the full, unambiguous argument names. Consult `west <command> --help` for correct options.
deprecated The `west.log` module is deprecated since West v1.0. `WestCommand` methods like `dbg()`, `inf()`, `wrn()`, `err()` should be used instead for logging output within West extensions.
Fix: If developing West extensions, migrate from `west.log` functions to the corresponding methods provided by `west.commands.WestCommand` instances.
gotcha Since West v0.10.1, `west init --manifest-rev` (`--mr`) no longer defaults to `master`. Instead, it queries the remote repository for its default branch name (e.g., `main`).
Fix: Explicitly specify the revision using `--mr <branch_name>` if your manifest repository's default branch is not the one you intend to use for initialization, or if it changed from `master` to `main`.
gotcha Beginning with a certain version (around v1.0), `west update` now synchronizes Git submodules in projects by default. This can cause unexpected behavior if not anticipated.
Fix: If this behavior is undesirable, you can disable it by setting the `update.sync-submodules` configuration option to `false` in your West configuration.

Install

pip install west Install latest stable version

Imports

WestCommand
```
from west.commands import WestCommand
```
Primarily used for developing custom West extension commands.
Configuration
```
from west.configuration import Configuration
```
Recommended API for reading and managing West's configuration files (system, global, local).
Manifest
```
from west.manifest import Manifest
```
Used for programmatic access to the West manifest file structure and its projects.

Quickstart

This quickstart demonstrates how to use `west` from a Python script to initialize and update a Zephyr RTOS workspace. It uses `subprocess` to execute `west` CLI commands, which is the most common way to automate `west` operations in Python. Ensure `git` is installed and available in your system's PATH before running.

import subprocess
import os
import shutil

# Ensure a clean state for the example
if os.path.exists('zephyrproject'):
    shutil.rmtree('zephyrproject')

try:
    # Initialize a west workspace with the default Zephyr manifest
    print("Initializing west workspace...")
    subprocess.run(['west', 'init', 'zephyrproject'], check=True, capture_output=True)
    print("\nWest workspace initialized in 'zephyrproject'.")

    # Change into the workspace directory
    os.chdir('zephyrproject')

    # Update the repositories defined in the manifest
    print("\nUpdating repositories (this may take some time)...")
    subprocess.run(['west', 'update'], check=True, capture_output=True)
    print("\nRepositories updated successfully.")

    # List the projects in the workspace
    print("\nListing projects in the workspace:")
    result = subprocess.run(['west', 'list'], check=True, capture_output=True, text=True)
    print(result.stdout)

except subprocess.CalledProcessError as e:
    print(f"An error occurred during west command execution: {e}")
    print(f"Stdout: {e.stdout.decode()}")
    print(f"Stderr: {e.stderr.decode()}")
except FileNotFoundError:
    print("Error: 'west' command not found. Please ensure west is installed and in your PATH.")
finally:
    # Clean up the created directory for re-runnability
    os.chdir('..') # Go back up from zephyrproject
    if os.path.exists('zephyrproject'):
        shutil.rmtree('zephyrproject')
        print("\nCleaned up 'zephyrproject' directory.")

view raw JSON →