West

https://github.com/zephyrproject-rtos/west
Admin
West is the Zephyr RTOS meta tool that manages multiple Git repositories under a single directory...
Tokens:6,217
Snippets:56
Trust Score:9.6
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install and Initialize West

Source: https://github.com/zephyrproject-rtos/west/blob/main/README.rst

Commands to install the West tool globally and initialize a new Zephyr project workspace.

```bash
pip3 install west
mkdir zephyrproject && cd zephyrproject
west init
west update
```

--------------------------------

### Develop and Build West

Source: https://github.com/zephyrproject-rtos/west/blob/main/README.rst

Commands for developers to perform an editable install, build distribution wheels, and run the test suite.

```bash
# Editable install for live development
pip3 install -e .

# Build a wheel package
uv build
# Or using standard build module
python -m build

# Run tests
uv run poe all
```

--------------------------------

### Access West Configuration

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Demonstrates how to iterate through configuration options and retrieve file paths for local or global configuration files.

```python
for option, value in config.items():
    print(f"{option} = {value}")

search_paths = config.get_search_paths(ConfigFile.ALL)
existing_paths = config.get_existing_paths(ConfigFile.LOCAL)
```

--------------------------------

### Implement Custom West Extension Commands

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Shows how to subclass WestCommand to create custom CLI commands. It includes argument parsing, workspace interaction, logging, and error handling.

```python
from west.commands import WestCommand, CommandError, Verbosity
import argparse

class MyCustomCommand(WestCommand):
    def __init__(self):
        super().__init__(name='mycommand', help='brief help text', description='Detailed description', accepts_unknown_args=False, requires_workspace=True)

    def do_add_parser(self, parser_adder) -> argparse.ArgumentParser:
        parser = parser_adder.add_parser(self.name, help=self.help, description=self.description)
        parser.add_argument('--option', help='an option')
        return parser

    def do_run(self, args, unknown):
        self.inf(f"Topdir: {self.topdir}")
        if self.has_manifest:
            for project in self.manifest.projects:
                self.dbg(f"Project: {project.name}")
        self.check_call(['git', 'status'], cwd=self.topdir)
```

--------------------------------

### Utilize West Workspace Utilities

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Covers common utility functions for finding the workspace root, managing directory paths, and preparing shell commands.

```python
from west.util import west_topdir, west_dir, WestNotFound, quote_sh_list

try:
    topdir = west_topdir()
except WestNotFound:
    print("Not in a west workspace")

cmd = ['git', 'commit', '-m', 'message with spaces']
shell_cmd = quote_sh_list(cmd)
```

--------------------------------

### Utility Functions

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Core utility functions for workspace discovery and path manipulation.

```APIDOC
## UTILITY FUNCTIONS

### Description
Helper functions provided by `west.util` for common workspace operations.

### Functions
- **west_topdir(start=None, fall_back=True)**: Returns the path to the root of the current West workspace.
- **west_dir()**: Returns the path to the hidden `.west` directory.
- **escapes_directory(path, parent)**: Returns True if the given path is outside the specified parent directory.
- **quote_sh_list(list)**: Safely quotes a list of strings for shell execution.
```

--------------------------------

### Working with Projects using Python API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The `west.manifest.Project` class represents an individual project within a West workspace, offering access to its metadata and Git operations. It allows checking project status, retrieving file content at specific revisions, and running Git commands.

```python
from west.manifest import Manifest, Project, QUAL_MANIFEST_REV_BRANCH

manifest = Manifest.from_topdir()

for project in manifest.projects[1:]:  # Skip manifest project at index 0
    # Project attributes
    print(f"Name: {project.name}")
    print(f"URL: {project.url}")
    print(f"Revision: {project.revision}")
    print(f"Path: {project.path}")
    print(f"Absolute path: {project.abspath}")
    print(f"POSIX path: {project.posixpath}")
    print(f"Clone depth: {project.clone_depth}")
    print(f"Remote name: {project.remote_name}")
    print(f"Groups: {project.groups}")
    print(f"West commands: {project.west_commands}")
    print(f"Submodules: {project.submodules}")
    print(f"User data: {project.userdata}")

    # Check if cloned
    if project.is_cloned():
        # Get SHA for a revision
        sha = project.sha('HEAD')
        manifest_rev_sha = project.sha(QUAL_MANIFEST_REV_BRANCH)

        # Check if up to date with manifest
        if project.is_up_to_date():
            print(f"{project.name} is up to date")

        # Check ancestor relationship
        if project.is_ancestor_of('v1.0.0', 'HEAD'):
            print("HEAD contains v1.0.0")

        # Run git commands
        result = project.git(['status', '--porcelain'], capture_stdout=True)
        print(result.stdout.decode())

        # Read file at specific revision
        content = project.read_at('README.md', rev='HEAD')

        # List directory at revision
        files = project.listdir_at('src/', rev='main')

    # Export project as dict
    project_dict = project.as_dict()
```

