Get started with Workshop¶

In this tutorial, you’ll create a Zephyr 26.04 LTS workspace and build and run the Hello World sample.

Prerequisites¶

A host running Ubuntu 26.04 or another Linux distribution that supports snaps.
Access to the internet.
Permission to use sudo on the host.

Install Workshop and LXD¶

Workshop is the standard development environment for Zephyr 26.04 LTS. The Workshop definition contains the Zephyr source, Python environment, SDK bundle, and x86 toolchain. LXD is a container manager that Workshop uses to create and run its development environment.

Install LXD 6 and Workshop:

$ sudo snap install --channel=6/stable lxd
$ sudo snap install --classic workshop

To avoid using sudo for every LXD operation, add your user to the lxd group:

$ sudo usermod --append --groups lxd "$USER"
$ newgrp lxd

Define a development environment¶

Create a directory for your project:

$ mkdir zephyrproject
$ cd zephyrproject

Now we must create a Workshop environment definition under .workshop/. You may do that manually by copying the following template:

$ mkdir .workshop
$ editor .workshop/zephyr-26-04.yaml

Add the sample environment definition to the file:

.workshop/zephyr-26-04.yaml¶

name: zephyr-26-04
base: ubuntu@26.04
sdks:
  - name: uv
    channel: latest/stable
  - name: zephyr
    channel: 26.04/stable
  - name: zephyr-sdk-ng
    channel: 26.04.0/stable
  - name: zephyr-amd64
    channel: 26.04.0/stable
connections:
  - plug: zephyr:venv
    slot: uv:venv
  - plug: zephyr:sdk-ng
    slot: zephyr-sdk-ng:sdk-ng
  - plug: zephyr-sdk-ng:amd64
    slot: zephyr-amd64:toolchain
actions:
  sync: |
    west update "$@"
  build: |
    source /var/lib/workshop/sdk/zephyr/venv/bin/activate
    cd /project/zephyr
    west build "$@"
  flash: |
    source /var/lib/workshop/sdk/zephyr/venv/bin/activate
    cd /project/zephyr
    west flash "$@"

Or you may have Workshop initialize the Zephyr 26.04 LTS template for you on the command line:

$ workshop init zephyr-26.04 --sdks uv/latest/stable,zephyr/26.04/stable,zephyr-sdk-ng/26.04.0/stable,zephyr-amd64/26.04.0/stable --base ubuntu@26.04

But be sure to add the sdks, connections and actions from the aforementioned zephyr-26-04 yaml file.

This YAML file declares the base system, Zephyr SDKs, toolchains, and project actions:

name an identifier for the Workshop environment.
base an Ubuntu base image used to create the environment.
sdks a list of the SDKs that Workshop installs. name selects an SDK and its channel selects the version channel to use.
connections link the SDK components so that one component can use another. A plug requests an interface, and a slot provides it, for example, plug: zephyr:venv connects to slot: uv:venv so the Zephyr environment can use the Python environment provided by uv.
actions defines commands that Workshop can run from the host

To see the other versions and channels an SDK publishes, follow How to find other SDK versions.

Launch the development environment:

$ workshop launch zephyr-26-04

Workshop will read the definition, create the environment via LXD, and download the Ubuntu base image and SDKs. The first launch may take several minutes.

Initialize and download the Zephyr source¶

Once the development environment is launched, start a Workshop shell:

$ workshop shell zephyr-26-04

Create a west workspace using Canonical’s Zephyr manifest repository and select the 26.04.0 source tag.

workshop@zephyr-26-04:/project$ west init \
-m https://git.launchpad.net/~arctic-tern/zephyr-rtos/+git/zephyr-manifest \
--mr 26.04.0 .

The source tag identifies an immutable, tested Zephyr 26.04 LTS source set. Verify the selected tag:

workshop@zephyr-26-04:/project$ git -C zephyr-manifest \
describe --tags --exact-match

which should yield:

26.04.0

Download the repositories from the Zephyr 26.04 LTS manifest:

workshop@zephyr-26-04:/project$ west update --narrow -o=--depth=1

The manifest pins each repository to a tested revision. It also directs west to the Zephyr RTOS Launchpad project.

Export the Zephyr CMake package:

workshop@zephyr-26-04:/project$ west zephyr-export

west zephyr-export exports the Zephyr package and registers Zephyr with CMake, so plain CMake projects can locate the Zephyr build system without relying on West to set ZEPHYR_BASE.

Build and run Hello World¶

Change to the Zephyr repository:

workshop@zephyr-26-04:/project$ cd zephyr

Build Hello World for the qemu_x86 board:

workshop@zephyr-26-04:/project/zephyr$ west build -p always -b qemu_x86 samples/hello_world

Run the built application:

workshop@zephyr-26-04:/project/zephyr$ west build -t run

The console should show output similar to:

*** Booting Zephyr OS LTS build 2e4ba3e7c182 ***
Hello World! qemu_x86/atom

Press Ctrl+A, then press X to stop QEMU.

Exit the Workshop shell:

exit

You will return to the host’s terminal.

Run Workshop actions from the host¶

You do not have to enter the Workshop shell manually for every task. The actions mapping in the workshop definition file defines commands that Workshop can run from the host.

For example, the workshop definition file in this tutorial defines sync, build, and flash actions:

.workshop/zephyr-26-04.yaml¶

actions:
  sync: |
    west update "$@"
  build: |
    source /var/lib/workshop/sdk/zephyr/venv/bin/activate
    cd /project/zephyr
    west build "$@"
  flash: |
    source /var/lib/workshop/sdk/zephyr/venv/bin/activate
    cd /project/zephyr
    west flash "$@"

To update all repositories defined in the West manifest, run the sync action:

$ workshop run zephyr-26-04 -- sync

Any arguments supplied after the action name are passed to the command defined for that action.

For example, the following command runs the build action and passes the build options to west build through "$@":

$ workshop run zephyr-26-04 -- build -p always \
-b qemu_x86 samples/synchronization

The build action then runs three commands:

source /var/lib/workshop/sdk/zephyr/venv/bin/activate
cd /project/zephyr
west build -p always -b qemu_x86 samples/synchronization

You can define additional actions in the workshop definition file to automate other tasks in a similar manner, see Customize Workshop actions.