west: Zephyr RTOS Project meta-tool

The west.app package contains the implementation of the west command line tool and its built-in features.

Important for Extension Authors: Nothing in this package should be considered a stable API. If you are developing west extension commands, do not rely on the behavior of west.app or any of its contents, as these implementations may change without notice.

To manually create and upload Python distribution archives (wheels) to PyPI, ensure you have the necessary PyPI credentials for twine. It is critical to run git clean -ffdx first to prevent broken wheels caused by a dirty repository state.

Follow these steps:

1. Clean the repository.
2. Install/upgrade build and twine.
3. Generate the distribution archives.
4. Upload the artifacts using twine.

git clean -ffdx
pip3 install --upgrade build twine
python -m build
twine upload -u zephyr-project dist/*

When releasing a new version, create an annotated, GPG-signed tag to ensure authenticity. Replace vX.Y.Z with your actual version number and include a proper sign-off message.

git tag -a -s vX.Y.Z -m 'West vX.Y.Z

Signed-off-by: Your Name <your.name@example.com>'
git push origin vX.Y.Z

After installing an alpha version of west (e.g., pip3 install west==X.YaN), verify it by creating and updating a default Zephyr workspace on your target platform.

Note: Ensure ZEPHYR_BASE is unset in your environment before running build tests. It is acceptable if west build requires the --pristine flag during verification.

# Install the alpha version
pip3 install west==X.YaN

# Initialize and update workspace
west init zephyrproject
cd zephyrproject
west update

# Example: Build and run a QEMU target
west build -b qemu_x86 -s zephyr/samples/hello_world -d build-qemu-x86
west build -d build-qemu-x86 -t run

# Example: Build and flash a Nordic board
west build -b nrf52dk_nrf52832 -s zephyr/samples/hello_world -d build-nrf52
west flash -d build-nrf52

Manifests can define group-filter to include or exclude groups of projects. This is useful for managing different build configurations or subsets of a workspace.

Manifest-level group-filter

Defined under the group-filter: key in the manifest. Items must start with + (include) or - (exclude).

Project-level groups

Projects can be assigned to groups using the groups: key.

Filtering Rules

• A project is included if its groups match the group-filter logic.
• If a project is blocked by a manifest.project-filter configuration option, its import: statements are also ignored.

group-filter: 
  - "+hardware_enabled"
  - "-experimental"

projects:
  sensor_driver:
    groups: ["hardware_enabled"]
    url: ...

The self: section in a manifest allows you to extend the current manifest by importing data from the same repository. This is useful for modularizing large manifests.

Supported keys under self::

• path: The path to a sub-manifest file.
• import: A string, list, or dictionary specifying what to import from the manifest repository.
  • If a string: Imports a specific file path.
  • If a list: Imports multiple paths/items.
  • If a dictionary (Import Map): Provides fine-grained control using file, name-allowlist, path-allowlist, name-blocklist, path-blocklist, and path-prefix.
• userdata: Arbitrary data associated with the manifest.
• west-commands: A list of Python files to be treated as extension commands for this manifest.

self:
  path: submanifest.yml
  import: 
    - path/to/other_manifest.yml
  west-commands: my_extension_cmd.py

The west.log API is deprecated and will be removed in west v2.0 due to its reliance on global state.

When developing extensions or commands for west, you should use the equivalent methods provided by the WestCommand class instead of calling west.log directly. For example:

• Use WestCommand.dbg() instead of west.log.dbg()
• Use WestCommand.inf() instead of west.log.inf()
• And so on for other logging methods.

West configuration files support interpolation using Python's configparser syntax.

• Interpolation: Use %(other-option)s to expand to the value of another option in the same section.
• Literal Percent Signs: Because % is a special character for interpolation, you must use a double percent sign %% to represent a literal % in your configuration files.

Note: When using the west config CLI or the Configuration.set() API, values are automatically escaped, so you do not need to double the percent signs there. Manual escaping is only required when editing configuration files directly.

A project's activity is determined by two main mechanisms:

1. Project Filters: If manifest.project-filter is configured, projects are active/inactive based on regex matches against their names. A name starting with + is explicitly active; - is explicitly inactive. The last matching pattern wins.
2. Group Filters: If no explicit project filter matches, activity depends on project.groups.
   • Projects with no groups are always active.
   • If a project has groups, it is active if at least one of its groups is enabled by the manifest.group-filter configuration.

Inactive projects are generally treated as absent from the workspace for operations like updating or listing.

When you run west help or use the --help flag, the CLI determines which help output to show based on the command provided:

• west --help: Displays the top-level help, including optional arguments and logical groups of built-in commands.
• west <command> --help: Displays help specific to that command.
• Unknown commands: If you enter an unknown command, west will warn you and display the top-level help. If the manifest failed to load (e.g., due to a ManifestVersionError), it will suggest running west update to fix the manifest.
• Extensions: If the command is an extension, west attempts to run the extension's help command. If extensions cannot be loaded because the manifest failed, west will notify you that extension help is unavailable and suggest debugging with west -vv manifest --validate.