--------------------------------

### Configuration Class API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The Configuration class allows for programmatic reading and writing of West configuration settings across local and global files.

```APIDOC
## Configuration Class API

### Description
Access and modify west configuration programmatically using the `Configuration` class.

### Method
N/A (Instance Methods)

### Parameters
- **key** (string) - Required - The configuration key to get or set.
- **value** (string) - Optional - The value to set for the key.

### Request Example
config.set('update.fetch', 'always', configfile=ConfigFile.LOCAL)

### Response
#### Success Response (200)
- **value** (any) - Returns the requested configuration value or None if not found.
```

--------------------------------

### Define West Manifest Structure

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Provides a template for the west.yml manifest file, illustrating how to define remotes, project groups, and individual project configurations.

```yaml
manifest:
  version: "1.2"
  remotes:
    - name: zephyrproject
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      revision: v3.5.0
    - name: mylib
      url: https://github.com/myorg/mylib
      revision: develop
```

--------------------------------

### Loading and Manipulating Manifests with Python API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The `west.manifest.Manifest` class provides programmatic access to load and manipulate West manifest files. Manifests can be loaded from a workspace top directory, a specific file, or raw YAML data, with options to ignore imports. It allows accessing manifest properties and iterating over projects.

```python
from west.manifest import Manifest, ManifestProject, ImportFlag
from pathlib import Path

# Load manifest from workspace topdir
manifest = Manifest.from_topdir(topdir='/path/to/workspace')

# Load from specific manifest file
manifest = Manifest.from_file(source_file='/path/to/west.yml')

# Load from raw YAML data
yaml_data = """
manifest:
  remotes:
    - name: origin
      url-base: https://github.com/myorg
  projects:
    - name: myproject
      remote: origin
      revision: main
"""
manifest = Manifest.from_data(yaml_data)

# Ignore imports during loading
manifest = Manifest.from_data(yaml_data, import_flags=ImportFlag.IGNORE)

# Access manifest properties
print(f"Manifest path: {manifest.abspath}")
print(f"Topdir: {manifest.topdir}")
print(f"Has imports: {manifest.has_imports}")
print(f"Group filter: {manifest.group_filter}")

# Iterate over projects
for project in manifest.projects:
    if isinstance(project, ManifestProject):
        print(f"Manifest repo: {project.path}")
    else:
        print(f"Project: {project.name} at {project.path}")
        print(f"  URL: {project.url}")
        print(f"  Revision: {project.revision}")
        print(f"  Groups: {project.groups}")

# Get specific projects by name or path
projects = manifest.get_projects(['zephyr', 'modules/hal/stm32'])

# Check if project is active
for project in manifest.projects:
    if manifest.is_active(project):
        print(f"{project.name} is active")

# Export manifest as YAML
yaml_output = manifest.as_yaml()

# Export frozen manifest (with SHAs)
frozen_yaml = manifest.as_frozen_yaml()

# Export as dict
manifest_dict = manifest.as_dict()
frozen_dict = manifest.as_frozen_dict()
```

--------------------------------

### Manifest File (west.yml)

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Schema definition for the west.yml manifest file which manages projects, remotes, and workspace configuration.

```APIDOC
## MANIFEST west.yml

### Description
The manifest file defines the structure of the West workspace, including remotes, project definitions, and group filters.

### Key Sections
- **manifest.version**: Schema version (e.g., "1.2").
- **remotes**: List of URL bases for project cloning.
- **projects**: List of repositories to manage. Each project supports:
  - **name**: Unique project identifier.
  - **revision**: Git branch, tag, or commit hash.
  - **path**: Local filesystem path.
  - **import**: Configuration for importing sub-manifests.
- **self**: Configuration for the manifest repository itself.
```

--------------------------------

### Expand user path in West

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

Uses the expand_path utility to resolve a tilde-prefixed path string into a standard Path object. This is useful for normalizing workspace directory references across different user environments.

```python
from west.util import expand_path

# Expand user path
path = expand_path('~/projects/zephyr')  # Returns Path object
```

--------------------------------

