Embedded Linux Build Environment

Docker-based build environment for embedded Linux projects. The workspace is organized around a reusable Ubuntu base image plus an embedded overlay for RTOS/SDK development (e.g., Zephyr, ESP-IDF).

Prerequisites

• Docker
• gum (for interactive menu)

Quick Start

./launch.sh

Select your Ubuntu version from the interactive menu. The container builds and launches automatically with your workspace mounted.

Usage

Interactive mode

./launch.sh

Non-interactive mode

./launch.sh 22.04
./launch.sh 18.04
./launch.sh 25.04
./launch.sh embedded 22.04
./launch.sh -w /opt -w /data 22.04

The old form ./launch.sh 22.04 still launches the generic base profile. Use ./launch.sh embedded 22.04 for the embedded overlay.

embedded requires Ubuntu 22.04 or newer. 18.04 remains available only for the generic base profile.

Extra mounts

In interactive mode you will be asked whether to mount extra host paths. In non-interactive mode use -w (repeatable):

./launch.sh -w /opt -w /data 22.04
./launch.sh -w /opt/homebrew embedded 22.04

Environment variables

Variable	Values	Default	Description
PROXY_MODE	auto, on, off	off	Proxy handling for build and run
BUILD_NETWORK	host, default	host	Docker network mode during build
WORKSPACE_DIR	host path	parent of this repo	Host directory mounted into /workspace
PROFILE	base, embedded	base	Default launch profile when not passed as an argument

PROXY_MODE=on ./launch.sh 22.04
WORKSPACE_DIR=$HOME/work/embedded ./launch.sh embedded 22.04
./launch.sh -w /opt -w /data 22.04

Supported Ubuntu versions

Version	Use case
18.04	Legacy projects requiring older toolchains
22.04	Recommended — best balance of stability and tool versions
25.04	Latest — newest compilers and libraries

Included tools

• Base profile: generic embedded Linux host tools for Buildroot, Yocto, OpenWrt, and related projects
• Embedded profile: base image plus RTOS/SDK host dependencies such as cmake, ninja, gperf, ccache, west, Python venv support, SDL2, and libmagic
• Networking: libnl, socat, iproute2

Embedded profile usage

Launch the embedded profile against an RTOS/SDK workspace:

WORKSPACE_DIR=$HOME/work/embedded ./launch.sh embedded 22.04

The embedded image includes common Linux host dependencies for Zephyr, ESP-IDF, and similar RTOS projects. After launching a container you can set up your SDK of choice:

Zephyr

python3 -m venv .venv
source .venv/bin/activate
west init zephyrproject
cd zephyrproject
west update
west zephyr-export
pip install -r zephyr/scripts/requirements.txt

For board builds, install the Zephyr SDK separately inside the container or mount an existing SDK and set ZEPHYR_SDK_INSTALL_DIR.

ESP-IDF

python3 -m venv .venv
source .venv/bin/activate
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32
. ./export.sh

If you already have an esp-idf checkout in your mounted workspace, run ./install.sh and . ./export.sh there instead.

Structure

.
├── launch.sh
├── docker/
│   ├── base/
│   │   ├── Dockerfile.ubuntu-18.04
│   │   ├── Dockerfile.ubuntu-22.04
│   │   └── Dockerfile.ubuntu-25.04
│   └── embedded/
│       ├── Dockerfile.ubuntu-22.04
│       └── Dockerfile.ubuntu-25.04

Inside the container

• Workspace mounted at /workspace
• Extra host paths mounted with -w <path> (same path inside container)
• Non-root user builder matching your host UID/GID