Container-Backed Zephyr Builds via a west Extension (west-env)

[tbitcs]

Problem / Pain Point

Today, Zephyr does not provide a first-class, west-native way to run builds inside containers.

While Zephyr does document how to install dependencies manually and does publish
a reference Docker image, container usage remains:

• manual (docker run ...)
• external to west
• inconsistent across teams and CI
• especially painful on Windows systems

Common pain points I’ve repeatedly seen (and personally hit):

• Long, fragile host setup instructions
• Subtle dependency drift between developers and CI
• Windows builds breaking due to toolchain or Python issues
• No clean way to say “this project builds in this environment”
• Containers treated as ad-hoc scripts rather than a reproducible contract

Containers clearly solve many of these problems, but Zephyr has no opinionated,
west-aligned abstraction for them today.

---

Proposed Direction

This idea explores extending west with an environment abstraction that allows
Zephyr projects to build:

• natively on the host or
• transparently inside a container

…without modifying Zephyr itself and without changing existing west workflows.

Key concept

Containers are an implementation detail, not a user-facing workflow.

Developers still run:

west build ...

They just get a reproducible, known-good environment underneath.

---

The Experiment: west-env

I’ve been prototyping this idea in a west extension called west-env:

👉 Repository:
https://github.com/bitconcepts/west-env

west-env is intentionally not a workspace, not a fork, and not a build system.
It is a thin orchestration layer around west build.

What it does

• Adds west env subcommands:

  • west env build
  • west env shell
  • west env doctor

• Uses a simple west-env.yml file alongside west.yml

• Runs west build:

  • natively or
  • inside a container (Docker / Podman)

• Keeps all workspace state on the host

• Requires zero changes to Zephyr core

What it deliberately does not do

• No custom build system
• No workspace magic
• No container shells required
• No mutation of repo state
• No replacement for west

---

Why a west Extension?

This approach is intentionally aligned with Zephyr’s existing mental model:

• west already owns:

  • manifests
  • modules
  • build orchestration

• west extensions are the sanctioned way to experiment

• No new top-level tooling for users to learn

From the user’s perspective:

west env build -b nrf52840dk/nrf52840 samples/hello_world

…behaves exactly like west build, just with a reproducible environment.

---

Container Model (High Level)

• The container provides:

  • toolchain (Zephyr SDK)
  • CMake / Ninja
  • Python deps

• The host workspace provides:

  • .west/
  • zephyr/
  • modules
  • build output

• The workspace is mounted at /work

• Containers are disposable and stateless

This is enforced via a documented container contract in the repo.

---

Status & Compatibility

This experiment is currently validated with:

• Zephyr: v4.3.0

• Zephyr SDK: 0.17.4

• Host platforms tested:

  • Windows 11 + Docker Desktop
  • WSL2 (recommended on Windows)

Container Image

By default, the project uses a prebuilt image from GitHub Container Registry:

ghcr.io/bitconcepts/zephyr-build-env:latest

However, the design does not depend on this specific image.

It may also work with Zephyr’s upstream image:
https://github.com/zephyrproject-rtos/docker-image

Swapping images is a config change, not a code change.

---

Quick Try-It (Minimal)

The repo includes a copy-only reference workspace.

High-level flow:

1. Copy example/workspace/ → new directory
2. Run bootstrap script
3. Enter workspace shell
4. west env doctor
5. west env build ...

Authoritative, step-by-step instructions live here:

• Workspace setup:
  https://github.com/bitconcepts/west-env/tree/main/example
• Container contract:
  https://github.com/bitconcepts/west-env/tree/main/container

---

Why I’m Posting This in Ideas

This is not a proposal to upstream code immediately.

This is a request for:

• feedback on the concept

• discussion about scope and boundaries

• interest from:

  • Zephyr maintainers
  • CI users
  • Windows users
  • anyone fighting toolchain drift

If there’s interest, the next steps would be:

1. Refine the model with community feedback

2. Write an RFC-style document

3. Decide whether this belongs as:

   • an official extension
   • a reference implementation
   • or input into future west features

---

Discussion Prompts

I’d love feedback on:

• Is container-backed building something Zephyr wants to standardize?
• Does a west extension feel like the right abstraction layer?
• Are there sharp edges or missing cases you see immediately?
• Would you use something like this in CI or locally?

Thanks for reading — happy to demo or iterate publicly.