### Running Commands Across Multiple Projects with West Forall

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The `west forall` command allows executing a given shell command in multiple projects within a West workspace. It supports filtering projects by name, including inactive projects, and filtering by group.

```shell
west forall -c "git branch -vv" zephyr hal_stm32
```

```shell
west forall --all -c "ls -la"
```

```shell
west forall -g bluetooth -c "git status"
```

--------------------------------

### Create and Push West Release Branch

Source: https://github.com/zephyrproject-rtos/west/blob/main/MAINTAINERS.rst

Commands to create a new release branch from the main branch and push it to the remote repository. This is a critical step in the release lifecycle for minor versions.

```bash
git checkout -b vX.Y-branch origin/main
git push origin vX.Y-branch
```

--------------------------------

### Accessing and Modifying West Configuration with Python API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The `west.configuration.Configuration` class allows programmatic access to and modification of West configuration settings. Configuration values can be retrieved and set for different precedence levels (local, global) and types (string, boolean, integer).

```python
from west.configuration import Configuration, ConfigFile
from pathlib import Path

# Load configuration for a workspace
config = Configuration(topdir='/path/to/workspace')

# Get configuration values
manifest_path = config.get('manifest.path')
fetch_strategy = config.get('update.fetch', default='smart')

# Get typed values
use_color = config.getboolean('color.ui', default=True)
depth = config.getint('update.clone-depth', default=None)

# Get from specific config file
local_path = config.get('manifest.path', configfile=ConfigFile.LOCAL)
global_setting = config.get('color.ui', configfile=ConfigFile.GLOBAL)

# Set configuration values
config.set('update.fetch', 'always', configfile=ConfigFile.LOCAL)
config.set('color.ui', 'true', configfile=ConfigFile.GLOBAL)

# Delete configuration
config.delete('update.fetch', configfile=ConfigFile.LOCAL)
config.delete('manifest.group-filter')  # Delete from highest precedence file
```

--------------------------------

### Project Class API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The Project class provides an interface for interacting with individual git repositories managed by West, including metadata access and git operations.

```APIDOC
## Project Class API

### Description
Work with individual projects using the `Project` class which provides Git operations and project metadata.

### Method
N/A (Instance Methods)

### Parameters
- **project** (object) - Required - An instance of a project retrieved from the Manifest object.

### Request Example
project.git(['status', '--porcelain'], capture_stdout=True)

### Response
#### Success Response (200)
- **result** (object) - Returns a result object containing stdout, stderr, and return codes.
```

--------------------------------

### Searching Code with West Grep

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The `west grep` command facilitates searching for patterns across projects in a West workspace. It supports using `git grep` (default) or `ripgrep` as the backend search tool and allows specifying projects to search within.

```shell
west grep "CONFIG_"
```

```shell
west grep --tool ripgrep "pattern"
```

```shell
west grep -p zephyr -p hal_stm32 "function_name"
```

--------------------------------

### WestCommand Extension API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

API for creating custom command-line extensions for the West tool by subclassing WestCommand.

```APIDOC
## CLASS WestCommand

### Description
Base class for creating custom West commands. Extensions must be registered in a west-commands.yml file.

### Methods
- **do_add_parser(parser_adder)**: Defines command-line arguments using argparse.
- **do_run(args, unknown)**: Implements the command logic, providing access to workspace, manifest, and configuration data.

### Attributes
- **self.topdir**: Path to the workspace root.
- **self.manifest**: Access to project manifest data.
- **self.config**: Access to local/global configuration settings.

### Logging Methods
- **self.inf(msg)**: Info level logging.
- **self.dbg(msg)**: Debug level logging.
- **self.wrn(msg)**: Warning level logging.
- **self.err(msg)**: Error level logging.
- **self.die(msg, exit_code)**: Fatal error logging and exit.
```

--------------------------------

### Manifest Class API

Source: https://context7.com/zephyrproject-rtos/west/llms.txt

The Manifest class provides methods to load, parse, and manipulate west.yml manifest files programmatically.

```APIDOC
## Manifest Class API

### Description
Load and manipulate manifests programmatically using the `Manifest` class from `west.manifest`.

### Method
N/A (Class Methods)

### Parameters
#### Path Parameters
- **topdir** (string) - Optional - Path to the workspace top directory.
- **source_file** (string) - Optional - Path to a specific manifest file.

### Request Example
from west.manifest import Manifest
manifest = Manifest.from_topdir(topdir='/path/to/workspace')

### Response
#### Success Response (200)
- **manifest** (object) - Returns a Manifest instance containing project lists and metadata.
```
Tokens:
Raw