[yoe] next generation

Fast tooling and builds. No cross-compiling headaches. Easy to customize/upgrade/debug. One tool for both system engineers and application developers to ship products faster.

[yoe] next generation is a build system (focused on Embedded Linux for now) for teams shipping modern edge products. Components in Go, Rust, Zig, Python, JS/TS, and C/C++ are supported. [yoe] releases often and tracks upstream closely. The configuration language is easily processed by humans and AI. Build on your laptop, on native hardware, or in cloud CI — one integrated tool, same config, same results.

We took what we learned from many years of maintaining and building products with the Yoe Distribution, started over, and began building the tool we always wanted. [yoe] next generation is an experiment in progress — we’re sharing the work in the open as it takes shape.

Note: Not everything in the documentation has been implemented yet as this project is in the early stages.

🎯 Goals

Three north stars guide the experiment — everything else is in service of these:

1. Drastically improve developer productivity. Shrink the loop between an idea and a running image. Fewer rebuilds, fewer context switches, fewer tools to learn — so engineers spend their time on the product, not on the build.
2. Easily integrate complex workloads. Modern edge devices ship Go services, Rust agents, Python ML, container workloads, and kernel drivers side by side. Pulling these together should be straightforward, not a custom integration project each time.
3. Scale to build anything. From tiny Zephyr images to complex AI workloads. From one application to a complete distributed system. One tool, one mental model — the same workflow on a laptop, a build farm, or cloud CI, with caching that keeps up as projects grow.

Is [yoe] Right for You?

[yoe] build is not for everyone. If you are building a mission-critical system that requires bit-for-bit reproducible builds, long-term release freezes, or extensive compliance certification, use the current generation [Yoe Distribution](https://yoedistro.org/ based on Yocto - it is battle-tested for those requirements.

[yoe] build is designed for edge systems that behave more like cloud systems — AI workloads and modern-language applications — and for teams that track upstream closely and prioritize fast iteration over strict reproducibility. If your product ships frequent updates, runs containerized services, or depends heavily on Go/Rust/Python ecosystems, [yoe] may be a better fit.

More fundamentally, [yoe] assumes a small-team problem set, not a scaled-down enterprise one. A startup or ten-person product team doesn’t have smaller versions of an enterprise’s problems — it often has different problems entirely, and adopting tooling built for scale you don’t have imports its operational cost without the payoff (the You Are Not Google point. [yoe] is calibrated for the problems small teams and startups actually have.

🚀 Getting Started

Prerequisites: Linux or macOS with Git and Docker installed. Windows users: install WSL2 and use the Linux binary (Linux x86_64/Docker is the most tested configuration). Claude Code is highly recommended, but not required.

To run a built image you also need QEMU. On Debian/Ubuntu:

sudo apt-get install qemu-system-x86

For KVM acceleration, your user must be in the kvm group. If yoe run reports failed to initialize kvm: Permission denied, add yourself and pick up the new group membership:

sudo usermod -aG kvm $(whoami)
newgrp kvm   # or log out and back in

# Download the yoe binary (Linux x86_64)
curl -L https://github.com/yoebuild/yoe/releases/latest/download/yoe-Linux-x86_64 -o yoe
# For other platforms, download from https://github.com/yoebuild/yoe/releases/latest

chmod +x yoe
mkdir -p ~/bin
mv yoe ~/bin/
# Make sure ~/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed)
export PATH="$HOME/bin:$PATH"

# Create a new project
yoe init yoe-test
cd yoe-test

# Start the TUI (see screenshot below)
yoe

# Navigate to the base-image and press 'b' to build

# When build is complete, press 'r' to run (requires `qemu-system-x86_64` installed on your host)

# Log in a user: root, no password

# Power off when finished (inside running image)
poweroff

The TUI user interface:

dev-image is another included image with a few more things in it. Press the s key to navigate to the setup menu and select the image.

The / key modifies the unit query to change what units are displayed.

The tab key shifts between the unit, modules, and diagnostics pages.

For more information on the TUI, see the [yoe] tool documentation.

There are also CLI variants of the above commands (build, run, etc.).

What just happened:

1. yoe init created a project with a PROJECT.star config and a default x86_64 QEMU machine.
2. On first build, yoe automatically built a Docker container with the toolchain (gcc, make, etc.) and fetched the default unit modules from GitHub.
3. It built ~10 packages from source (busybox, linux kernel, openssl, etc.) inside the container, each isolated in its own bubblewrap sandbox.
4. It assembled a bootable disk image from those packages.
5. yoe run launched the image in QEMU with KVM acceleration.

Everything is in the project directory — no global state, no hidden caches outside the tree.

🔧 Why This Is Possible Now

A decade ago, this combination wasn’t realistic. Several things have changed:

1. ARM and RISC-V hardware is fast enough to build natively. Modern ARM boards and cloud instances (AWS Graviton, Hetzner CAX) build at full speed. For development, QEMU user-mode emulation runs ARM containers on x86 — no cross-toolchain needed.
2. Modern languages bring their own package managers. Go, Rust, Zig, and Python already handle dependency resolution, reproducible builds, and caching. [yoe] doesn’t reinvent any of that — application developers use the same Cargo, Go modules, or pip they already know.
3. AI can guide developers through the system. The hardest part of embedded Linux is knowing what to configure and why. [yoe]’s metadata is structured Starlark — queryable, not buried in shell scripts — so an AI assistant can create units, diagnose build failures, and audit security without the developer memorizing the build system’s quirks.

🧭 Values

1. The product developer experience is the top priority. Other solutions are often not optimized for developers building products. This includes application developers as well as system engineers. Clear and concise communication is essential when things go wrong. Unintelligible stacktraces are unacceptable.
2. Be Pragmatic. Leverage what already exists where it makes sense. We don’t have any religion that everything needs to be built from source, or that we all need to build our own toolchains.
3. Optimized for small teams. [yoe] is a tool for small teams to do big things. There are plenty of enterprise tools (Bazel, Buck2, Maven, etc.); we will use ideas from these tools, but [yoe] aims to be something different.
4. Scope is not limited to Embedded Linux. Although Embedded Linux is our current focus, a tool like [yoe] could be used for any problem where you pull a lot of pieces together. At its heart, [yoe] is a tool for building complex systems.
5. Track upstream closely. Modern edge systems are more like the cloud than traditional embedded systems — they are connected, updated regularly, and expected to receive security patches throughout their lifetime. [yoe] assumes you will track upstream releases closely rather than freezing on a version for years. Updating a package should be easy and routine, not a high-risk event that requires a dedicated engineering effort.
6. Vendor Neutral. [yoe] is a vendor neutral project and welcomes BSPs and other units from any vendor. The goal is to build an integrated ecosystem like Zephyr.

🤖 Why AI-Native

Embedded Linux is hard not because the concepts are complex, but because there are many concepts that interact in non-obvious ways: toolchain flags, dependency ordering, kernel configuration, package splitting, module composition, image assembly, device trees, bootloaders. Traditional build systems manage this complexity through complexity.

[yoe] takes a different approach: Simplify things as much as possible. Starlark units are readable by both humans and AI. The dependency graph is queryable. Build logs are structured. An AI assistant that understands all of this can:

• Create units from a URL or description — /new-unit https://github.com/example/myapp
• Diagnose build failures by reading logs and the dependency graph — /diagnose openssh
• Trace why a package is in your image — /why libssl
• Simulate changes before building — /what-if remove networkmanager
• Audit for CVEs and license compliance — /cve-check, /license-audit
• Generate machine definitions from board names — /new-machine "Raspberry Pi 5"

Add these skills to your project with yoe skills install (or as a Claude Code plugin via /plugin marketplace add yoebuild/yoe). See AI Skills for installation details and the full catalog of AI-driven workflows.

💡 Inspirations

[yoe] draws selectively from existing systems, taking the best ideas from each while avoiding their respective pain points:

• Yocto — machine abstraction, image composition, module architecture, OTA integration. Leave behind BitBake, sstate, cross-compilation complexity.
• Buildroot — the principle that simpler is better. Leave behind monolithic images and full-rebuild-on-config-change.
• Arch — rolling release, minimal base, PKGBUILD-style simplicity, documentation culture. Leave behind x86-centrism and manual administration.
• Alpine — apk package manager, busybox, minimal footprint, security defaults. Leave behind lack of BSP support.
• Nix — content-addressed caching, declarative configuration, hermetic builds, atomic rollback. Leave behind the Nix language and store-path complexity.
• Google GN — two-phase resolve-then-build model, config propagation through the dependency graph, build introspection commands, label-based target references for composability. Leave behind the C++-specific build model and Ninja generation.
• Bazel — Starlark as a build configuration language, hermetic sandboxed actions, content-addressed action caching, and remote build execution. Leave behind the monorepo bias, JVM runtime, and BUILD-file verbosity that make Bazel heavy for small teams.

See Comparisons for detailed analysis of how [yoe] relates to each of these (and other) systems, including when you should use them instead.

⚙️ Design

🏗️ A Single Tool

At its heart, [yoe] is a single tool — one Go binary that handles the entire build flow, from fetching sources to assembling bootable images. It exposes three interfaces: AI conversation, an interactive TUI, and a traditional CLI. All three do the same things; use whichever fits the moment.

The tool handles:

• TUI — run yoe with no arguments for an interactive unit list with inline build status, background builds, search, and quick actions (edit, diagnose, clean).
• Build orchestration — invoke language-native build tools in the right order, manage caching, assemble outputs. Multiple images and targets live in a single build tree (like Yocto). No global lock or global resource: concurrent yoe invocations run in parallel, which is essential for rapid AI-driven development.
• Machine/distro configuration — define target boards and distribution profiles in Starlark — Python-like, deterministic, sandboxed.

See The yoe Tool for the full CLI reference, Unit & Configuration Format for the unit and config spec, and Build Languages for the Starlark rationale.

Why Go: single static binary with no runtime dependencies, fast compilation, excellent cross-compilation support (useful for shipping the tool itself), and a strong standard library for file manipulation, process execution, and networking.

🖥️ Workstation-Centric Development

[yoe] is designed first for the developer’s workstation. While yoe runs equally well on an embedded dev kit, an ARM cloud instance, or a CI runner, the development loop is centered on the machine where developers already have their editor, shell, browser, debugger, and Git workflow set up. You should not need to SSH into a Raspberry Pi to get real work done.

That said, the option is there. The selfhost-image for the Raspberry Pi 5 bundles yoe, Go, Docker, git, and the dev-image tool set (helix, yazi, zellij) — flash, boot, and a freshly-imaged RPi5 is a complete native ARM64 build host. See Self-Host on RPi5.

When a build runs much faster on a different native architecture — for example, building ARM64 packages from an x86_64 workstation — those build steps can be dispatched to a native builder (a local ARM board on the network, an AWS Graviton instance, a Hetzner ARM box) without changing the developer’s workflow. This is similar to how CI systems dispatch jobs to remote runners: the developer’s workstation plays the role of the orchestrator, and remote machines act as architecture-specific runners. Orchestration, source edits, project state, the TUI, and the CLI stay on the workstation; only the per-unit build steps that benefit from native execution run elsewhere.

If a remote builder isn’t available — offline, on a plane, or the cloud runner is down — QEMU user-mode emulation is the fallback so builds can always continue locally. It’s slower, but the workflow doesn’t break.

The result: developers stay in the environment they already have tuned, and [yoe] puts the right machine behind each build step.

🚫 No Cross Compilation

Instead of maintaining cross-toolchains, [yoe] targets native builds:

• QEMU user-mode emulation — build ARM64 or RISC-V images on any x86_64 workstation. The build runs inside a genuine foreign-arch Docker container, transparently emulated via binfmt_misc. One command to set up (yoe container binfmt), then --machine qemu-arm64 just works. ~5-20x slower than native, but fine for iterating on a few packages.
• Native hardware — build on the target architecture directly (ARM64 dev boards, RISC-V boards).
• Cloud CI — use native architecture runners (e.g., ARM64 GitHub Actions runners, AWS Graviton, Hetzner ARM boxes) for full-speed CI builds.
• Per-unit build environment — each unit runs in its own Docker container with bubblewrap sandboxing. Architecture is determined per unit, not globally, and build dependencies don’t pollute the host or leak between units.

This eliminates an entire class of build issues (cross-sysroot management, host contamination, cross-pkg-config, etc.).

* Note, we are not opposed to cross compilation where it makes sense. Go applications cross-compile very easily. The Linux kernel is generally easy to cross-compile, so we may do that. But, cross-compilation of C/C++ components is not required.

📦 Native Language Package Managers

Each language ecosystem manages its own dependencies:

[yoe] plays nicely with existing language caching infrastructure so builds are fast and repeatable without re-downloading the internet.

🖥️ Kernel and System Image Tooling

While application builds use native language tooling, the system-level pieces still need orchestration:

• Kernel builds — configure, build, and package kernels for target boards.
• Root filesystem assembly — combine built artifacts into a bootable image (ext4, squashfs, etc.).
• Device tree / bootloader management — board-specific configuration.
• OTA / update support — image-based device management (full image updates, OSTree, BDiff) integrated with update frameworks (RAUC, SWUpdate, etc.). Container workloads on the target device are on the roadmap.

This is where [yoe] tooling (written in Go and Starlark) provides value — similar to what bitbake and wic do in Yocto, but simpler and more opinionated.

📋 Package Management: apk

[yoe] uses apk (Alpine Package Keeper) as its package manager. It is important to distinguish between units and packages — these are separate concepts:

• Units are build-time definitions (Starlark .star files in the project tree) that describe how to build software. See Unit & Configuration Format.
• Packages are installable artifacts (.apk files) that units produce. They are what gets installed into root filesystem images and onto devices.

This separation means units are a development/CI concern, while packages are a deployment/device concern. You can build packages once and install them on many devices without needing the unit tree. Rebuilding from source is first class but not required — every package is fully traceable to its unit, with no golden images.

Why apk over apt and dnf:

• Speed — apk operations are near-instantaneous. Install, remove, and upgrade are measured in milliseconds, not seconds.
• Simple format — an .apk package is a signed tar.gz with a .PKGINFO metadata file. No complex archive-in-archive wrapping.
• Small footprint — apk-tools is tiny, appropriate for embedded targets.
• Active development — apk 3.x adds content-addressed storage and atomic transactions, aligning with [yoe]’s Nix-inspired reproducibility goals.
• Works with glibc — apk is not tied to musl; it works with any libc. [yoe] runs its own package repositories, not Alpine’s.
• On-device package management — devices can pull updates from a [yoe] package repository, enabling incremental OTA updates (install only changed packages) alongside full image updates.

The [yoe] build tooling invokes units to produce packages — .apk on the default Alpine base, .deb on the experimental Debian/Ubuntu bases — which are published to a repository. Image assembly then installs those packages into a root filesystem with the base’s native tool (apk on Alpine, mmdebstrap/apt on Debian/Ubuntu).

🧱 Base System

The base userspace depends on the image’s distro. The default — and most mature — base is Alpine-derived: busybox on a musl C library, with busybox’s built-in init as PID 1. [yoe] also builds experimental Debian and Ubuntu bases, which are glibc worlds running systemd as PID 1 (see Yoe and distributions). The choice is per image:

• C library — musl on the Alpine base (inherited from Alpine’s toolchain); glibc on the Debian/Ubuntu bases, for maximum compatibility with pre-built binaries, vendor blobs, language runtimes (Go, Rust, Python, Node.js), and third-party libraries that assume glibc.
• busybox (Alpine base) — provides the core userspace utilities (sh, coreutils, etc.) and init in a single small binary, keeping the image minimal while still giving a functional shell environment for debugging and scripting. The Debian/Ubuntu bases ship the full GNU coreutils instead.
• Init — busybox’s built-in init handles PID 1 on the Alpine base; the Debian/Ubuntu bases run systemd, with its rich service management, integrated journal logging, network management, and device management (udev). The trade-off is size and complexity — which is why the lean busybox path stays the default.

This combination gives a small but fully functional base system that can run real-world services without surprises.

🔒 Reproducibility

[yoe] targets functional equivalence, not bit-for-bit reproducibility. Same inputs produce functionally identical outputs — same behavior, same files, same permissions — but the bytes may differ due to embedded timestamps, archive member ordering, or compiler non-determinism.

This is a deliberate trade-off:

• Bit-for-bit reproducibility (what Nix aspires to) requires patching upstream build systems to eliminate timestamps (__DATE__, .pyc mtime), enforce file ordering in archives, and strip or fix build IDs. This is enormous effort — Nix still hasn’t fully achieved it after 20 years — and the primary benefit (verifying a binary matches its source by rebuilding) is relevant mainly for high-assurance supply-chain contexts.
• Functional equivalence gets the practical benefits — reliable caching, hermetic builds, provenance tracking — without the patching burden. Bubblewrap isolation prevents host contamination. Content-addressed input hashing — combining hashes of the unit, its source, and its dependencies — ensures cache hits are reliable. Starlark evaluation is deterministic by design. The remaining non-determinism (timestamps, ordering within packages) doesn’t affect functionality or caching.

The caching model does not depend on output determinism. Cache keys are computed from inputs (unit content, source hash, dependency .apk hashes, build flags), not outputs. If inputs haven’t changed, the cached output is used regardless of whether a fresh build would produce identical bytes.

📚 Documentation

See the main documentation site for more information.

🤝 Contributing

Contributions are welcome — especially BSPs for new boards and units for new packages. AI-assisted contributions are fine; just make sure the result actually works, and keep PRs small and reviewable. Please discuss architectural or significant UI changes before implementing.

💚 Sponsors

[yoe] is supported by:

📄 License

[yoe] is licensed under the Apache License 2.0.

The [yoe] Tool

yoe is the single CLI tool that drives all [yoe] workflows — building packages and images from units, managing caches and source downloads, and flashing devices. It is a statically-linked Go binary with no runtime dependencies.

Installation

Prerequisites: Linux or macOS with Git and Docker installed. Windows users: install WSL2 and use the Linux binary (Linux x86_64/Docker is the most tested configuration). Claude Code is highly recommended, but not required.

# Download the yoe binary (Linux x86_64)
curl -L https://github.com/yoebuild/yoe/releases/latest/download/yoe-Linux-x86_64 -o yoe
# For other platforms, download from https://github.com/yoebuild/yoe/releases/latest

chmod +x yoe
mkdir -p ~/bin
mv yoe ~/bin/
# Make sure ~/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed)
export PATH="$HOME/bin:$PATH"

Since yoe is a Go binary, it cross-compiles trivially — build on your x86 workstation, run on an ARM build server.

Command Overview

yoe                 Launch the interactive TUI
yoe init            Create a new `[yoe]` project
yoe build           Build units (packages and images)
yoe shell           Open an interactive shell in a unit's build sandbox  [planned]
yoe dev             Manage source modifications (extract, diff, status)
yoe flash           Write an image to a device/SD card
yoe run             Run an image in QEMU
yoe serve           Serve the project's apk repo over HTTP+mDNS
yoe deploy          Build and install a unit on a running yoe device
yoe device          Manage repo configuration on a target device
yoe module          Manage external modules (fetch, sync, list)
yoe repo            Manage the local apk package repository
yoe cache           Manage the build cache (local and remote)  [planned]
yoe bundle          Export/import content-addressed bundles (air-gapped)  [planned]
yoe source          Download and manage source archives/repos
yoe config          View and edit project configuration
yoe desc            Describe a unit, package, or target
yoe refs            Show reverse dependencies
yoe graph           Visualize the dependency DAG
yoe log             Show build log (most recent or specific unit)
yoe diagnose        Launch Claude Code to diagnose a build failure
yoe skills          Install/update yoe's Claude Code skills in this project
yoe clean           Remove build artifacts
yoe container       Manage the build container (build, binfmt, status)

All commands except init, version, skills, and container run inside an Alpine build container automatically. The container is built on first use from containers/Dockerfile.build. See Build Environment for details.

Commands

yoe init

Scaffolds a new [yoe] project directory with the standard layout.

yoe init my-project

Creates:

my-project/
├── PROJECT.star
├── .gitignore          # ignores build/, cache/, repo/, local.star
├── .claude/skills/     # yoe's Claude Code skills (committed)
├── machines/
├── units/
├── classes/
└── overlays/

Optionally specify a machine to start with:

yoe init my-project --machine beaglebone-black

yoe init also installs [yoe]’s Claude Code skills into the new project’s .claude/skills directory (the same set yoe skills install provides), so Claude Code is ready to help the moment you open the project. See yoe skills.

yoe build

Builds one or more units. Package units (unit(), autotools(), etc.) produce .apk packages and publish them to the local repository. Image units (image()) assemble a root filesystem and produce a disk image. The class function used in the .star file determines the behavior — the command is the same for both.

# Build a single package unit
yoe build openssh

# Build multiple units
yoe build openssh zlib openssl

# Build an image unit (assembles rootfs, produces disk image)
yoe build base-image

# Build an image for a specific machine
yoe build base-image --machine raspberrypi4

# Build for ARM64 on an x86_64 host (uses QEMU user-mode emulation)
yoe build base-image --machine qemu-arm64

# Build all units (packages and images)
yoe build --all

# Build all image units for all machines (full matrix)
yoe build --all --class image             # planned: --class filter

# Build a unit and all its dependencies
yoe build --with-deps myapp               # planned: --with-deps flag

# Build up to 8 units in parallel (saved to local.star for next time)
yoe build -j 8 --all

# Rebuild even if the cache is fresh
yoe build --force openssh

# Skip remote cache — only check local cache
yoe build --no-remote-cache openssh       # planned: remote cache

# Skip all caches — force build from source
yoe build --no-cache openssh

# Dry run — show what would be built and why
yoe build --dry-run --all

# List available image/machine combinations
yoe build --list-targets                  # planned

What happens during a build:

Inspired by Google’s GN, yoe build uses a two-phase resolve-then-build model. The entire dependency graph is resolved and validated before any build work starts. This catches missing dependencies, cycles, and configuration errors up front rather than mid-build.

1. Sync modules — fetch or update external modules declared in PROJECT.star (skipped if already up to date). See yoe module sync.
2. Evaluate Starlark — load and evaluate all .star unit files (including those from modules) to produce the set of build targets. Each class function call (unit(), autotools(), image(), etc.) registers a target.
3. Resolve dependencies — topologically sort the build order from declared dependencies. Validate that all referenced units exist and the graph is acyclic. If any errors are found, stop here — no partial builds.
4. Check cache — compute a content hash of the unit + source + build dependencies. If a cached .apk with that hash exists (locally or in a remote cache), skip the build.
5. Fetch source — download the source archive or clone the git repo (see yoe source below). Sources are cached in $YOE_CACHE/sources/.
6. Prepare build environment — set up an isolated build root with only declared build dependencies installed via apk. This ensures hermetic builds.
7. Execute build steps — run the build commands defined by the class function in the build root. The environment provides:
   • $PREFIX — install prefix (typically /usr)
   • $DESTDIR — staging directory for installed files
   • $NPROC — number of available CPU cores
   • $ARCH — target architecture
8. Package — collect files from $DESTDIR, generate .PKGINFO from the unit metadata, and create the .apk archive.
9. Publish — add the .apk to the local repository and update the repo index.

For image units (image() class), steps 5-9 are replaced with image assembly:

1. Sync modules — same as above.
2. Evaluate Starlark — same as above.
3. Resolve dependencies — same as above.
4. Check cache — same as above.
5. Read machine definition — evaluate machines/<name>.star for architecture, kernel, bootloader, and partition layout.
6. Create empty rootfs — set up a temporary directory.
7. Install packages — run apk add --root <rootfs> with the [yoe] repository to install all declared packages. apk handles dependency resolution.
8. Apply configuration — set hostname, timezone, locale, and enable services per the image unit’s configuration (via the active init system — busybox init today, systemd a possible future option).
9. Apply overlays — copy files from overlays/ into the rootfs.
10. Install kernel + bootloader — build (or fetch from cache) the kernel and bootloader per the machine definition, install into the rootfs/boot partition.
11. Generate disk image — partition the output image per the partition layout and populate each partition.

Output format can be specified with --format:

yoe build base-image --format sdcard    # raw disk image with partitions
yoe build base-image --format rootfs    # tar.gz of the rootfs only
yoe build base-image --format squashfs  # squashfs for read-only roots

Parallel builds: yoe build walks the dependency DAG and builds units concurrently — as soon as a unit’s dependencies are all built (or cached), it can start, so independent branches of the graph build at the same time. The concurrency limit defaults to 5 units at once. Set it however suits your machine:

yoe build -j 12 --all                 # this run, and remembered afterward
yoe config set parallel-builds 12     # set it without starting a build

Either form writes parallel_builds to local.star, so the setting is per-developer and persists across builds (including builds started from the TUI). The TUI Setup page (s) also exposes it: select Parallel builds and press ←/→ (or h/l) to adjust the count, which writes the same local.star value. yoe config show prints the value currently in effect. -j 1 forces a fully sequential build, which is handy when reading interleaved verbose output. Precedence is -j flag → local.star → the built-in default of 5.

When a build fails: the failing unit’s build log is the record of what its build steps actually did. yoe prints the tail of that log inline at the point of failure, so the underlying error (a configure rejection, a compiler message, a missing header) is visible directly in the output — including when the build ran somewhere ephemeral like CI, where the log file does not survive the run. The full log path is printed alongside the tail; yoe log <unit> reprints it, and yoe log <unit> -e opens it in $EDITOR. In verbose mode (-v) the log is streamed to the terminal as the build runs, so only the path is noted on failure.

yoe flash

Writes a built image to a block device or SD card.

# Flash to SD card (auto-detects the most recent image build)
yoe flash /dev/sdX

# Flash a specific image unit's output
yoe flash base-image /dev/sdX

# Flash for a specific machine
yoe flash base-image --machine beaglebone-black /dev/sdX

# Dry run — show what would happen
yoe flash --dry-run /dev/sdX

Safety: yoe flash requires explicit confirmation before writing and refuses to write to mounted devices or devices that look like system disks.

yoe run

Launches a built image in QEMU for development and testing. When the host and target architecture match, QEMU uses KVM hardware virtualization for near-native speed. For cross-architecture images (e.g., ARM64 on x86_64), QEMU runs in software emulation mode automatically.

# Run the most recently built image (auto-detects machine/image)
yoe run

# Run a specific image unit
yoe run dev-image --machine qemu-x86_64

# Run an ARM64 image on an x86_64 host (software emulation)
yoe run base-image --machine qemu-arm64

# Forward an extra host port (default qemu machines already forward 2222→22,
# 8080→80, and 8118→8118 — `--port` adds to that list)
yoe run --port 9000:9000

# Allocate more memory — also saved to local.star and reused next time
yoe run --memory 8G

# Run with graphical output (default is serial console). Opens QEMU's
# native window with a virtio-vga adapter; serial stays multiplexed onto
# this terminal via `-serial mon:stdio`, so kernel logs are still
# visible alongside the framebuffer.
yoe run qt-image --display

# Run headless in the background
yoe run --daemon

# Run the Debian build of an image that exists in several distros
yoe run dev-image --distro debian

# Boot smoke test: boot headless, wait for the login prompt, SSH in and run
# a health check, then power off — exits non-zero on any failure
yoe run --boot-test dev-image
yoe run --boot-test --timeout 90s --machine qemu-arm64 dev-image

When an image name exists in more than one distro (e.g. dev-image ships in both the Alpine and Debian modules), --distro selects which built image to run, mirroring yoe build --distro. Without it the project’s effective distro (the local.star override, then defaults.distro) decides.

What happens:

1. Detect architecture — read the machine definition to determine the target architecture (x86_64, aarch64, riscv64).
2. Select QEMU binary — map to the correct qemu-system-* binary.
3. Configure machine — for x86_64, use the q35 machine type with UEFI firmware (OVMF). For aarch64, use virt with UEFI (AAVMF). For riscv64, use virt with OpenSBI.
4. Enable KVM — hardware virtualization is always used since host and guest architectures match.
5. Attach image — use the built disk image as a virtio block device.
6. Route console — by default, connect the serial console to the terminal (-nographic). The guest kernel must have console=ttyS0 (x86) or console=ttyAMA0 (aarch64) in its command line.
7. Set up networking — use QEMU user-mode networking with port forwarding. The qemu-x86_64 and qemu-arm64 machines forward 2222:22 (SSH), 8080:80, and 8118:8118 by default, so SSH to the guest works without any extra flags. --port adds to that list.

QEMU machine definitions:

Projects can define QEMU-specific machines alongside hardware ones:

# machines/qemu-x86_64.star
machine(
    name = "qemu-x86_64",
    arch = "x86_64",
    kernel = kernel(
        unit = "linux-qemu",
        cmdline = "console=ttyS0 root=/dev/vda2 rw",
    ),
    qemu = qemu_config(
        machine = "q35",
        cpu = "host",
        memory = "4G",
        firmware = "ovmf",
        display = "none",
    ),
)

When yoe run is given a machine with a qemu configuration, it uses those settings directly. When given a hardware machine without qemu configuration, it falls back to a reasonable default QEMU configuration for the machine’s architecture.

Guest memory follows this precedence: the --memory flag, then qemu_memory in local.star, then the machine’s own qemu memory. Passing --memory also writes the value to local.star, so later runs (and the TUI) reuse it without re-passing the flag — the same persistence -j uses for parallel-builds. Set it without a run via yoe config set qemu-memory 8G, or clear it with yoe config set qemu-memory "" to fall back to the machine default. The TUI Setup page (s) exposes it under QEMU settings (see below).

Graphical display follows the precedence: the --display flag, then qemu_display in local.star ("on" / "off"), then off. The TUI sub-screen is the editor for the persisted value.

Port forwards layer over the machine’s declared qemu.ports like this: local-overrides (qemu_ports in local.star) come first, then --port flags on the command line. In both lists, an entry whose guest port matches one in the machine’s defaults replaces that default instead of adding a duplicate — the same rule --port already follows for qemu-in-qemu.

Boot smoke test (--boot-test). This turns yoe run into a non-interactive pass/fail check, for CI or a quick local sanity test. yoe boots the image headless, watches the serial console until it reaches the login prompt, then SSHes into the guest over the 2222→22 forward (as root, which dev images leave passwordless), runs a health command, and powers the guest off. It exits 0 only if every stage succeeds; a boot that never reaches the prompt, a guest that exits early, or an unreachable SSH all fail the run. --timeout bounds the whole sequence (default 5 minutes — generous so an unaccelerated TCG boot still finishes); the boot uses KVM when /dev/kvm is available and falls back to TCG otherwise. The test requires qemu-system-* on the host PATH: it runs QEMU on the host so the guest’s SSH forward lands on the host loopback where the probe can reach it, rather than inside the build container.

QEMU settings sub-screen. Open Setup with s, move to QEMU settings, press Enter. The sub-screen lays out three sections:

• Memory — ←/→ steps a preset ladder (machine default, then 128M doubling up to 16G).
• Display — ←/→ cycles default (off) / off / on.
• Ports — read-only rows show the machine’s declared forwards; below them, each row is a local override. Press Enter (or a / +) on the trailing [+] add port row to type a new host:guest mapping; press d (or -) on a local row to remove it. Every change writes through to local.star.

yoe serve

Runs an HTTP server rooted at the project’s repo/ tree and advertises it on mDNS as _yoe-feed._tcp.local. so devices and yoe deploy discover it automatically.

# Serve at the default port (8765) with mDNS advertisement
yoe serve

# Bind to a specific interface or change the port
yoe serve --bind 192.168.1.10 --port 9000

# Skip mDNS (e.g., inside a container without host networking)
yoe serve --no-mdns

The default port is pinned (8765) so the URL written by yoe device repo add on a target survives yoe serve restarts. apks and APKINDEX.tar.gz are already signed by the project key, so plain HTTP transport is fine for development. See feed-server.md for the full dev-loop guide.

yoe deploy

Builds a unit, exposes the project’s repo as a feed (reusing a running yoe serve if one is up, otherwise spinning up an ephemeral feed on the same pinned port), then ssh’s to the device and runs apk add --upgrade <unit>. Transitive dependencies resolve on the device against the same APKINDEX.tar.gz production OTA uses.

# Build myapp and install it on dev-pi over the LAN
yoe deploy myapp dev-pi.local

# Deploy to a QEMU vm started with `yoe run` (default 2222→22 forward)
yoe deploy myapp localhost:2222

# Non-root ssh user
yoe deploy myapp pi@dev-pi.local

# Cross-subnet or mDNS-hostile network — advertise an explicit IP
yoe deploy myapp 10.0.5.42 --host-ip 10.0.5.1

The repo file /etc/apk/repositories.d/yoe-dev.list is left in place after deploy, so the device stays configured to pull from the dev host on any future apk add from the device. Use yoe device repo remove <host> to tear it down. Image targets error with a pointer to yoe flash.

yoe device

Configures /etc/apk/repositories.d/ on a target device so apk add from the device pulls from your dev feed. Useful standalone (without an immediate yoe deploy) to set up a fresh device, configure several devices for a multi-device QA bench, or inspect what’s currently configured.

# Auto-discover the running yoe serve on the LAN, configure dev-pi
yoe device repo add dev-pi.local

# Same, plus push the project signing pubkey to /etc/apk/keys/ on the
# target — needed if the device was flashed before the project key existed
yoe device repo add dev-pi.local --push-key

# Configure a QEMU vm started with `yoe run` (default 2222→22 forward)
yoe device repo add localhost:2222

# Explicit feed URL (colleague's serve, or non-mDNS network)
yoe device repo add 192.168.4.30 --feed http://laptop.local:8765/myproj

# Tear down
yoe device repo remove dev-pi.local

# Inspect /etc/apk/repositories and /etc/apk/repositories.d/*.list
yoe device repo list dev-pi.local

After yoe device repo add, run apk update && apk add htop (or any unit your project builds) directly on the device. yoe deploy writes the same file by default (yoe-dev.list), so the first deploy doubles as the persistent feed config.

yoe module

Manages external modules — the Git repositories declared in PROJECT.star that provide units, classes, and machine definitions.

Status: yoe module sync and yoe module list are implemented. yoe module info, yoe module check-updates, and yoe module list --tree (transitive tree output) are planned — the CLI dispatches them today with a “not yet implemented” stub message.

# Fetch/update all modules to the refs declared in PROJECT.star
yoe module sync

# List all modules with status (fetched, local override, version)
yoe module list

# Show the full resolved module tree (including transitive deps from MODULE.star)
yoe module list --tree        # planned

# Show details for a specific module
yoe module info @vendor-bsp   # planned

# Check for updates — show if upstream has newer tags
yoe module check-updates      # planned

What happens during yoe module sync:

1. Read PROJECT.star — parse the modules list.
2. Read MODULE.star from each module — discover transitive dependencies.
3. Resolve versions — PROJECT.star versions override transitive deps. If a required transitive dep is missing, error with an actionable message.
4. Fetch/update — clone or update each module’s Git repo into $YOE_CACHE/modules/. Checkout the declared ref.
5. Verify — confirm that each module’s MODULE.star (if present) is valid Starlark.

Module caching: Modules are cached in $YOE_CACHE/modules/ as bare Git repositories with worktree checkouts at the pinned ref. yoe module sync performs incremental fetches — only downloading new objects.

Automatic sync: yoe build automatically runs module sync if any module is missing or if PROJECT.star has changed since the last sync. You rarely need to run yoe module sync manually.

Local overrides: Modules with local = "..." in PROJECT.star skip fetching entirely and use the local directory. yoe module list shows these as (local: ../path).

Example output of yoe module list:

Module                             Ref        Status
@module-core                      v1.0.0     up to date
@vendor-bsp-imx8                   v2.1.0     up to date
  └─ @hal-common                   v1.3.0     up to date (transitive)
  └─ @firmware-imx                 v5.4       up to date (transitive)
@my-local-module                   main       (local: ../my-module)

yoe repo

Manages the local apk package repository.

Status: yoe repo list, yoe repo info, and yoe repo remove are implemented. yoe repo push and yoe repo pull (S3-compatible remote repository sync) are planned — there is no S3 backend yet.

# List all packages in the repository
yoe repo list

# Show details of a specific package
yoe repo info openssh

# Remove a package from the repository
yoe repo remove openssh-9.5p1-r0

# Push local repository to a remote (S3-compatible)
yoe repo push                 # planned

# Pull packages from a remote repository
yoe repo pull                 # planned

The local repository lives at repo/<project-name>/ within the project directory. It’s a standard apk-compatible repository — you can point apk on a running device at it directly.

yoe cache (planned)

Status: Not implemented. cmd/yoe/main.go has no cache case in its command switch — invoking yoe cache prints “Unknown command”. Content addressing and a local build cache exist inside the build executor, but there is no user-facing cache subcommand, no remote/S3 cache, no signing, and no yoe cache stats / gc / push / pull. The surface below describes the planned design.

Manages the local and remote build caches.

# Show cache status — local size, remote config, hit rate
yoe cache status

# List cached packages (local)
yoe cache list

# Show what's cached for a specific unit
yoe cache list openssh

# Push locally-built packages to the remote cache
yoe cache push

# Push specific packages
yoe cache push openssh zlib

# Pull packages from the remote cache into local
yoe cache pull

# Remove local cache entries older than retention period
yoe cache gc

# Remove all local cache entries
yoe cache gc --all

# Verify integrity of cached packages (check hashes and signatures)
yoe cache verify

# Show cache hit/miss statistics for the last build
yoe cache stats

Cache push/pull vs. repo push/pull: yoe repo manages the apk package repository (the repo index that apk consumes during image assembly). yoe cache manages the build cache (content-addressed build outputs keyed by input hash). In practice, both store .apk files, but the cache is keyed by build inputs while the repo is indexed by package name/version. Pushing to the cache shares build avoidance with CI/team. Pushing to the repo shares installable packages with devices.

yoe source

Manages source downloads. Sources are cached locally to avoid repeated downloads.

# Download sources for a unit
yoe source fetch openssh

# Download sources for all units
yoe source fetch --all

# List cached sources
yoe source list

# Verify source integrity (check sha256)
yoe source verify

# Clean stale sources
yoe source clean

Sources are stored in $YOE_CACHE/sources/ with content-addressed naming. For git sources, bare clones are cached and updated incrementally.

yoe config

View project configuration and set the per-developer settings stored in local.star.

# Show current configuration (includes parallel-builds and qemu-memory)
yoe config show

# Set how many units build in parallel (written to local.star)
yoe config set parallel-builds 12

# Set the RAM `yoe run` gives the QEMU guest (written to local.star)
yoe config set qemu-memory 8G

# Clear it so the machine's own qemu memory applies again
yoe config set qemu-memory ""

yoe config show reads PROJECT.star and reports the project name, default machine and image, cache path, the parallel-build concurrency in effect, and the QEMU guest memory in effect (each annotated default, machine default, or local.star).

yoe config set only writes settings that live in the yoe-generated local.star: parallel-builds and qemu-memory. Project configuration (defaults.machine, defaults.image, etc.) lives in hand-authored PROJECT.star and is edited there directly — config set does not patch Starlark.

yoe config set defaults.* / yoe config resolve (planned)

Status: Not implemented. yoe config set currently accepts only parallel-builds <n>; defaults.machine / defaults.image are edited in PROJECT.star by hand, and yoe config resolve does not exist yet. Use yoe desc <unit> --config to inspect resolved configuration in the meantime.

yoe config set defaults.machine raspberrypi4              # planned
yoe config set defaults.image dev                         # planned
yoe config resolve --machine beaglebone-black --image base # planned

yoe desc

Describes a unit, showing its resolved configuration, dependencies, build inputs hash, and package output. Inspired by GN’s gn desc.

# Show full details of a unit
yoe desc openssh

# Example output:
#   Unit:       openssh
#   Version:      9.6p1
#   Source:       https://cdn.openbsd.org/.../openssh-9.6p1.tar.gz
#   Build deps:   zlib, openssl
#   Runtime deps: zlib, openssl
#   Input hash:   a3f8c2...
#   Cached .apk:  yes (openssh-9.6p1-r0.apk)
#   Config:       CFLAGS=-O2 -march=armv8-a (propagated from machine)

# Show only the resolved config for a unit
yoe desc openssh --config

# Show the build inputs that contribute to the hash
yoe desc openssh --inputs

yoe refs

Shows reverse dependencies — what units or images depend on a given unit. Inspired by GN’s gn refs.

# What depends on openssl?
yoe refs openssl

# Example output:
#   Build deps:
#     openssh (build + runtime)
#     curl (build + runtime)
#     python (build)
#   Images:
#     base (via openssh, curl)
#     dev (via openssh, curl, python)

# Show only direct dependents
yoe refs openssl --direct

# Show the full transitive tree
yoe refs openssl --tree

This is essential for answering “if I update openssl, what needs to rebuild?”

yoe graph

Visualizes the dependency DAG.

# Print the dependency graph as text
yoe graph

# Output DOT format for graphviz
yoe graph --format dot | dot -Tpng -o deps.png

# Show graph for a single unit and its deps
yoe graph openssh

# Show only units that need rebuilding
yoe graph --stale

yoe TUI (no args)

Running yoe with no arguments launches an interactive terminal UI showing all units with their build status. The home screen has three tabs (tab / shift+tab to cycle): Units, Modules, and Diagnostics.

  `[yoe]`  Machine: qemu-x86_64  Image: base-image

  Query: in:base-image                            Units: 9/142

  NAME           CLASS      MODULE     VERSION    SRC         SIZE  DEPS  STATUS
→ base-files     unit       core       1.0.0                12 KiB    0  ● cached
  busybox        unit       core       1.37.0    pin        1.2 MiB    2  ● cached
  linux          unit       core       6.6.87    dev       42.1 MiB    1  ▌building...
  musl           unit       core       1.2.5     dev-mod    650 KiB    0  ● waiting
  openssl        autotools  core       3.4.1     dev-dirty  5.4 MiB    2  ● cached
  zlib           autotools  core       1.3.1                120 KiB    0  ● cached

  b build  $ shell  e edit  l log  s setup  / search  \ home  S save  q quit

Status indicators

When you build a unit, its dependencies appear as “waiting” (yellow), then transition to “building” (flashing green) as the executor reaches them. Multiple deps can flash green simultaneously.

Source state (SRC column)

The SRC column on the units and modules tabs shows whether the on-disk source checkout is yoe-managed or under your control. The same vocabulary applies to both units (build/<unit>/src/) and modules (<cache>/modules/<name>/).

Toggle a unit’s source between pin and dev with u on its detail page (or on the cursor row in the modules tab). When a dev or dev-mod checkout is ready to ship, P rewrites the unit’s .star tag field — to HEAD’s tag name when one exists, otherwise to the 40-char SHA. P never writes the branch field; branch tracking is declared by the unit author. The SRC column flips back to dev the next time the row renders.

While a unit is in any dev* state, yoe build reuses your working tree without re-fetching, re-extracting, or re-applying patches. A warning is logged so you know .star source/tag/patches edits won’t apply until you toggle the unit back to pin.

Tracking an upstream branch in dev mode

Units can opt into automatic branch tracking by declaring a branch field alongside tag:

unit(
    name = "busybox",
    source = "https://git.busybox.net/busybox",
    tag = "1_36_1",      # the pin — what `pin` mode builds
    branch = "master",    # dev-mode tracking ref
)

tag and branch are orthogonal. Without branch, pin and dev build the same commit (today’s behavior). With branch set, toggling pin → dev fetches upstream and checks out origin/<branch> HEAD — the working tree advances to whatever branch HEAD has accumulated past the pinned tag. The detail-page SOURCE line shows tracking origin/<branch> (N commits past <tag>) so the move is visible. Press P to capture the new HEAD as the new pin.

Key bindings (unit list)

The cursor auto-follows whatever unit is actively building, but only when you’ve been idle for a couple of seconds — pressing j/k or typing into the query bar suppresses the follow so the cursor stays where you put it. Pressing b or B re-arms the follow so the build cascade is visible.

Detail view

Pressing Enter on a unit opens a detail view with two tabs (tab / shift+tab to cycle): Info and Files.

The Info tab shows the unit’s place in the project plus its build streams:

• USED BY (upstream) — which explicit picks in the default image pull this unit in, and the runtime-dep chain that bridges them
• PULLS IN (downstream) — what this unit pulls in transitively
• BUILD OUTPUT — executor progress: dependency resolution, cache hits, build status for each dep
• BUILD LOG — tail of the unit’s build.log, updated in real time during a build

The Files tab lists every file the unit installed into its destdir (what apk packages into the unit’s .apk) with its on-disk size. Sortable by path or size — handy for spotting the biggest payloads or confirming a binary actually landed where you expected. Symlinks are dimmed; directories are omitted. Empty until the unit has been built at least once.

For image units the tab walks destdir/rootfs/ rather than destdir/, so the listing reflects the same content that drives the units-page SIZE column (BuildMeta.InstalledBytes) and the on-target install footprint. The assembled <image>.img artifact is intentionally not shown — its apparent size is the machine’s partition size (e.g. 600 M of reserved free space for qemu-x86_64), so including it would dwarf every other row without describing anything the user installed.

Help overlay

Press ? on any page — the unit list, a detail tab, Setup, Flash, Deploy, the Modules and Diagnostics tabs, or a dev-mode prompt — to open a centered box listing every shortcut that page accepts, grouped by purpose (navigation, build, inspect, filter, …) with a plain-language description for each. The overlay is page-aware: it shows exactly the keys the current page handles. When the list is taller than the terminal it scrolls — ↑/↓ j/k, PgUp/PgDn Ctrl+B/Ctrl+F, and g/G for the ends — with the page title and footer pinned and a lines a–b of N position indicator. Any other key closes it. ? is suppressed only while you’re typing into the Deploy host field, where it would be a literal character.

Search

Press / to edit the active query. The query bar accepts plain substrings plus field filters: type:image, module:rpi, status:failed, and in:<unit> — the last expands to the runtime closure of that unit, so in:dev-image shows only what your image needs. When the active query is non-empty, / opens the bar with a trailing space so you can immediately type an additional term. Tab completes field names and values; when there are multiple equally-good matches the candidate list renders as a vertical column directly under the query bar so you can see the next character to type. Press Ctrl+U to clear the input back to a blank bar in one keystroke. Press Enter to accept, Esc to revert. The TUI starts filtered to your default image’s closure; press \ to snap back to the saved default and S to save the current query as the new default.

Builds call build.BuildUnits() directly (in-process, no subprocess). The executor sends events to the TUI as each unit starts and finishes building.

The TUI is built with Bubble Tea.

Restarting after edits

The TUI loads the project once at startup and holds the resolved unit catalog in memory for the lifetime of the process. There is no in-process reload — if you change something that affects what the catalog contains, exit (q) and re-launch.

Restart is fast. Module-cache clones, build outputs, source tarballs, and APKINDEX / Packages files all stay on disk between runs — only the in-memory structures rebuild. A typical project’s TUI launches in well under a second; a large multi-feed project might take a second or two on the first launch (cold OS file-cache), warming up to a fraction of a second afterward. The exit/relaunch loop is a routine workflow step, not something to dread.

The “no in-process reload” stance is deliberate: making the in-memory catalog authoritative for the process lifetime avoids races between “what the resolver thinks” and “what’s on disk.” If a long build were partway through a closure when the catalog mutated under it, names could resolve differently mid-walk than at the start — a class of bug worth avoiding structurally rather than handling explicitly. For the architectural shape of what gets loaded and when, see Catalog and Materialization.

One-shot commands (yoe build, yoe deploy, yoe dry-run, …) sidestep this entirely: every invocation is a fresh process, so any edit to any .star or feed index is picked up on the next command automatically.

yoe log

Shows a build log. With no arguments, shows the most recently modified build log. Specify a unit name to view that unit’s log.

yoe log                  # show most recent build log
yoe log openssl          # show openssl build log
yoe log openssl -e       # open openssl build log in $EDITOR

The -e / --edit flag opens the log in your editor (defaults to vi).

The log is located under the project’s effective distro (the same cascade yoe build uses — an image’s own distro, then your local.star selection, then the project default), so it finds the right log in a multi-distro project. It also works for images and other machine-specific units, not just architecture- wide libraries and tools.

yoe diagnose

Launches Claude Code to diagnose a build failure. With no arguments, diagnoses the most recent build failure. Specify a unit name to diagnose that unit.

yoe diagnose             # diagnose most recent failure
yoe diagnose util-linux  # diagnose util-linux build failure

Requires claude to be in your PATH. Claude Code reads the build log and iteratively identifies root causes, applies fixes, and rebuilds until the unit succeeds.

yoe skills

Installs [yoe]’s Claude Code skills — the workflows behind /new-unit, /diagnose, /audit-unit, /update-unit, and /pull-alpine — into your project’s .claude/skills directory, where Claude Code discovers them.

The skills are baked into the yoe binary, so installing them needs no network access and the versions always match the tool you’re running.

# Copy the skills into ./.claude/skills (run from anywhere in the project)
yoe skills install

# List the skills embedded in this binary
yoe skills list

# Refresh the yoe-managed skills to this binary's versions after `yoe update`
yoe skills update

install is conservative: a skill whose directory already exists is left untouched so your local edits survive, and the command reports it as skipped. Pass --force to overwrite, or use update, which always refreshes the yoe-managed skills to the binary’s versions. Either way, only the skills [yoe] ships are touched — any skills you authored under .claude/skills are never read or modified.

The installed copies are plain Markdown files that belong to your project. Edit them to fit your workflow; the next yoe skills update will overwrite your changes to the yoe-managed skills, so keep heavily customized variants under a different name. When run inside a project (a directory with PROJECT.star, found by walking up from the current directory), the skills land at the project root; otherwise they land in the current directory.

Custom Commands

Projects can define custom commands in commands/*.star that become first-class yoe subcommands. This is similar to Zephyr’s west extensions but uses Starlark instead of Python classes.

# commands/deploy.star
command(
    name = "deploy",
    description = "Deploy image to target device via SSH",
    args = [
        arg("target", required=True, help="Target device hostname/IP"),
        arg("--image", default="base-image", help="Image to deploy"),
        arg("--reboot", type="bool", help="Reboot after install"),
    ],
)

def run(ctx):
    img = ctx.args.image
    target = ctx.args.target
    ctx.log("Deploying", img, "to", target)
    ctx.shell("scp", "build/output/" + img + ".img", "root@" + target + ":/tmp/update.img")
    ctx.shell("ssh", "root@" + target, "rauc", "install", "/tmp/update.img")
    if ctx.args.reboot == "true":
        ctx.shell("ssh", "root@" + target, "reboot")

Usage:

yoe deploy 192.168.1.100 --image production-image --reboot

Custom commands show up alongside built-in commands. If yoe doesn’t recognize a command, it checks commands/*.star before printing “unknown command”.

The context object provides:

Commands from modules:

Vendor BSP modules can ship custom commands (e.g., flash-emmc, enter-dfu) that become available when the module is added to the project.

Key difference from unit evaluation: Unit .star files are sandboxed — no I/O, deterministic. Command .star files have full I/O access via ctx.shell() because they are actions, not build definitions.

yoe dev

Work with unit source code directly. Every unit’s build directory is a git repo — upstream source is committed with an upstream tag, and existing patches are applied as commits on top. Local edits are just git commits.

There is no “dev mode” to enter or exit. If the build directory has commits beyond upstream, yoe build uses them directly instead of re-fetching source.

# After building, edit source in place
yoe build openssh
cd build/openssh/src
vim auth.c
git commit -am "fix auth timeout handling"

# Rebuild uses your local commits
yoe build openssh

# See what you've changed
yoe dev diff openssh

# Extract commits as patch files
yoe dev extract openssh
# Writes <unit-dir>/openssh/0001-fix-auth-timeout-handling.patch
# (alongside openssh.star, so the patches ship with the module that defines it)
# Prints updated patches list for your unit

# Check which units have local modifications
yoe dev status

Subcommands:

Rebasing on upstream updates:

# Update unit version
$EDITOR units/openssh.star   # bump version to 9.7p1

# Rebuild fetches new source, applies patches via rebase
yoe build openssh

# If patches conflict, resolve in the git repo
cd build/openssh/src
git rebase --continue
yoe dev extract openssh         # re-extract clean patches

Why this is simpler than Yocto’s devtool:

• No separate workspace — the build directory is the workspace
• No mode to enter/exit — local commits are automatically detected
• No state files — git is the only state
• Extracting patches is git format-patch — a command developers already know
• Each patch = one git commit, so the patch series is the git log

yoe shell (planned)

Status: Not implemented. The command below describes the intended interactive entry point into a unit’s build sandbox — the piece that makes the no-SDK model (see Development Environments) complete.

Opens an interactive shell inside the build sandbox for a unit. The shell attaches to the same container, environment variables, and mounted sysroot that yoe build uses — but with a TTY and no automatic build steps.

# Shell into the sandbox for a unit (uses the unit's container + default machine)
yoe shell myapp

# For a specific machine (cross-arch via QEMU)
yoe shell myapp --machine raspberrypi4

# Shell without targeting a unit — uses the machine's default toolchain container
yoe shell --machine beaglebone-black

Inside the shell, $SRCDIR, $DESTDIR, $PREFIX, $ARCH, and $NPROC are set exactly as yoe build would set them, and the unit’s resolved -dev dependencies are already installed into the sandbox via apk. Exiting the shell tears down the sandbox — it is not persistent, so probing with apk add <pkg> for exploration does not pollute subsequent builds.

This replaces the traditional SDK shell (Yocto’s environment-setup-*). See Development Environments for the full model.

yoe bundle (planned)

Status: Not implemented. The yoe bundle subcommand below is the air-gapped distribution story described in Development Environments. Today there is no export/import path, no bundle format, and no signing.

Exports and imports content-addressed bundles — the subset of the build cache, source cache, module checkouts, and container images needed to reproduce a set of targets without network access.

# Export a bundle for a specific image (includes all transitive deps)
yoe bundle export base-image --out bundle-base-v1.0.tar

# Export everything reachable from PROJECT.star
yoe bundle export --all --out bundle-full.tar

# Sign the bundle with the project's cache signing key
yoe bundle export base-image --sign keys/bundle.key --out bundle.tar

# Import on an air-gapped machine (verifies signatures if present)
yoe bundle import bundle-base-v1.0.tar --verify keys/bundle.pub

# Show the contents of a bundle without importing
yoe bundle inspect bundle.tar

A bundle contains built .apks, source archives, module checkouts, and toolchain container OCI archives — all keyed by content hash. After yoe bundle import, subsequent yoe build runs resolve everything from the local cache with no network access required.

yoe clean

Removes build artifacts.

# Remove build intermediates (keep cached packages)
yoe clean

# Remove everything (build dirs, packages, sources)
yoe clean --all

# Remove only packages for a specific unit
yoe clean openssh

Image rootfs builds deliberately leave per-file ownership (e.g. /var/lib/navidrome:navidrome:navidrome) on disk so that build/<image>.<arch>/destdir/rootfs/ inspects with the same uid/gid the booted system sees — see Security and Threat Model. A plain shell rm -rf build/ will fail with permission errors on those files. yoe clean handles the cleanup correctly: it tries a host-side rm first and, on EACCES, falls back to running the rm inside the build container where it has the privilege to remove root- and service-user-owned files. You don’t need sudo.

Environment Variables

Dependency Resolution

yoe resolves dependencies at two levels:

1. Build-time — unit deps entries form a DAG. yoe build --with-deps topologically sorts this graph and builds in order, parallelizing where the DAG allows.

2. Install-time — unit runtime_deps entries are written into the .apk’s .PKGINFO. When apk add runs during image assembly, it pulls in runtime dependencies automatically.

This means:

• Build dependencies are resolved by yoe (it knows the unit graph).
• Runtime dependencies are resolved by apk (it knows the package graph).
• The unit author declares both; the tools handle the rest.

Config Propagation (planned)

Status: Not implemented. There is no public_config field on units, no machine-to-unit CFLAGS/optimization propagation, and no resolved-config view in yoe desc. Units today receive architecture via the build environment and nothing else is automatically propagated through the DAG. The section below describes the planned GN-inspired design.

Inspired by GN’s public_configs, machine-level configuration automatically propagates through the dependency graph. When you build for a specific machine, settings like architecture flags, optimization level, and kernel headers path flow to every unit without each unit declaring them:

machine (beaglebone-black)
  → arch = "arm64"
  → CFLAGS = "-O2 -march=armv8-a"
  → KERNEL_HEADERS = "/usr/src/linux-6.6/include"
      ↓ propagates to
  unit (zlib)        → builds with arm64 flags
  unit (openssl)     → builds with arm64 flags
  unit (openssh)     → builds with arm64 flags + sees kernel headers

Units can also declare public_config settings that propagate to their dependents. For example, a zlib unit might export its include path so that openssh (which depends on zlib) automatically gets -I/usr/include without the unit author specifying it.

This is resolved during the graph resolution phase (phase 1) so the full resolved config for every unit is known before any build starts. Use yoe desc <unit> --config to inspect the resolved configuration.

Design note: unit-level, not task-level dependencies. Unlike BitBake, which models dependencies between individual tasks across units (e.g., B:do_configure depends on A:do_install), yoe treats each unit as an atomic unit — unit A depends on unit B means B must be fully built before A starts. This is a deliberate simplicity trade-off. BitBake’s task-level graph enables fine-grained parallelism (start fetching C while B is still compiling) and per-task caching (sstate), but it is also the primary source of Yocto’s debugging complexity. Unit-level dependencies are easier to reason about, and the parallelism loss is minor since independent units still build concurrently across the DAG. Per-unit caching via content-addressed .apk hashes provides sufficient granularity for fast incremental rebuilds.

Caching Strategy

Builds are cached at multiple levels:

1. Source cache — downloaded tarballs and git clones in $YOE_CACHE/sources/. Keyed by URL + hash.
2. Build cache — content-addressed by hashing the unit, source, and all build dependency .apk hashes. If the combined hash matches, the build is skipped and the cached .apk is used.
3. Package repository — built .apk files in the local repo. Once published, packages are available for image assembly and on-device updates.
4. Remote cache (planned — optional) — push/pull packages to an S3-compatible store so CI and team members share build results. Not yet implemented: there is no remote cache backend, no S3 integration, and no cache signing today. See the Caching Architecture section for the planned S3 configuration, cache signing, and the multi-level fallback chain.

Cache invalidation is hash-based, not timestamp-based. Changing a unit, updating a source, or rebuilding a dependency all produce a new hash and trigger a rebuild. Use yoe build --dry-run to see what would be rebuilt and why, or yoe cache stats to review hit/miss rates from the last build.

Example Workflow

# Start a new project
yoe init my-product --machine beaglebone-black

# Add a unit for your application
$EDITOR units/myapp.star

# Build everything (packages and images)
yoe build --all

# Flash to an SD card
yoe flash base-image /dev/sdX

# Later, update just your app and rebuild the image
$EDITOR units/myapp.star  # bump version
yoe build myapp
yoe build base-image         # only myapp's .apk changed, fast rebuild

# Or update the device directly
scp repo/myapp-1.3.0-r0.apk device:/tmp/
ssh device apk add /tmp/myapp-1.3.0-r0.apk

AI-First Tooling for [yoe]

[yoe] is designed as an AI-first build system. While every operation has a CLI equivalent, the primary interface for many workflows is a conversation with an AI assistant that understands the build system deeply. This document defines the skills (AI-driven workflows) that ship with [yoe].

Installing the skills

The skills ship two ways — pick whichever fits how you like to work.

Bundled with yoe (editable copies you own). The skills are baked into the yoe binary; install them into your project’s .claude/skills directory, where Claude Code discovers them:

yoe skills install   # copy the skills into ./.claude/skills
yoe skills list      # list the skills embedded in this binary
yoe skills update    # refresh them after upgrading yoe

yoe init does this automatically for new projects. The installed files are plain Markdown that belong to your project — yours to read, tweak, and commit. install won’t clobber a skill you’ve already edited (it skips and tells you); yoe skills update refreshes the yoe-managed skills to the running binary’s versions, so keep heavily customized variants under a different name.

As a Claude Code plugin (managed, auto-updating). If you’d rather let Claude Code manage updates, add the marketplace and install the plugin from inside Claude Code:

/plugin marketplace add yoebuild/yoe
/plugin install yoe@yoe

Both paths come from one source — .claude/skills in the yoebuild/yoe repository — so they deliver identical skills. Choose yoe skills install when you want to edit the skills, and the plugin when you want Claude Code to keep them updated for you. See yoe skills for the full command behavior.

Why AI-First

Embedded Linux development has a steep learning curve — not because the concepts are hard, but because there are many concepts and they interact in non-obvious ways. An AI assistant that understands units, dependencies, machine definitions, build isolation, and packaging can:

• Lower the barrier to entry. A developer can describe what they want in natural language and get working units, machine definitions, and image configurations.
• Reduce debugging time. Build failures in embedded systems often involve subtle interactions between toolchain flags, dependency ordering, and cross-module overrides. An AI that can read the full dependency graph and build logs can diagnose issues faster than manual investigation.
• Automate routine maintenance. Version bumps, security patches, license audits, and dependency updates are tedious but critical. AI skills can automate these with human review.
• Make the build system self-documenting. Instead of reading docs, ask the assistant “how does openssh get into my image?” and get a traced answer through the actual dependency graph.

Skill Categories

Unit Development

/new-unit

Create a new unit from a description or upstream URL. The AI determines the build system (autotools, cmake, meson, etc.), fetches the source to inspect it, identifies dependencies, and generates a complete .star file.

/new-unit https://github.com/example/myapp
/new-unit "I need an MQTT broker for IoT devices"
/new-unit "add libcurl with HTTP/2 support"

/update-unit <name>

Bump a unit to the latest upstream version. Checks for new releases, updates the version and sha256, runs a test build, and reports any patch conflicts or dependency changes.

/update-unit openssl
/update-unit --all --dry-run

/audit-unit <name>

Review a unit for common issues: missing runtime dependencies, incorrect license, unnecessary build dependencies, suboptimal configure flags, missing sub-package splits.

/audit-unit openssh

Image & Machine Configuration

/new-machine

Generate a machine definition from a board name or SoC. Looks up kernel defconfig, device trees, bootloader configuration, and QEMU settings (if applicable).

/new-machine beagleplay
/new-machine "Raspberry Pi 5"
/new-machine "custom board with i.MX8M Plus"

/new-image

Design an image unit interactively. Asks about the use case (gateway, HMI, headless sensor, development), suggests appropriate packages, configures services, and generates the .star file.

/new-image "industrial gateway with MQTT and OPC-UA"
/new-image "minimal headless sensor node"

/image-size

Analyze an image unit and estimate the installed size. Break down by package, identify the largest contributors, and suggest ways to reduce size (remove debug packages, switch to smaller alternatives, strip unnecessary features).

/image-size base-image
/image-size dev-image --compare base-image

Dependency Analysis

/why <package>

Trace why a package is included in an image. Shows the full dependency chain from image unit to the specific package, including which packages pull it in as a runtime dependency.

/why libssl
/why dbus --image dev-image

/what-if

Simulate the impact of a change without building. “What if I remove networkmanager from the image?” “What if I update glibc to 2.40?”

/what-if remove networkmanager from base-image
/what-if update glibc to 2.40
/what-if add python3 to dev-image

Build Debugging

/diagnose

Analyze a build failure. Reads the build log, identifies the root cause (missing dependency, configure flag issue, patch conflict, toolchain mismatch), and suggests a fix.

/diagnose openssh
/diagnose  # diagnose the most recent failure

/build-log <unit>

Summarize a build log — highlight warnings, errors, and anything unusual. Filter out noise (compiler progress, make output) and surface what matters.

/build-log linux
/build-log openssl --warnings-only

Security & Maintenance

/cve-check

Scan units against known CVEs. Reports which packages have outstanding vulnerabilities, their severity, and whether newer upstream versions fix them.

/cve-check
/cve-check openssl
/cve-check --image base-image

/license-audit

Audit all packages in an image for license compliance. Flag incompatible license combinations, missing license declarations, and packages that need special handling (GPL with linking exceptions, etc.).

/license-audit base-image
/license-audit --format spdx

/security-review

Review an image configuration for security issues: services running as root, unnecessary packages, missing hardening flags (ASLR, stack protector, fortify), world-readable sensitive files, default passwords.

/security-review base-image

Module Management

/new-module

Scaffold a new module with MODULE.star, directory structure, and example units.

/new-module vendor-bsp "BSP module for our custom board"
/new-module product "Product-specific units and images"

/module-diff

Compare two versions of a module. Show what units changed, what versions bumped, what new units were added, and what was removed.

/module-diff @module-core v1.0.0 v1.1.0

Development Environment

[yoe] does not ship a separate SDK — yoe itself is the dev environment. See Development Environments for the full model.

/dev-setup

Guide a developer through getting yoe + Docker installed and their editor configured for Starlark (syntax highlighting, language server, formatters). Verify the toolchain works by building a small unit end to end.

/dev-setup
/dev-setup --for rust  # also install Rust-native tooling on the workstation

/devshell <unit>

Wrapper over yoe shell — drops into the unit’s build sandbox with the same env vars, container, and mounted sysroot that yoe build uses. Useful for debugging configure issues, probing deps, or testing build commands manually.

/devshell openssh
/devshell linux --machine beaglebone-black

Documentation & Learning

/explain <concept>

Explain a [yoe] concept in context. Not just documentation — the AI reads the project’s actual configuration and explains how the concept applies to this specific project.

/explain "how does caching work for my project"
/explain "what happens when I run yoe build base-image"
/explain "how do modules compose in my project"

/diff-from-yocto

For developers coming from Yocto, explain how a Yocto concept maps to [yoe]. References the actual Yocto documentation and provides side-by-side comparisons.

/diff-from-yocto bbappend
/diff-from-yocto "MACHINE_FEATURES"
/diff-from-yocto sstate-cache

Implementation Notes

Each skill:

• Has access to the full project state via yoe desc, yoe refs, yoe graph, and direct Starlark file reading
• Can invoke yoe CLI commands to gather information (build logs, dependency graphs, cache status)
• Can create and modify .star files with the user’s approval
• Runs in the context of the current project directory

Skills that modify files (like /new-unit or /update-unit) always show the proposed changes and ask for confirmation before writing. Skills that only read and analyze (like /why or /diagnose) run without confirmation.

Go Workflows

This page covers Go-related workflows in [yoe]: building Go binaries as units, where the Go module/build cache lives, and how to recover from common pitfalls.

Building a Go binary as a unit

The go_binary class in module-core/classes/go.star wraps the standard build pattern: clone the source, run go build, install the resulting binary into $DESTDIR$PREFIX/bin. A minimal unit looks like:

load("//classes/go.star", "go_binary")

go_binary(
    name = "siot",
    version = "0.18.5",
    source = "https://github.com/simpleiot/simpleiot.git",
    tag = "v0.18.5",
    go_package = "./cmd/siot",   # optional, defaults to ./cmd/<name>
    binary = "siot",             # optional, defaults to <name>
    license = "Apache-2.0",
)

Cross-compilation is automatic: yoe sets GOARCH from the target machine’s arch (x86_64 → amd64, arm64 → arm64, riscv64 → riscv64) and forces CGO_ENABLED=0 GOOS=linux so the result is a statically-linked Linux binary.

The build runs inside the upstream golang:1.26 container by default. Override with container = "golang:1.23" (or any pullable Go image) when a unit needs a specific toolchain version.

Cache layout

Go-class units share a project-scoped cache mounted into the build container at /go/cache:

The cache survives across builds, so the second build of any Go unit is much faster than the first. It also survives across different Go units in the same project — simpleiot and a hypothetical second Go unit will share downloaded modules and built artifacts.

Cleaning the cache

go mod download writes module files with mode 0444 and their parent directories with mode 0555 — read-only by design, so you can’t accidentally edit a cached module. As a side effect, rm -rf against the cache fails with “Permission denied” even though every file is owned by your user: unlink needs the write bit on the parent directory, and Go has stripped it.

Recover with one of these:

# Option 1: chmod first, then rm — fastest
chmod -R u+w <project>/cache/go && rm -rf <project>/cache/go

# Option 2: let Go do it (this is what `go clean` is for)
GOMODCACHE=<project>/cache/go/mod go clean -modcache
GOCACHE=<project>/cache/go/build go clean -cache

Symptom you’d see if you skip the chmod:

rm: cannot remove 'yoe-test/cache/go/mod/go.bug.st/serial@v1.6.4/serial.go': Permission denied

This is a permission-bit issue, not an ownership issue. stat -c '%U:%G' on the file will show your username, not root.

Build sandbox notes

Go builds run inside the build container as --user $(id -u):$(id -g), so all cache writes land on the host as your user. The golang:1.26 upstream image has /go owned by root, but the bind mount overlays that with the project cache directory before any build step runs.

Cross-arch Go builds (e.g. building a riscv64 binary on x86_64) use QEMU user-mode emulation via binfmt_misc. Run yoe container binfmt once to register the QEMU handlers if you haven’t yet — the TUI surfaces a warning banner when this is missing.

Customising the build

Common knobs on go_binary:

For anything more involved than a go build — multi-binary repos, code generation, embedded assets — drop down to the plain unit() class and write the task("build", steps=[...]) directly. go_binary is just a thin wrapper around that pattern.

Python Workflows

This page covers how to ship Python apps with their pip dependencies on a yoe image. yoe doesn’t use pip as a package manager — pip-installed packages live in a per-app virtualenv baked into a regular apk, so the on-device package manager stays apk-only and rebuilding the image rebuilds the venv from a declared list of pins.

Packaging a Python app with pip dependencies

The python_venv class in module-core/classes/python.star creates a virtualenv under /usr/lib/python-venvs/<name> on the target and pip-installs the listed packages into it. The result is packaged as a regular .apk, gets the same caching and signing as any other unit, and brings in python3 automatically via runtime_deps.

A minimal app:

load("//classes/python.star", "python_venv")

python_venv(
    name = "python-hello",
    version = "1.0.0",
    description = "Greeter that renders ASCII art via pyfiglet",
    pip_packages = ["pyfiglet==1.0.2"],
    entry_points = {
        # /usr/bin/figlet runs `python -m pyfiglet "$@"` inside the venv
        "figlet": "pyfiglet",
    },
)

After yoe build python-hello, the resulting apk installs:

• /usr/lib/python-venvs/python-hello/ — the venv (pip, pyfiglet, etc.)
• /usr/bin/figlet — a one-line /bin/sh wrapper that execs the venv’s python -m pyfiglet

On the device, figlet "hi" works without the user knowing a venv is involved.

Bundling app code alongside the venv

python_venv only manages the venv itself. For apps that have their own source files, add an extra task that ships them via install_file() and points a wrapper at the bundled script:

load("//classes/python.star", "python_venv")

python_venv(
    name = "python-hello",
    version = "1.0.0",
    description = "Example Python app: ASCII-art greeting via pyfiglet",
    pip_packages = ["pyfiglet==1.0.2"],
    runtime_deps = ["busybox"],  # /bin/sh for the wrapper
    tasks = [
        task("install-app", steps = [
            "mkdir -p $DESTDIR/usr/lib/python-hello $DESTDIR/usr/bin",
            install_file("hello.py", "$DESTDIR/usr/lib/python-hello/hello.py",
                         mode = 0o644),
            "cat > $DESTDIR/usr/bin/python-hello <<'__WRAP__'\n" +
            "#!/bin/sh\n" +
            "exec /usr/lib/python-venvs/python-hello/bin/python " +
            "/usr/lib/python-hello/hello.py \"$@\"\n" +
            "__WRAP__",
            "chmod 0755 $DESTDIR/usr/bin/python-hello",
        ]),
    ],
)

install_file() resolves the source path relative to a sibling directory named after the .star file — units/python/python-hello.star looks for hello.py under units/python/python-hello/. See the python-hello example for the complete unit.

How the venv stays runnable on the target

python_venv builds the venv inside $DESTDIR during the unit build, which means every script the venv created has a build-time $DESTDIR-prefixed path baked into its shebang or config. Before packaging, the class:

1. Strips every __pycache__ so the apk doesn’t ship stale bytecode that pip will regenerate on first import anyway.
2. Runs grep -rIlF "$VENV_BUILD" | xargs sed -i to rewrite every reference from the build-time $DESTDIR/usr/lib/python-venvs/<name> prefix back to the on-target /usr/lib/python-venvs/<name> prefix.
3. Re-creates bin/python and bin/python3 as symlinks to /usr/bin/python3 so the venv works against whatever python3 is installed on the target.

The toolchain container (toolchain-musl) ships the same Alpine python3 the target rootfs gets via py3-pip’s runtime-dep chain. Because the python version (3.12.x) and its absolute path (/usr/bin/python3) match on both sides, the venv carries over cleanly.

Pure-Python wheels vs C extensions

Pure-Python wheels (pyfiglet, flask, click, requests and its dependencies, etc.) install out of the box. Wheels with C extensions — numpy, cryptography, pydantic-core, anything with cffi — need their build-time libraries and headers in the toolchain container. Add them as deps:

python_venv(
    name = "python-crypto-app",
    version = "1.0.0",
    pip_packages = ["cryptography==43.0.3"],
    deps = ["openssl", "libffi"],  # cryptography links these
)

If a wheel is published as musllinux_* (most popular packages now are), pip will install the prebuilt binary and you can skip the headers.

Customising the install path

By default the venv lives at /usr/lib/python-venvs/<name>. Override with install_path when an app needs a different location — for example, when an upstream config file points at a fixed path:

python_venv(
    name = "myapp",
    version = "1.0.0",
    pip_packages = ["myapp==1.0.0"],
    install_path = "/opt/myapp/venv",
)

The wrapper script(s) emitted by entry_points follow the install path automatically.

python-image

module-alpine/images/python-image.star boots into a userland with python3, pip, the dev-image diagnostic tools, and the python-hello demo pre-installed. Run yoe build python-image && yoe run python-image to get a QEMU VM where python-hello "..." renders an ASCII-art banner — useful as a smoke test that python_venv works end-to-end on your machine before you spend pip’s download budget on a real app.

Node.js Workflows

This page covers how to ship Node.js apps with their npm dependencies on a yoe image. yoe doesn’t use npm as a package manager — npm-installed packages live in a per-app node_modules tree baked into a regular apk, so the on-device package manager stays apk-only and rebuilding the image rebuilds node_modules from your package.json (and package-lock.json if present).

Packaging a Node.js app with npm dependencies

The nodejs_app class in module-core/classes/nodejs.star creates an app directory under /usr/lib/node-apps/<name> on the target, runs npm install against your package.json so the listed packages land in node_modules/ next to your code, and ships the whole tree as a regular .apk. It gets the same caching and signing as any other unit and brings in nodejs automatically via runtime_deps.

Each app lives in its own source directory next to the unit’s .star file and uses a normal Node.js project layout — package.json is the source of truth for deps, exactly like a developer would use locally.

A minimal app:

load("//classes/nodejs.star", "nodejs_app")

nodejs_app(
    name = "nodejs-hello",
    version = "1.0.0",
    description = "Greeter that renders ASCII art via figlet",
    runtime_deps = ["busybox"],  # /bin/sh for the wrapper
    tasks = [
        task("install-app", steps = [
            install_file("package.json",
                         "$DESTDIR/usr/lib/node-apps/nodejs-hello/package.json",
                         mode = 0o644),
            install_file("hello.js",
                         "$DESTDIR/usr/lib/node-apps/nodejs-hello/hello.js",
                         mode = 0o644),
            "cat > $DESTDIR/usr/bin/nodejs-hello <<'__WRAP__'\n" +
            "#!/bin/sh\n" +
            "exec node /usr/lib/node-apps/nodejs-hello/hello.js \"$@\"\n" +
            "__WRAP__",
            "chmod 0755 $DESTDIR/usr/bin/nodejs-hello",
        ]),
    ],
)

With a package.json like this next to the unit:

{
  "name": "nodejs-hello",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "figlet": "1.7.0"
  }
}

After yoe build nodejs-hello, the resulting apk installs:

• /usr/lib/node-apps/nodejs-hello/ — package.json, hello.js, and node_modules/ (figlet and its transitive deps)
• /usr/bin/nodejs-hello — a one-line /bin/sh wrapper that runs the app via node

On the device, nodejs-hello "hi" works without the user knowing node_modules is involved.

How the task order works

nodejs_app wraps the user-supplied tasks between two class-owned tasks:

1. nodejs-setup — creates $DESTDIR/<install_path> so install_file steps have a target directory.
2. (your tasks) — copy package.json (and optionally package-lock.json), then any JS/asset files, into $APP_BUILD using install_file(). Emit your /usr/bin wrapper here too.
3. nodejs-install — runs npm ci if a lockfile is present, otherwise npm install, against the staged package.json. Then rewrites any build-time path baked into node_modules back to the on-target absolute path and writes the entry_points wrappers.

If you ship a package-lock.json alongside package.json, npm ci makes the install fully reproducible — recommended for production units. Without a lockfile you get whatever satisfies the version ranges in dependencies{} at build time.

entry_points shortcut

For apps whose main entry point is just “run a binary from node_modules/.bin” or “run a script from a package,” skip the manual wrapper script and use entry_points:

nodejs_app(
    name = "myapp",
    version = "1.0.0",
    entry_points = {
        # /usr/bin/myapp runs `node_modules/.bin/myapp`
        "myapp": "myapp",
        # /usr/bin/lint runs `node node_modules/eslint/bin/eslint.js`
        "lint": "eslint:bin/eslint.js",
    },
    tasks = [
        task("install-app", steps = [
            install_file("package.json",
                         "$DESTDIR/usr/lib/node-apps/myapp/package.json"),
        ]),
    ],
)

"pkg" resolves to node_modules/.bin/pkg. "pkg:script" resolves to node node_modules/pkg/script.

Pure-JS packages vs native bindings

Pure-JavaScript packages (figlet, commander, chalk, express and its deps, etc.) install out of the box. Packages with native bindings (anything using node-gyp, prebuild, or a binding.gyp) need their build-time libraries and headers in the toolchain container. Add them as deps:

nodejs_app(
    name = "sqlite-app",
    version = "1.0.0",
    deps = ["sqlite"],  # better-sqlite3 links libsqlite
    tasks = [
        task("install-app", steps = [
            install_file("package.json",
                         "$DESTDIR/usr/lib/node-apps/sqlite-app/package.json"),
        ]),
    ],
)

When a package ships musl-compatible prebuilt binaries, npm will use those and you can skip the headers.

Customising the install path

By default the app lives at /usr/lib/node-apps/<name>. Override with install_path when an app needs a different location — for example, when an upstream config or service file points at a fixed path:

nodejs_app(
    name = "myapp",
    version = "1.0.0",
    install_path = "/opt/myapp",
    tasks = [
        task("install-app", steps = [
            install_file("package.json", "$DESTDIR/opt/myapp/package.json"),
        ]),
    ],
)

The wrapper script(s) emitted by entry_points follow the install path automatically.

nodejs-image

module-alpine/images/nodejs-image.star boots into a userland with node, npm, the dev-image diagnostic tools, and the nodejs-hello demo pre-installed. Run yoe build nodejs-image && yoe run nodejs-image to get a QEMU VM where nodejs-hello "..." renders an ASCII-art banner — useful as a smoke test that nodejs_app works end-to-end on your machine before you spend npm’s download budget on a real app.

Bun Workflows

This page covers how to ship Bun apps with their npm dependencies on a yoe image. yoe doesn’t use bun (or npm) as a system package manager — bun-installed packages live in a per-app node_modules tree baked into a regular apk, so the on-device package manager stays apk-only and rebuilding the image rebuilds node_modules from your package.json (and bun.lockb if present).

Bun is a single binary that bundles a JavaScript runtime, a package manager, and a bundler. It runs TypeScript directly with no separate compile step, so the entry point of a bun app can be a plain .ts file.

Packaging a Bun app with npm dependencies

The bun_app class in module-core/classes/bun.star creates an app directory under /usr/lib/bun-apps/<name> on the target, runs bun install --production against your package.json so the listed packages land in node_modules/ next to your code, and ships the whole tree as a regular .apk. It gets the same caching and signing as any other unit and brings in bun automatically via runtime_deps.

Each app lives in its own source directory next to the unit’s .star file and uses a normal Bun project layout — package.json is the source of truth for deps, exactly like a developer would use locally.

A minimal app:

load("//classes/bun.star", "bun_app")

bun_app(
    name = "bun-hello",
    version = "1.0.0",
    description = "Greeter that renders ASCII art via figlet",
    runtime_deps = ["busybox"],  # /bin/sh for the wrapper
    tasks = [
        task("install-app", steps = [
            install_file("package.json",
                         "$DESTDIR/usr/lib/bun-apps/bun-hello/package.json",
                         mode = 0o644),
            install_file("hello.ts",
                         "$DESTDIR/usr/lib/bun-apps/bun-hello/hello.ts",
                         mode = 0o644),
            "cat > $DESTDIR/usr/bin/bun-hello <<'__WRAP__'\n" +
            "#!/bin/sh\n" +
            "exec bun /usr/lib/bun-apps/bun-hello/hello.ts \"$@\"\n" +
            "__WRAP__",
            "chmod 0755 $DESTDIR/usr/bin/bun-hello",
        ]),
    ],
)

With a package.json like this next to the unit:

{
  "name": "bun-hello",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "figlet": "1.7.0"
  }
}

And hello.ts:

import figlet from "figlet";

const argv = process.argv.slice(2);
const text = argv.length > 0 ? argv.join(" ") : "Hello, yoe!";
console.log(figlet.textSync(text, { font: "Slant" }));
console.log(`(bun ${Bun.version})`);

After yoe build bun-hello, the resulting apk installs:

• /usr/lib/bun-apps/bun-hello/ — package.json, hello.ts, and node_modules/ (figlet and its transitive deps)
• /usr/bin/bun-hello — a one-line /bin/sh wrapper that runs the app via bun

On the device, bun-hello "hi" works without the user knowing node_modules is involved.

How the task order works

bun_app wraps the user-supplied tasks between two class-owned tasks:

1. bun-setup — creates $DESTDIR/<install_path> so install_file steps have a target directory.
2. (your tasks) — copy package.json (and optionally bun.lockb), then any JS/TS/asset files, into $APP_BUILD using install_file(). Emit your /usr/bin wrapper here too.
3. bun-install — runs bun install --production against the staged package.json, then rewrites any build-time path baked into node_modules back to the on-target absolute path and writes the entry_points wrappers.

If you ship a bun.lockb alongside package.json, bun resolves dependencies from the lockfile — recommended for production units. Without a lockfile you get whatever satisfies the version ranges in dependencies{} at build time.

entry_points shortcut

For apps whose main entry point is a single script or a binary from node_modules/.bin, skip the manual wrapper and use entry_points:

bun_app(
    name = "myapp",
    version = "1.0.0",
    entry_points = {
        # /usr/bin/myapp runs `bun /usr/lib/bun-apps/myapp/main.ts`
        "myapp": "main.ts",
        # /usr/bin/serve runs `node_modules/.bin/serve`
        "serve": "serve",
        # /usr/bin/lint runs `bun node_modules/eslint/bin/eslint.js`
        "lint": "eslint:bin/eslint.js",
    },
    tasks = [
        task("install-app", steps = [
            install_file("package.json",
                         "$DESTDIR/usr/lib/bun-apps/myapp/package.json"),
            install_file("main.ts",
                         "$DESTDIR/usr/lib/bun-apps/myapp/main.ts"),
        ]),
    ],
)

Entry forms:

• "file.ts" / "file.js" / "file.mjs" — exec bun <install_path>/<file>.
• "pkg" — exec node_modules/.bin/pkg directly.
• "pkg:script" — exec bun node_modules/pkg/script.

Why Bun is a useful default for new JS/TS apps

A few practical differences from Node:

• TypeScript runs as-is. No tsc, no ts-node, no separate build step. The entry point of a bun_app can be a .ts file and it works.
• bun install is fast. The install task in a typical app build is much shorter than the npm install equivalent.
• Single binary. The runtime, package manager, test runner, and bundler are all the same bun executable, so the toolchain footprint is one apk.

Node is still available via module-alpine’s nodejs unit if you have an existing Node app or a dep that depends on Node-specific behavior.

Customising the install path

By default the app lives at /usr/lib/bun-apps/<name>. Override with install_path when an app needs a different location:

bun_app(
    name = "myapp",
    version = "1.0.0",
    install_path = "/opt/myapp",
    tasks = [
        task("install-app", steps = [
            install_file("package.json", "$DESTDIR/opt/myapp/package.json"),
        ]),
    ],
)

The wrapper script(s) emitted by entry_points follow the install path automatically.

bun-image

module-alpine/images/bun-image.star boots into a userland with bun, bunx, the dev-image diagnostic tools, and the bun-hello demo pre-installed. Run yoe build bun-image && yoe run bun-image to get a QEMU VM where bun-hello "..." renders an ASCII-art banner — useful as a smoke test that bun_app works end-to-end on your machine before you spend bun’s download budget on a real app.

Feed server and yoe deploy

The dev loop for installing in-progress builds onto a running yoe device. Three commands, layered:

• yoe serve — long-lived HTTP feed for the project’s apk repo, advertised via mDNS so devices and yoe deploy find it without configuration.
• yoe device repo {add,remove,list} — configure /etc/apk/repositories on a target device so apk add from the device pulls from your dev feed.
• yoe deploy <unit> <host> — build, ship, and install a unit on a running device in one command. Pulls the unit and all its transitive deps via apk on the device side, so dependency resolution mirrors production OTA.

The model is pull, not push. Every install — image-time, on-device OTA, and the dev loop — uses the same apk repo, the same APKINDEX.tar.gz, and the same signing key. Adding a new runtime dep to a unit doesn’t require updating deploy machinery; apk on the device resolves it.

Trust

apks and APKINDEX are signed by the project key (docs/signing.md). Every yoe device has the matching public key in /etc/apk/keys/ via base-files. apk verifies signatures unconditionally, so the HTTP transport is plain — package integrity is enforced at the package layer, not the network layer.

For production OTA, layer HTTPS via reverse proxy (docs/on-device-apk.md).

Common workflows

One-time setup on a fresh device

A device that was just flashed with an image built by your project needs nothing — the public key is already in /etc/apk/keys/. Configure the repo:

# Dev host, in your project dir
yoe serve &

# In another terminal — autodiscovers the running serve via mDNS
yoe device repo add dev-pi.local

After this, on the device:

apk update
apk add htop strace gdb         # any unit your project builds is now installable

If the device was flashed from someone else’s image (no project key), pass --push-key:

yoe device repo add dev-pi.local --push-key

Iterating on a single unit

yoe deploy myapp dev-pi.local

Builds myapp, starts an ephemeral feed (or reuses your running yoe serve if it’s advertising the same project), ssh’s to the device, and runs apk add --upgrade myapp. Transitive deps are resolved on the device.

A # >>> yoe-dev … # <<< yoe-dev block in /etc/apk/repositories on the target is left in place after deploy — same block yoe device repo add would have written. So the first deploy to a fresh device doubles as the persistent feed config.

Multiple devices on a LAN

Run yoe serve once on the dev host. Each device runs yoe device repo add once. After that, apk update && apk upgrade on each device picks up new builds.

Tearing it down

yoe device repo remove dev-pi.local

Strips the # >>> yoe-dev block from /etc/apk/repositories. The device falls back to whatever else is configured (typically nothing, in dev).

Inspecting the device’s repo config

yoe device repo list dev-pi.local

Cats /etc/apk/repositories, prefixed with the source filename. (Also reads /etc/apk/repositories.d/*.list if present, though apk-tools 2.x does not read those itself — they’re informational only.)

Command reference

yoe serve

yoe serve [--port PORT] [--bind ADDR] [--no-mdns] [--service-name NAME]

• --port — TCP port. Default 8765. Pinned (not random) so the URL written by yoe device repo add stays valid across yoe serve restarts.
• --bind — listen address. Default 0.0.0.0 (LAN-visible).
• --no-mdns — skip the mDNS advertisement (multicast-hostile networks).
• --service-name — mDNS instance name. Default yoe-<project>.

yoe device repo add

yoe device repo add <[user@]host[:port]> [--feed URL] [--name NAME]
                                          [--push-key] [--user USER]

• <[user@]host[:port]> — ssh destination. Examples: dev-pi.local, pi@dev-pi.local, localhost:2222 (QEMU), pi@dev-pi.local:2200.
• --feed URL — explicit URL. If omitted, browses mDNS for _yoe-feed._tcp on the LAN; errors clearly on 0 or >1 matches.
• --name NAME — name suffix for the marker block written into /etc/apk/repositories (# >>> yoe-<name> … # <<< yoe-<name>). Default yoe-dev.
• --push-key — copy the project signing pubkey to /etc/apk/keys/ on the target before configuring.
• --user USER — default ssh user when the target spec has no user@ prefix. Default root. ssh shells out to the user’s ssh so ~/.ssh/config, ssh-agent, known_hosts, and jump hosts all work.

yoe device repo remove

yoe device repo remove <[user@]host[:port]> [--name NAME] [--user USER]

Idempotent — missing file is success.

yoe device repo list

yoe device repo list <[user@]host[:port]> [--user USER]

yoe deploy

yoe deploy <unit> <[user@]host[:port]> [--user U] [--port P]
                                        [--host-ip IP] [--machine M]

• <unit> — must resolve to a non-image unit. Image targets error with a pointer to yoe flash.
• <[user@]host[:port]> — ssh destination, same syntax as device repo add.
• --port — feed port (default 8765, same as yoe serve).
• --host-ip — advertise this IP to the device instead of <hostname>.local. Use when mDNS resolution fails on the device.
• --machine — target machine override.

Constraints

• mDNS doesn’t cross subnets. Cross-subnet deploys need --feed URL or --host-ip.
• A pinned port 8765 collides if something else on the dev host is using it — pass --port to yoe serve and yoe deploy to override.
• The dev host needs avahi / systemd-resolved running for <hostname>.local to resolve from the device. Most Linux distros ship this.
• Concurrent deploys against the same project: one runs the ephemeral feed (or reuses yoe serve), the other will see the same URL via mDNS reuse. Truly parallel ephemeral feeds for the same project on the same dev host collide on port 8765.

On-Device Package Management

apk-tools ships in dev-image and any other image that includes it, so booted yoe systems can install, upgrade, and inspect packages against the project’s signed repo using stock Alpine apk commands.

What’s already on the device

After a successful yoe build dev-image && yoe run dev-image:

• /sbin/apk — the apk-tools binary.
• /lib/apk/db/ — the installed-package database, populated at image assembly time via apk add.
• /etc/apk/keys/<keyname>.rsa.pub — the project’s signing public key, shipped by base-files. apk uses it to verify signatures on every add/upgrade/update without any flag-passing on your part.
• /etc/apk/repositories — a commented-out template. You override this with your project’s repo URL before doing anything live.

Pointing at a repository

Edit /etc/apk/repositories and add a single line — one repo per line. A few common shapes:

# Project repo served over HTTPS by an nginx behind your CA
https://repo.example.com/myproj

# Project repo served by a plain HTTP server on the LAN
http://10.0.0.1/repo/myproj

# Local filesystem path (e.g., bind-mounted USB stick or sshfs)
/var/cache/yoe/repo

Then update the index cache:

$ apk update

Yoe-built repos use Alpine’s standard <repo-root>/<arch>/APKINDEX.tar.gz layout, so apk picks the right arch automatically — point the repositories file at the root, not at the per-arch subdirectory.

Pointing at a yoe-served feed

For development, run yoe serve on your build host and configure the device with yoe device repo add <host>. See feed-server.md for the full dev-loop walkthrough.

Installing and upgrading

Once a repository is wired up:

$ apk add htop          # install one package
$ apk add --update vim  # refresh index, then install
$ apk upgrade           # upgrade everything to the latest available
$ apk del strace        # remove a package
$ apk info -vv | head   # list installed packages
$ apk verify            # re-verify every installed package's hashes

All of these run with signature verification on. If apk reports “BAD signature” or “untrusted”, the public key under /etc/apk/keys/ doesn’t match the key the repo’s apks were signed with. See docs/signing.md for the key-rotation flow.

OTA flow (rebuild → publish → upgrade)

The recommended OTA path for yoe-built devices:

1. Bump versions. Edit one or more units’ version = (or release = if just rebuilding the same source) on your dev host.
2. Build the new apks. yoe build <unit> produces the new .apk files in <projectDir>/repo/<project>/<arch>/ and refreshes APKINDEX.tar.gz. Both are signed with the project key.
3. Sync to your hosting. Copy the entire <projectDir>/repo/<project> subtree to wherever you serve it from — e.g., a static-site bucket, an nginx vhost, or a release server. The on-disk layout is already correct; no transformation needed.
4. On-device upgrade. apk update && apk upgrade.

Hosting the repo over HTTP/HTTPS

Any static file server works. nginx example:

server {
    listen 443 ssl;
    server_name repo.example.com;
    ssl_certificate     /etc/letsencrypt/live/repo.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/repo.example.com/privkey.pem;

    root /srv/yoe-repos;
    autoindex off;

    # Tighten cache headers — APKINDEX.tar.gz changes on every publish,
    # but individual .apk files are content-addressed by version+release
    # and never change once published.
    location ~ /APKINDEX\.tar\.gz$ {
        add_header Cache-Control "no-cache";
    }
    location ~ \.apk$ {
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
}

Drop your project’s repo subtree under /srv/yoe-repos/myproj/ and point /etc/apk/repositories at https://repo.example.com/myproj.

Constraints worth knowing

• Kernel upgrades need a reboot. apk doesn’t restart anything; a new linux-* apk replaces files in /boot and the running kernel keeps running until you reboot.
• No automatic rollback. If an upgrade leaves the system unbootable, there’s no built-in A/B rollback in this layer. For atomic-rootfs workflows (RAUC-style A/B partitioning, or btrfs-snapshot rollback), layer them above the apk repo — apk handles the package contents, the rootfs strategy handles atomicity.
• In-place upgrade is non-atomic. apk extracts each package’s files individually. A power loss during apk upgrade can leave the rootfs in a half-upgraded state. For deployments where that’s not OK, ship upgrades as full image artifacts via flash/A-B and use the apk repo for development iteration only.
• No remote network at install time during image build. Image assembly runs apk add --no-network against the local repo. This is intentional: build artifacts must be reproducible from the project tree alone.

QEMU Machines

yoe ships two QEMU machines that serve as the default development and CI targets: qemu-arm64 and qemu-x86_64. Neither corresponds to physical hardware — both target QEMU’s emulated virt/q35 machines and exist to let you iterate on userspace and the kernel without booting real silicon each time.

This page covers what each machine ships, how the boot path differs between them, and what yoe qemu actually does at run time.

Machine descriptors live at:

• modules/module-core/machines/qemu-arm64.star
• modules/module-core/machines/qemu-x86_64.star

Both lean entirely on module-core and module-alpine — no board-specific BSP units.

Comparison at a glance

Both default to 4 GB RAM and display = "none"; the -nographic flag sends serial to the controlling terminal. 4 GB is the floor for memory-heavy unit builds inside the guest — the kernel link step alone needs well over 1 GB, so a self-hosted yoe build of linux is OOM-killed on a smaller VM.

Pass --display to yoe run (e.g. yoe run qt-image --display) to drop -nographic and let QEMU open its native window for the guest framebuffer. The launcher attaches a virtio-vga adapter for the DRM virtio-gpu driver and keeps serial multiplexed onto host stdio so kernel logs still appear in the terminal that started the run. The kernel’s graphics.cfg fragment turns on the relevant FB/DRM bits (DRM_VIRTIO_GPU, DRM_BOCHS, FB_VESA, FB_EFI, DRM_FBDEV_EMULATION), so /dev/fb0 is present from the first boot — needed by linuxfb-backed UIs like the qt-image demo.

qemu-arm64

machine(
    name = "qemu-arm64",
    arch = "arm64",
    kernel = kernel(
        unit = "linux",
        defconfig = "defconfig",
        cmdline = "console=ttyAMA0 root=/dev/vda1 rw",
    ),
    partitions = [
        partition(label = "rootfs", type = "ext4", size = "512M", root = True),
    ],
    qemu = qemu_config(
        machine = "virt", cpu = "host", memory = "4G",
        display = "none",
        ports = ["2222:22", "8080:80", "8118:8118"],
    ),
)

There is no bootloader and no boot partition. yoe qemu invokes QEMU with -kernel <vmlinuz> taken from the built image’s own /boot, and passes the machine’s cmdline via -append. The kernel is whichever one the image ships: Alpine installs /boot/vmlinuz and mounts the rootfs directly, while Debian installs a versioned /boot/vmlinuz-<ver> alongside an initrd.img-<ver> that QEMU also receives via -initrd. QEMU loads these straight into emulated DRAM on the virt machine and starts the A53 cores at the kernel entry point.

This is the one place in yoe where direct-kernel boot is the correct path, not a shortcut. The virt machine has no analog in physical silicon — there is no ROM, no SPL, no need for U-Boot. (For physical aarch64 boards, see BeaglePlay for the full ROM → SPL → TF-A → U-Boot → kernel chain.)

EFI-only kernels boot through UEFI firmware. Direct -kernel boot only works for a bare arm64 Image (Alpine and Debian ship one — recognizable by the ARMd magic at offset 56). Ubuntu builds its arm64 kernels as EFI zboot: a zstd-compressed EFI/PE application with no bare-Image header, which the firmware-less -kernel path cannot start (the guest would hang with a silent console). The launcher detects this — an EFI-only /boot/vmlinuz — and boots it through edk2/AAVMF UEFI firmware (-bios), which still picks up the -kernel/-initrd/-append that follow via fw_cfg and runs the kernel’s own EFI stub to decompress and start it. The firmware comes from the host’s qemu-efi-aarch64 / edk2-aarch64 package; if it is missing, yoe run fails with an actionable message rather than launching a guest that never prints. Bare Image kernels are untouched and keep the plain direct-kernel path.

On real hardware: this UEFI handoff is a QEMU-side accommodation for the dev/CI machine. Booting an EFI-zboot kernel on a physical low-end SoC (e.g. a TI AM62 whose U-Boot uses the classic booti/extlinux flow, which also expects a bare Image) needs a separate decision when such a target is added — either the board’s U-Boot UEFI path (bootefi), or unwrapping the zboot payload back to a bare Image at image-assembly time. The bare-Image distros sidestep the question entirely.

The single ext4 partition becomes /dev/vda1 through QEMU’s virtio-blk disk. The disk is presented to the guest as a raw image file, attached with -drive file=...,format=raw,if=virtio.

qemu-x86_64

machine(
    name = "qemu-x86_64",
    arch = "x86_64",
    kernel = kernel(
        unit = "linux",
        defconfig = "x86_64_defconfig",
        cmdline = "console=ttyS0 root=/dev/vda2 rw",
    ),
    packages = ["syslinux"],
    partitions = [
        partition(label = "rootfs", type = "ext4", size = "600M", root = True),
    ],
    qemu = qemu_config(
        machine = "q35", cpu = "host", memory = "4G",
        firmware = "seabios",
        display = "none",
        ports = ["2222:22", "8080:80", "8118:8118"],
    ),
)

x86_64 goes through a real bootloader: SeaBIOS (QEMU’s built-in legacy BIOS, used by default on q35) reads the MBR off the virtio disk and jumps into syslinux, which loads the kernel from the ext4 rootfs.

This mirrors how a physical x86 board with legacy BIOS boots, so the same image will also boot on bare metal that lacks UEFI. (UEFI/OVMF support is set up in internal/device/qemu.go — pass firmware = "ovmf" instead to swap SeaBIOS for OVMF and boot via EFI.)

Why root=/dev/vda2 when there’s only one partition declared? syslinux installation inserts its own boot sector ahead of the data partition, so the visible partition index starts at 2 once the image is on disk. The rootfs is still that single ext4 — it just lives at vda2 from Linux’s view.

What runs inside the guest

Both machines pick up the generic linux unit from module-core, not a board-specific kernel. That unit builds arch/<arch>/boot/{Image,bzImage} plus the standard module set; no out-of-tree drivers, no custom defconfig fragment.

The userspace stack is whatever the project includes via its package list plus the rootfs base — busybox, OpenRC, apk-tools, and any apks pulled through module-alpine. See libc, init, and the Rootfs Base for the userspace layout.

Networking

yoe qemu wires a single virtio-net device through QEMU’s user-mode networking (SLIRP). The default forwards in the machine descriptor land SSH on host port 2222 and a couple of HTTP ports for app dev. Extra forwards can be passed on the CLI (yoe run --port 9000:9000, repeatable). A --port entry whose guest port matches a machine forward replaces that forward; an entry with a new guest port is appended.

That replace-on-match behavior is what makes --port usable for qemu-in-qemu — see Running inside a QEMU guest below.

Tuning at run time

Three knobs override the machine descriptor for a given developer without editing checked-in .star files:

All three live in local.star and apply the next time you run the same image. The TUI editor is on Setup → QEMU settings (press s, move down to QEMU settings, press Enter). Local-override forwards layer over the machine’s defaults with the same replace-on-guest-port rule that --port uses; the order at run time is machine ← local.star ← CLI, so a one-off --port still beats a saved entry for the same guest port.

How yoe qemu runs

The launcher in internal/device/qemu.go:

1. Picks the binary by arch: qemu-system-aarch64, qemu-system-x86_64, or qemu-system-riscv64.
2. Builds the arg list: -machine, -cpu, -m, -nographic by default (or -device virtio-vga -serial mon:stdio when yoe run --display is set, which lets QEMU open its native window and still leaves the serial console muxed onto host stdio), the virtio-blk drive, the virtio-net device with port forwards, and -bios if a firmware (OVMF/AAVMF) is set. On a same-arch host it adds -enable-kvm when /dev/kvm is present; when it is not (notably qemu-in-qemu without nested virtualization) it drops KVM, downgrades a host CPU to max, and runs under TCG software emulation instead — slower, but it still boots.
3. If the machine has no firmware, appends -kernel <vmlinuz> -append <cmdline> for the direct-boot path (this is what qemu-arm64 uses), taking the kernel from the built image’s /boot and adding -initrd <initrd.img> only when the image ships a real initramfs (e.g. Debian). The launcher reads these straight off the host rootfs, so the image build makes the kernel world-readable (Ubuntu otherwise ships it root-only, which would fail with “could not load kernel”). An image that carries no initramfs boots through the kernel’s built-in drivers (Alpine, and Ubuntu — whose kernel only recommends an initramfs generator); the launcher resolves the /boot/initrd.img symlink and omits -initrd when it dangles, rather than handing QEMU a path it would reject with “could not load initrd”.
4. Tries host QEMU first; falls back to running QEMU inside the toolchain-musl container with the project bind-mounted at /project if the host doesn’t have it installed.

The image yoe passes is whatever the assembly step produced, attached read-write. Restart-and-iterate workflows: rebuild, then re-run yoe qemu — the image is regenerated, the guest starts clean.

When to use which

• qemu-x86_64 is the right default for most development. KVM acceleration on an x86 host is essentially native speed; the boot path matches legacy-BIOS bare metal so what you debug here is what runs on similar hardware.
• qemu-arm64 is for catching arch-specific bugs (byte ordering, alignment, ARM64-only paths in code) without finding a board. It runs under TCG (software emulation) on x86 hosts, which is slow but faithful. On aarch64 hosts (an Apple Silicon Mac, an Ampere server) it uses KVM and is fast.
• For anything physical-board-shaped — secure boot, vendor blobs, display, real I/O — use the actual board’s machine descriptor.

Running inside a QEMU guest (qemu-in-qemu)

yoe run works from within a guest that is itself running under QEMU — useful for exercising a self-hosted yoe build. Two things differ from a run on the bare host, and yoe run handles both:

1. Port forwards collide. The outer guest already holds the machine’s default host forwards (2222, 8080, 8118), so a nested run cannot bind them. Remap the host side with --port; an entry whose guest port matches a default forward replaces it:

   yoe run base-image --port 12222:22 --port 18080:80 --port 18118:8118
   

2. No KVM. A guest has no /dev/kvm unless its host was started with nested virtualization. yoe run detects this and falls back to TCG software emulation automatically — it prints using TCG software emulation (slower) and boots. No flag is needed; expect roughly a 10–20× slowdown versus KVM.

To get full-speed nested runs instead of TCG, enable nested virtualization on the bare-metal host (kvm_intel/kvm_amd module option nested=1) and start the outer guest with a passthrough CPU so /dev/kvm appears inside it.

Raspberry Pi BSP (RPi4, RPi5)

yoe supports the Raspberry Pi 4 (BCM2711) and the Raspberry Pi 5 (BCM2712) through the raspberrypi4 and raspberrypi5 machines. Both target the 64-bit application cores and share the same firmware unit, the same config-file mechanism, and the same partition layout — they differ mainly in which kernel image and DTB land on the boot partition.

Machine descriptors:

• modules/module-bsp/machines/raspberrypi4.star
• modules/module-bsp/machines/raspberrypi5.star

Units under modules/module-bsp/units/bsp/:

• rpi-firmware — shared GPU bootloader blobs
• linux-rpi4, linux-rpi5 — per-board kernel builds
• rpi4-config, rpi5-config — per-board config.txt + cmdline.txt

Raspberry Pi 4 Model B. Photo: Laserlicht / Wikimedia Commons, CC BY-SA 4.0.

Raspberry Pi 5. Photo: SimonWaldherr / Wikimedia Commons, CC BY 4.0.

Running it on hardware

After yoe build --machine raspberrypi4 base-image (or raspberrypi5, or whatever image you’ve picked), yoe produces a single disk image under build/<image>.raspberrypi{4,5}/disk.img. The next steps are: write it to a microSD card, connect serial + power, and power on.

Authoritative hardware reference for everything below: https://www.raspberrypi.com/documentation/. The notes here cover the yoe-specific bits and a quick start; for pinouts, mechanical layout, and silicon details, defer to the Foundation’s docs.

Writing the image to a microSD card

Two ways:

• TUI — open yoe (no arguments), highlight the image unit, press f. The flash UI shows the candidate removable devices and you pick one. This is the fast path during development.

• CLI — yoe flash <image-unit> <device>. List candidates first:

  yoe flash list
  

  That prints the /dev/sdN (or /dev/mmcblkN) entries with size and model so you can identify the card. Then write:

  yoe flash --machine raspberrypi4 base-image /dev/sdN
  

  Swap base-image for whichever image unit you built and raspberrypi4 for raspberrypi5 as appropriate. --dry-run shows what it would do without touching the device; --yes skips the confirmation prompt for scripted flows.

Either path picks the right disk image from the build tree, refuses to write to anything mounted or anything that looks like an internal disk, and confirms before overwriting. If a partition on the target is mounted (most desktops auto-mount removable media on insert), the flash exits with a message — unmount the partitions and retry. Read the device path it’s about to write to; flashing the wrong block device will silently overwrite it.

Power

• RPi4 takes 5 V over USB-C. Plan for 5 V / 3 A in practice — the official 15 W USB-C supply or a class-compliant laptop / phone charger that negotiates 5 V / 3 A. Underpowering shows up as the lightning-bolt under-volt warning in dmesg, SD card corruption, WiFi disconnects under load, or the board silently rebooting once anything is plugged into USB.
• RPi5 takes 5 V over USB-C with USB-PD. The official 27 W supply negotiates 5 V / 5 A and is required for full peripheral current on the USB ports; a 5 V / 3 A PD supply boots fine but the firmware caps USB current unless you set usb_max_current_enable=1 in config.txt.

Serial console

The kernel and the GPU firmware both bring up a UART on the GPIO header when enable_uart=1 is in config.txt. Settings are 115200 8N1, no flow control, on three pins of the 40-pin header:

The Linux device name differs between boards:

• RPi4 — mini-UART on ttyS0 (cmdline.txt’s console=ttyS0,115200)
• RPi5 — PL011 on ttyAMA10 (cmdline.txt’s console=ttyAMA10,115200)

Raspberry Pi boards do not have an on-board USB-to-serial bridge. The header is wired in the standard Raspberry Pi USB-to-TTL serial cable pinout, so you’ll need an external 3.3 V adapter:

• Recommended: FTDI TTL-232R-RPi (product page · Digi-Key). Purpose-built for this header, 3.3 V signals, genuine FTDI silicon (so the host’s ftdi_sio driver picks it up reliably and you don’t fight knock-off CP210x / CH340 driver quirks). Plug-and-play with no wiring decisions.
• Any other 3.3 V USB-TTL adapter (Adafruit 954, generic FTDI/CP210x/CH340 dongles) works too — connect three jumpers, leave the 5 V lead disconnected since the board has its own power.

Wiring is “cross-over”: the cable’s TX goes to the board’s RX (pin 10), and the cable’s RX goes to the board’s TX (pin 8). GND to GND (pin 6).

Once wired, plug the USB end into the host; it enumerates as /dev/ttyUSB0 (FTDI / CH340 / CP210x) or /dev/ttyACM0 (some CDC ACM adapters). Open it at 115200 with tio:

tio -b 115200 /dev/ttyUSB0

If nothing appears after power-on:

• Confirm enable_uart=1 made it into config.txt on the boot partition.
• Swap RX/TX. The single most common mistake.
• Confirm the adapter is 3.3 V, not 5 V. A 5 V adapter on the SoC’s UART pins is the fastest way to brick that GPIO.
• dmesg | tail on the host — the USB-TTL adapter should enumerate within a second or two of plugging in. If it doesn’t, the cable / dongle is the issue, not the board.

First boot

A successful boot prints (roughly, abbreviated):

[    0.000000] Booting Linux on physical CPU 0x...
[    0.000000] Linux version 6.12.x ...
...
Welcome to <hostname>
<hostname> login:

(The GPU firmware stage is silent on the UART — the first thing you see is the kernel’s earlycon output.)

The default credentials from base-files-* are root (no password) and user / password. Change them before connecting the board to any network you don’t fully control — the OpenSSH unit defaults to enabled once the package lands in the image.

If you get a rainbow splash and nothing else, the GPU firmware loaded but couldn’t find a kernel. See When something fails below.

The Raspberry Pi boot chain

Raspberry Pi boards do not use a conventional CPU-side bootloader. The boot sequence is GPU-first:

RPi4:  GPU ROM ─ reads ─→ bootcode.bin (SD) ─ loads ─→ start4.elf ─ reads ─→ config.txt + kernel + DTB ─ starts ARM cores
RPi5:  EEPROM  ────────────────────────────────────────────→ (same flow, no bootcode.bin, kernel_2712.img)

The VideoCore GPU is the first thing alive on the SoC. On RPi4, the on-board ROM is minimal and reads bootcode.bin from the SD card to bring the rest of the GPU firmware online. On RPi5, all that early code lives in an EEPROM on the board, so there is no bootcode.bin on the SD — the GPU goes straight from EEPROM to reading config.txt.

From there the flow is identical on both:

1. GPU firmware (start4.elf on RPi4, the EEPROM image on RPi5) parses config.txt.
2. It loads the kernel image named by config.txt’s kernel= line plus the matching DTB.
3. It reads cmdline.txt and passes it as the kernel command line.
4. It releases the ARM cores at the kernel entry point.

There is no U-Boot, no SPL, no TF-A in this chain by default. (You can chain-load U-Boot from the GPU firmware if you want EFI semantics, but yoe doesn’t.)

Shared units

rpi-firmware

unit(
    name = "rpi-firmware",
    source = "https://github.com/raspberrypi/firmware.git",
    tag = "1.20250305",
)

Prebuilt blobs only — no compilation. Installs the GPU firmware files the RPi family needs on the FAT boot partition:

RPi5 doesn’t need any of these on the SD card (the EEPROM ships them), but yoe stages them anyway — installed packages are uniform across both boards and the extra ~10 MB on the FAT partition is harmless.

linux-rpi4 / linux-rpi5

Both kernels build from github.com/raspberrypi/linux on branch rpi-6.12.y — the Raspberry Pi Foundation’s downstream tree carrying Broadcom GPU drivers, the wireless stack, and out-of-tree patches that aren’t yet in mainline.

The two units differ in defconfig and output naming:

Both run a defconfig merge step that folds in container.cfg — a small fragment that enables overlayfs, cgroups v2, netfilter, namespaces, and the eBPF cgroup hooks needed to make Docker / Podman / runc work out of the box. The same fragment is also used by linux-beagleplay; see BeaglePlay for the parallel.

Overlays go to /boot/overlays/*.dtbo. Kernel modules install into the rootfs under /lib/modules/<kver>/, with DEPMOD=true skipping depmod at build time (the build container doesn’t have it; the target runs depmod -a at first boot via OpenRC).

rpi4-config / rpi5-config

Two-file boot config: config.txt for the GPU firmware, cmdline.txt for the kernel.

config.txt (RPi4 / RPi5 differences):

# RPi4
arm_64bit=1
enable_uart=1
kernel=kernel8.img
dtoverlay=vc4-kms-v3d
disable_splash=1

# RPi5
arm_64bit=1
enable_uart=1
kernel=kernel_2712.img
dtoverlay=vc4-kms-v3d-pi5
disable_splash=1

• arm_64bit=1 flips the GPU firmware into 64-bit kernel mode (it defaults to 32-bit for legacy compatibility).
• enable_uart=1 brings up the mini-UART on RPi4 / the PL011 on the GPIO header so you get a serial console.
• kernel= matches what the per-board kernel unit installed.
• dtoverlay=vc4-kms-v3d selects the modern KMS DRM driver for the VideoCore GPU (the -pi5 variant on RPi5 targets VC6 / RP1).
• disable_splash=1 skips the rainbow boot logo.

cmdline.txt:

RPi4: console=ttyS0,115200 root=/dev/mmcblk0p2 rootfstype=ext4 rootwait rw
RPi5: console=ttyAMA10,115200 root=/dev/mmcblk0p2 rootfstype=ext4 rootwait rw

• RPi4 uses the BCM2711 mini-UART, exposed as ttyS0.
• RPi5 uses a different UART (PL011 routed differently in the BCM2712 GPIO multiplexer), exposed as ttyAMA10.
• Both root from /dev/mmcblk0p2 — second partition on the SD card.

Image assembly

Both machines use the same partition layout:

partitions = [
    partition(label = "boot",   type = "vfat", size = "64M",
              contents = ["kernel", "dtbs", "firmware"]),
    partition(label = "rootfs", type = "ext4", size = "1G", root = True),
]

The contents patterns are name-based selectors that map to file globs under /boot/ in the assembled rootfs:

The config.txt and cmdline.txt written by the per-board config unit land in /boot/ too and are matched by the firmware/dtbs/kernel selectors as appropriate.

SD card layout the GPU expects:

The GPU firmware doesn’t care about partition labels or GPT — it reads the first FAT partition off the MMC. Linux mounts the same FAT at /boot and uses partition 2 as /.

What’s the same and what differs across boards

Shared:

• Same upstream kernel tree, same branch, same container.cfg fragment.
• Same rpi-firmware package (RPi5 ignores the SD copies but they’re harmless).
• Same partition layout and root device.
• Same OpenRC / busybox / apk userspace.

Per-board:

• linux-rpi4 vs linux-rpi5 (defconfig, kernel image name, DTBs).
• rpi4-config vs rpi5-config (kernel image name in config.txt, KMS overlay variant, serial console device).
• The machine descriptor (which kernel unit to use, which config unit).

If you’re adding a Raspberry Pi 3 or Pi Zero 2 W, the work is mostly mechanical: clone the per-board kernel + config unit, swap defconfig and DTB names, and add a machine descriptor. The firmware unit and the partition layout don’t need to change.

Self-hosting yoe builds on the RPi5

The selfhost-image turns a Raspberry Pi 5 into a standalone yoe build host — yoe CLI, Go, Docker, git, helix, and the rest of the dev image, all on one bootable card or NVMe SSD. See Self-Host on RPi5 for the build, flash, first-boot, and NVMe setup walkthrough.

When something fails

• Rainbow screen, no kernel boot. GPU firmware loaded but couldn’t find the kernel. Check config.txt’s kernel= line and confirm the named file is on the FAT partition.
• Black screen, never sees UART. enable_uart=1 missing from config.txt, or the wrong console= in cmdline.txt for the board.
• Kernel boots but no rootfs. SD card not the only block device the kernel sees, or rootwait not in the cmdline — partition probing can race the kernel.
• WiFi / Bluetooth missing. The Foundation kernel pulls in brcmfmac firmware blobs that aren’t yet in this BSP. Add them via a separate unit if needed; the linux-firmware tree on the Foundation GitHub has them under brcm/.

BeaglePlay BSP

This page documents the BeaglePlay board support in yoe: which units make up the BSP, how they cooperate at build time, and how the resulting artifacts are arranged on the SD card or eMMC.

The hardware is BeagleBoard.org’s BeaglePlay, built on TI’s AM625 SoC (quad Cortex-A53 application cores, a Cortex-R5F MCU island, and a Cortex-M4F dead-man core). The cores run with help from TI’s K3 security firmware (“TIFS” / “SYSFW”) and a small device-manager (“DM”) payload — both shipped as signed blobs by TI.

The machine descriptor lives at modules/module-bsp/machines/beagleplay.star; everything below is built by units under modules/module-bsp/units/bsp/.

Photo: BeagleBoard.org, CC BY-SA 4.0.

Running it on hardware

After yoe build --machine beagleplay base-image (or whatever image you’ve picked), yoe produces a single disk image under build/<image>.beagleplay/disk.img (the exact path depends on the image’s disk task). The next steps are: write it to a microSD card, connect serial

• power, and power on.

Authoritative hardware reference for everything below: https://docs.beagleboard.org/boards/beagleplay/. The notes here cover the yoe-specific bits and a quick start; for pinouts, mechanical layout, and silicon details, defer to BeagleBoard.org’s docs.

Writing the image to a microSD card

Two ways:

• TUI — open yoe (no arguments), highlight the image unit, press f. The flash UI shows the candidate removable devices and you pick one. This is the fast path during development.

• CLI — yoe flash <image-unit> <device>. List candidates first:

  yoe flash list
  

  That prints the /dev/sdN (or /dev/mmcblkN) entries with size and model so you can identify the card. Then write:

  yoe flash --machine beagleplay base-image /dev/sdN
  

  Swap base-image for whichever image unit you built (jukebox-image, your own, …). --dry-run shows what it would do without touching the device; --yes skips the confirmation prompt for scripted flows.

Either path picks the right disk image from the build tree, refuses to write to anything mounted or anything that looks like an internal disk, and confirms before overwriting. If a partition on the target is mounted (most desktops auto-mount removable media on insert), the flash exits with a message — unmount the partitions and retry. Read the device path it’s about to write to; flashing the wrong block device will silently overwrite it.

Choosing boot media (SD vs eMMC)

The AM625 ROM checks boot sources in a sequence set by the SYSBOOT straps on the board. On BeaglePlay the default boot order looks at the on-board 16 GB eMMC first.

To boot from microSD instead, hold the USR button while applying power or pressing reset. That overrides the ROM’s boot search to start at the SD slot. Release the button once you see the SPL banner on the serial console (~1 second). The override is per-boot — power-cycling without the button reverts to eMMC.

For development you typically want microSD boot: it’s easy to re-flash, hard to brick, and leaves the eMMC’s contents alone. For production you’d flash a known image into eMMC (either by booting an SD-based installer or over USB-DFU) and ship without an SD card.

The yoe image is identical for both paths — the boot chain on eMMC and on SD comes from the same tiboot3.bin / tispl.bin / u-boot.img artifacts. yoe’s uEnv.txt hardcodes root=/dev/mmcblk1p2 (eMMC); if you boot off SD without re-flashing eMMC, the kernel will still try to mount the eMMC’s rootfs. Either flash both, or edit bootargs to root=/dev/mmcblk0p2 for SD-only.

Power

BeaglePlay takes 5 V over USB-C on the dedicated power connector. A phone-class 5 V / 1 A supply is enough for the board itself idling. Plan for at least 3 A in practice — a class-compliant USB-C charger (a laptop / phone charger that negotiates 5 V / 3 A) is the cheapest path. Underpowering shows up as kernel crashes during DRAM stress, WiFi disconnects under load, or the board silently rebooting once anything is plugged into USB.

The power connector is not the same physical port as the debug serial-USB. Read the silkscreen.

Serial console

The kernel and U-Boot both use the SoC’s UART0 (Linux ttyS2) at 115200 8N1, no flow control. This is the same setting uEnv.txt expects and what am62xx.inc upstream uses, so any client targeting “BeaglePlay serial console” will be at 115200 by default.

BeaglePlay does not have an on-board USB-to-serial bridge. The debug UART is brought out on a 3-pin header wired in the Raspberry Pi USB-to-TTL serial cable pinout — the same GND / RXD / TXD layout the standard Pi debug cables use. You’ll need an external adapter:

• Recommended: FTDI TTL-232R-RPi (product page · Digi-Key). Purpose-built for the Pi-style header, 3.3 V signals, genuine FTDI silicon (so the host’s ftdi_sio driver picks it up reliably and you don’t fight knock-off CP210x / CH340 driver quirks). Plug-and-play with no wiring decisions.
• Any other 3.3 V USB-TTL adapter (Adafruit 954, generic FTDI/CP210x/CH340 dongles) works too — connect three jumpers, leave the 5 V lead disconnected since the board has its own power.

Wiring is “cross-over”: the cable’s TX goes to the board’s RX, and vice versa. GND to GND. Check the silkscreen on the BeaglePlay header for RX / TX markings — those refer to the board’s signals.

Once wired, plug the USB end into the host; it enumerates as /dev/ttyUSB0 (FTDI / CH340 / CP210x) or /dev/ttyACM0 (some CDC ACM adapters). Open it at 115200 with tio:

tio -b 115200 /dev/ttyUSB0

If nothing appears after power-on:

• Swap RX/TX. The single most common mistake.
• Confirm the adapter is 3.3 V, not 5 V. A 5 V adapter on the AM625’s UART pins is the fastest way to brick the SoC’s UART block.
• dmesg | tail on the host — the USB-TTL adapter should enumerate within a second or two of plugging in. If it doesn’t, the cable / dongle is the issue, not the board.

First boot

A successful boot prints (roughly, abbreviated):

U-Boot SPL 2025.10 ...                  ← R5 SPL (from tiboot3.bin)
Trying to boot from MMC1                 ← reading tispl.bin
U-Boot SPL 2025.10 ...                  ← A53 SPL (from tispl.bin)
NOTICE:  BL31: ...                       ← TF-A handoff
I/TC: OP-TEE version: 4.9.0 ...          ← OP-TEE handoff
U-Boot 2025.10 ...                       ← U-Boot proper
Hit any key to stop autoboot:
...
Booting Linux on physical CPU 0x...      ← kernel
...
Welcome to <hostname>
<hostname> login:

The default credentials from base-files-* are root (no password) and user / password. Change them before connecting the board to any network you don’t fully control — the OpenSSH unit defaults to enabled once the package lands in the image.

If the boot stops at U-Boot’s Hit any key prompt and never autoboots, either uEnv.txt wasn’t found on the boot partition, or uenvcmd failed mid-way. Drop to the U-Boot shell, ls mmc 1:1 to see what’s on the FAT partition, and re-run the load commands one by one to see which one errors.

Boot chain at a glance

The AM625 boot ROM expects a multi-stage handoff. Each blob feeds the next, and most of the blobs are themselves FIT images that bundle code from several upstream projects.

ROM (AM625)
  └── tiboot3.bin                  ← U-Boot R5 SPL + TIFS + DM
        └── tispl.bin              ← U-Boot A53 SPL + BL31 (TF-A) + BL32 (OP-TEE) + DM
              └── u-boot.img       ← U-Boot proper (A53)
                    └── Image      ← Linux kernel (arm64) + DTB
                          └── init ← OpenRC (busybox PID 1)

Each arrow is “loads and jumps to”. Two CPU clusters take turns: the R5F brings the secure firmware up first, then hands the SoC over to the A53s for the rest of the chain.

The units

Sources and pinning:

• ti-linux-firmware — git://git.ti.com/... branch ti-linux-firmware, prebuilt blobs only. Cadence/PRU/etc. also ship through this unit so other rootfs units can pick what they need without re-cloning.
• tfa-k3 — git.trustedfirmware.org/TF-A master. K3 platform support lives only on master (no per-release tag), and meta-ti pins to a master SRCREV; we follow the same branch so future syncs roll forward.
• optee-k3 — upstream OP-TEE/optee_os at tag 4.9.0, mirroring meta-ti’s optee-os-ti-version.inc.
• u-boot-beagleplay / u-boot-beagleplay-r5 — both build from github.com/beagleboard/u-boot branch v2025.10-Beagle. Same tree, two defconfigs (_a53_ and _r5_), so they share the dep chain for build tools.
• linux-beagleplay — github.com/beagleboard/linux branch v6.12.43-ti-arm64-r54, the AM625 device tree + cape overlays that meta- beagle ships.
• beagleplay-config — local Starlark, generates uEnv.txt only.

All units build in the toolchain-musl container with container_arch = "target", i.e. the aarch64 Alpine container under QEMU user-mode. There is no cross-compilation in the conventional sense — the build sees the target ISA as native. The R5 SPL is the one exception (Cortex-R5F is armv7-R, an ISA the aarch64 toolchain can’t emit) and pulls Alpine’s gcc-arm-none-eabi cross toolchain via module-alpine.

Stage-by-stage walkthrough

Stage 0: ROM

The AM625 ROM is masked silicon. On power-up it reads tiboot3.bin from the configured boot media (SD MMC0 / eMMC MMC1 / OSPI, selected by SYSBOOT straps). The file is a FIT image: the ROM walks it, verifies signatures against TI’s keys (or, on a GP — General-Purpose — part, accepts a self-signed blob), and starts execution on the R5F.

Stage 1: R5F SPL — tiboot3.bin

Built by u-boot-beagleplay-r5. The output tiboot3.bin packs three things via binman:

1. R5 SPL — early U-Boot, runs on the Cortex-R5F.
2. TIFS / SYSFW — ti-sysfw/ti-fs-firmware-am62x-gp-acl.bin from ti-linux-firmware. The R5 SPL hands the SoC over to TIFS; from that point on, every privileged operation (power, clock, security) is brokered through TIFS via the TI SCI mailbox protocol.
3. DM firmware — ti-dm/am62xx/...xer5f from ti-linux-firmware. The “Device Manager” runs alongside TIFS on the R5 cluster and handles non-secure resource management once Linux is up.

The R5 SPL initializes DDR through the K3 DDR driver, sets up the first SD/eMMC controller, and loads the next stage off the FAT partition.

Stage 2: A53 SPL — tispl.bin

Built by u-boot-beagleplay. Another binman-assembled FIT, this time holding:

1. A53 SPL — second-stage U-Boot, runs on Cortex-A53.
2. BL31 — tfa-k3’s bl31.bin, the Arm TF-A secure monitor (runs at EL3, owns SMCs, dispatches to OP-TEE).
3. BL32 — optee-k3’s bl32.bin (= tee-pager_v2.bin), the OP-TEE OS running in the secure world (S-EL1).
4. DM firmware — same ti-dm payload, reused here because the A53 SPL re-loads it once it has full access to system memory.

These resolve through the merged sysroot — tfa-k3 and optee-k3 install their outputs to /lib/firmware/bl{31,32}.bin, and u-boot-beagleplay’s make line names them with BL31= / TEE= / TI_DM= / BINMAN_INDIRS=. binman then sucks them into the FIT.

After loading, the A53 SPL parks BL31 at EL3 and BL32 in the secure world, then jumps to U-Boot proper at EL2.

Stage 3: U-Boot proper — u-boot.img

Same u-boot-beagleplay build, second output. This is the full U-Boot shell — environment, distro_bootcmd, network, USB, FAT/EXT drivers. By default it sources uEnv.txt from the FAT partition and runs uenvcmd.

Stage 4: Linux — Image + DTB

linux-beagleplay builds the BeagleBoard fork of 6.12 with defconfig plus a small fragment that turns on container runtime support (cgroups v2, overlay, namespaces — same fragment used by the Raspberry Pi units, kept in linux-beagleplay/container.cfg).

The kernel and the BeaglePlay-specific DTB (k3-am625-beagleplay.dtb) land on the FAT partition; modules go to the rootfs at /lib/modules/<ver>/.

Stage 5: userspace

The kernel pivots to /dev/mmcblk1p2, busybox init reads /etc/inittab, which fires OpenRC’s sysinit → boot → default runlevels. See libc, init, and the Rootfs Base for how that base shapes up.

Build-time dependency layering

Within the BSP, dep order matters because binman pulls inputs out of the merged per-unit sysroot:

ti-linux-firmware ─┐
                   ├─→ u-boot-beagleplay-r5  → tiboot3.bin
                   │
                   ├─→ u-boot-beagleplay    → tispl.bin, u-boot.img
tfa-k3 ────────────┤      (also embeds bl31, bl32, DM)
optee-k3 ──────────┘
linux-beagleplay   (independent — kernel + DTB)
beagleplay-config  (independent — generates uEnv.txt)

u-boot-beagleplay declares ti-linux-firmware, tfa-k3, and optee-k3 as deps so their /lib/firmware/... outputs are visible in its sysroot at build time. The R5 SPL declares only ti-linux-firmware (it doesn’t embed BL31 or BL32).

Both U-Boot units also pull a substantial Python/host-tools chain through module-alpine — binman is a Python program with optional dependencies on pyelftools, pyyaml, jsonschema, yamllint, and friends. Which ones get exercised depends on the defconfig: the A53 build uses a smaller subset, the R5 build’s binman config invokes the ti-board-config entry type which drags in the full schema-validation stack. The dep lists in the two .star files reflect that — they intentionally differ.

Image assembly

The machine descriptor declares two partitions:

partitions = [
    partition(label = "boot",   type = "vfat", size = "128M",
              contents = ["tiboot3.bin", "tispl.bin", "u-boot.img",
                          "Image", "k3-am625-beagleplay.dtb",
                          "uEnv.txt"]),
    partition(label = "rootfs", type = "ext4", size = "1G", root = True),
]

Image assembly scans the assembled rootfs (built from all packages apks) and matches each contents glob against /boot/. Every file listed lands in the FAT partition at the root level (yoe’s vfat assembly flattens paths currently — that’s why uEnv.txt is at the partition root, not under extlinux/).

The MMC layout the AM625 ROM expects:

The kernel command line in uEnv.txt resolves root=/dev/mmcblk1p2, which is the ext4 partition on the on-board eMMC (mmc 1 in U-Boot, mmcblk1 in Linux — mmc 0 is the SD slot).

U-Boot environment

beagleplay-config writes uEnv.txt to /boot/:

bootargs=console=ttyS2,115200 earlycon=ns16550a,mmio32,0x02800000 \
  root=/dev/mmcblk1p2 rootfstype=ext4 rootwait rw
loadaddr=0x82000000
fdt_addr_r=0x88000000
uenvcmd=load mmc 1:1 ${loadaddr} Image; \
  load mmc 1:1 ${fdt_addr_r} k3-am625-beagleplay.dtb; \
  booti ${loadaddr} - ${fdt_addr_r}

ttyS2 is BeaglePlay’s debug UART (the same one meta-ti’s am62xx.inc names in SERIAL_CONSOLES). The DRAM load addresses keep the kernel and DTB clear of the SPL/U-Boot’s own footprint.

Notable build choices

A few things are non-obvious and worth knowing if you go to change a unit:

• ARCH=arm, not ARCH=arm64, for U-Boot and OP-TEE. Both upstreams keep all ARM code (32- and 64-bit) under arch/arm/ in their source tree. The 64-bit secure world / kernel selection happens via CONFIG_* or CFG_ARM64_core=y, not via the directory layout. yoe exports ARCH=arm64 as the target arch in the build env, so each unit’s make line overrides it explicitly.
• No CROSS_COMPILE prefix in the A53 builds. Inside the target Alpine container, plain gcc/ld/ar already target aarch64; there is no aarch64-linux-musl- triplet binary. The R5 SPL is the exception because it needs arm-none-eabi- to emit armv7-R code.
• TF-A overrides every per-tool variable. TF-A’s toolchain-detection searches for aarch64-none-elf-gcc / aarch64-linux-gnu-gcc by default. The tfa-k3 unit passes CC=gcc LD=gcc AS=gcc AR=gcc-ar OC=objcopy OD=objdump on the make line so detection finds the Alpine native tools. It also passes CFLAGS= CPPFLAGS= empty, because TF-A’s cflags.mk merges the env values into its compile line and yoe’s -I/build/sysroot/usr/include would trip -Werror=missing-include-dirs.
• OP-TEE TAs restricted to 64-bit. CFG_USER_TA_TARGETS=ta_arm64 skips building 32-bit Trusted Applications. With CFG_ARM64_core=y the default would be both 32 and 64, which requires a separate arm-linux-gnueabihf- toolchain that we don’t carry. AM62x runs a 64-bit secure world so 32-bit TAs aren’t needed.
• U-Boot’s host tools want a sysroot. mkeficapsule (and other signing/binman helpers) link against gnutls/openssl. yoe’s env doesn’t reach U-Boot’s HOSTCC/HOSTLD path, so both U-Boot units pass HOSTCFLAGS=-I/build/sysroot/usr/include and HOSTLDFLAGS=-L/build/sysroot/usr/lib on the make command line. They also export SWIG_LIB to redirect Alpine’s swig binary at the merged sysroot for pylibfdt generation.

When something fails

The boot chain is long and each stage is opinionated about exactly what it accepts from the previous one. Common breakage modes:

• ROM rejects tiboot3.bin. Wrong TIFS variant for the silicon (GP vs HS-FS vs HS-SE), or the FIT signature is bad. Confirm the ti-sysfw/...-gp-acl.bin selection in u-boot-beagleplay-r5’s binman config matches the part you have.
• tispl.bin loads but jumps into nothing. Usually BL31/BL32 didn’t land in the FIT — check that tfa-k3 and optee-k3 actually built and their outputs exist under /build/sysroot/lib/firmware/.
• DM firmware “not found”. binman’s BINMAN_INDIRS resolution: make sure the path matches /build/sysroot/lib/firmware. The TI_DM filename embeds the silicon revision (am62xx) — if you bump SoC variant, that filename changes too.
• Kernel boots but no console. console=ttyS2 and the matching earlycon= in uEnv.txt must reach the kernel. Older BeaglePlay docs use ttyAMA0/ttymxc*/etc. — those are different SoCs.

Yoe and distributions

Every yoe image targets exactly one distro — alpine, debian, ubuntu, or (in the future) something else. The choice determines the package format, the libc family, the toolchain container, the on-target package manager, and which prebuilt packages are reachable from the image’s closure. This page is the orientation guide: what “distro” means inside yoe, when to pick which one, and how distros plug into the rest of the system. For per-distro detail, see module-alpine, module-debian, and module-ubuntu.

What a distro means in yoe

A distro in yoe is a runtime compatibility class, not a brand preference. Choosing distro = "alpine" on an image means:

• Package format: .apk. The image-time installer is apk-tools.
• Libc family: musl. The toolchain container is toolchain-musl; every binary in the image links against musl.
• Userland conventions: OpenRC for init, busybox utilities, alpine-baselayout for /etc structure, alpine signing keys for upstream packages.

Choosing distro = "debian" means the corresponding glibc / .deb / systemd-or-sysvinit / dpkg-trust stack. The two are not mix-and-match within a single image; a .deb won’t install in an alpine rootfs and musl-linked binaries don’t run in a glibc rootfs.

Setting the distro

Each image(...) declaration can carry an explicit distro field:

image(
    name = "edge-image",
    distro = "alpine",
    artifacts = [...],
)

When unset, yoe resolves the effective distro through a three-level cascade:

1. The image’s own distro field — highest priority.
2. local.star’s default_distro_override — a per-developer override (not committed) for trying a different distro locally without editing project config.
3. PROJECT.star’s defaults.distro — the project-wide fallback.

If none of the three is set, image evaluation errors immediately. The distro choice is too consequential to pick silently.

yoe build also accepts a --distro flag that overrides the default for a single invocation, sitting at the same level as default_distro_override (an image’s own explicit distro still wins). This is mainly useful when the same image name is defined in more than one distro — for example a base-image in both module-alpine and module-debian — and you want to build a specific variant without editing local.star:

yoe build --distro alpine base-image
yoe build --distro debian base-image

Source-built units are typically distro-neutral, but can be tagged

A unit declared with unit(...) (in module-core or anywhere else) defaults to distro-neutral: leave distro unset and the unit is visible to every consuming image regardless of its distro. The same openssl or zlib source unit builds against musl when consumed by an alpine image and against glibc when consumed by a debian image, producing two distinct binaries cached under two distinct hash keys. The unit’s definition is the same; the build context (which toolchain, which libc) is different.

This is what lets a project share most of its source-built userland across distros while still producing libc-correct binaries. It’s the common case for module-core’s userland units.

But the distro field is available on every unit(...) declaration, including source-built ones. Set it explicitly when the unit genuinely is distro-specific — when the build assumes alpine’s patches or musl’s headers, when it ships configuration that only makes sense on one libc family, when the upstream source is hard- coded to one userland’s conventions:

# A unit whose configure flags assume musl's nsswitch shape;
# building it under glibc would produce a broken binary even if
# the toolchain were available.
unit(
    name    = "some-musl-only-thing",
    distro  = "alpine",
    source  = "https://...",
    tag     = "v1.2.3",
    ...
)

A tagged source unit becomes invisible to closures of other distros, exactly like a feed-materialized one. The same closure walker filter applies regardless of where the unit registered. The default is “no tag” because most source builds work fine against both libc families; the tag is an opt-in for the cases where they genuinely don’t.

Feed-materialized units (from alpine_feed / apt_feed) always carry a hard distro affinity automatically — an alpine .apk literally is not a debian .deb, and the synthetic module that produces them sets distro on every materialized *Unit. You don’t write that tag; the feed builtin writes it for you.

Per-distro dep additions

A source unit often works fine in both backends but needs different package names for the same role. Alpine packages setuptools as py3-setuptools; debian splits it across python3-setuptools and friends. Alpine bundles headers + library in one apk (zlib); debian splits them (zlib1g-dev for build, zlib1g for runtime). The unit’s behavior is the same; the dep names aren’t.

distro_deps and distro_runtime_deps express that without resorting to two tagged copies of the same unit or per-project conditionals that bake one distro’s names in at registration time and break the other distro’s closure walks:

unit(
    name = "meson",
    ...
    deps = ["samurai", "toolchain"],
    distro_deps = {
        "alpine": ["python3", "py3-setuptools"],
        "debian": ["python3.11", "python3-setuptools"],
    },
)

Effective deps at any consuming closure = deps + distro_deps[consumer_distro]. A unit with no distro_deps entry for the consumer’s distro just gets plain deps — no error, no fallback to some other distro’s list. Same shape for runtime_deps / distro_runtime_deps.

Reach for distro_deps when one source unit can satisfy both backends with different dep names. Reach for the distro tag instead when the build itself only makes sense for one libc family (musl-only configure flags, distro- specific patches), or when the two backends warrant materially different build recipes — then maintain two tagged units rather than one unit with branching build steps.

Choosing a distro

The picks are bounded today:

¹ Wall-clock to reassemble a working dev image on a qemu-x86_64 target with the full dependency closure already built and cached, so the figure isolates the image-assembly step — package install plus configure — rather than the source builds behind it. Measured as a median over several runs; the gap reflects how much each package format does at install time (apk extracts; dpkg also runs maintainer scripts), so it widens with package count and on foreign-arch targets where those scripts run under emulation.

Footprint. The two backends differ sharply in size. The minimal boot + SSH image — the platform floor for a device you can log into, with no developer tooling on either side (kernel, init, libc, shell, package manager, sshd, DHCP, one login user) — is about 85 MB on Alpine and ~405 MB on Debian on a qemu-x86_64 target (Debian trixie), roughly 4.8×. Most of the gap is the stock linux-image-amd64 kernel, which ships a driver for every machine it might ever run on; Alpine here boots a kernel yoe built from source and tailored to the target, so its module tree is a few megabytes rather than ~107 MB. A production Debian image can swap in a tailored kernel too — out of the box, the distro kernel brings everything. The remainder is the platform itself: glibc and its multiarch libraries, systemd, the full apt/dpkg stack, complete coreutils instead of busybox applets. Alpine’s musl + busybox + OpenRC base is simply lighter, and on a device that difference compounds.

If you don’t have a hard reason for debian — a vendor-supplied binary, a glibc-only library, a fleet already running debian — start with alpine. The defaults work, the cache hits land, and the boot-and-SSH path has miles on it.

If you do have a hard reason, debian’s plumbing is in place: feeds resolve, packages mirror verbatim, the image assembler runs mmdebstrap against the project’s local repo to unpack and configure the rootfs in a single pass, and the project repo emits a signed InRelease. The assembled rootfs boots in QEMU and accepts SSH — exercised nightly in CI on both arches — so the path works end to end; what keeps the experimental label is production hardening (tailored kernels, security review, a settled OTA story), not basic bring-up.

Mixing distros in one project

A project can define alpine images and debian images side-by-side. Each image’s effective distro is independent — yoe doesn’t enforce “one distro per project.”

Cross-distro coexistence is handled in three parallel layers that all keep distros separated:

• On-disk repos are per-distro. repo/<project>/alpine/<arch>/ holds apks; repo/<project>/debian/dists/<suite>/ holds debs. Each on-target package manager sees only its own subtree.
• On-disk build directories are per-distro: build/<distro>/<unit>.<scope>/destdir/. A source-built unit consumed by both an alpine and a debian image has two separate destdirs, each holding a libc-correct binary.
• The in-memory catalog stores every unit by (module, name) and exposes per-distro views: an alpine image queries DistroViews["alpine"] and gets alpine-tagged units (plus distro-neutral source units); a debian image queries DistroViews["debian"] and gets debian-tagged units (plus the same source units). Same-named entries from different distro feeds live in different UnitsByModule buckets and different DistroViews cells; they never clobber each other.

The one architectural cost mixing distros DOES pay:

• Source-built units build per consuming distro. A source-built openssl consumed by both an alpine and a debian image builds twice — once in each toolchain container — producing two binaries cached separately. This is the correctness mechanism, not a bug; the cost is one cache entry per (unit, distro) pair, and every subsequent build hits the cache.

The primary multi-distro use case: alpine app containers on a debian host

The pattern that motivates mixing distros within a single project is building alpine-based application containers that get deployed inside a debian host image. The host image is debian for the reasons that drive picking debian in the first place — glibc compatibility for vendor drivers, broad apt ecosystem, an existing fleet management story. The application containers are alpine for the reasons that drive picking alpine: small footprint, fast startup, minimal attack surface, comprehensive musl-clean package wrapping.

A representative PROJECT.star shape:

# Host image: debian. Boots the device, runs vendor agents,
# manages the container runtime, handles OTA. The app container
# is in artifacts, so the image build embeds it into the host's
# container store at image-assembly time.
image(
    name = "device-host",
    distro = "debian",
    artifacts = [
        "apt", "openssh-server", "linux-image-amd64",
        "containerd",
        "app",                # the alpine container below
    ],
)

# App container: alpine. Holds the actual product workload.
# Built as a deployable OCI artifact, not as a bootable image.
container(                                          # (planned)
    name = "app",
    distro = "alpine",
    artifacts = ["busybox", "my-app", "my-app-config"],
)

Status (planned): the container(...) form shown above — producing a deployable application-container artifact from an artifacts = [...] list, embeddable in a host image’s own artifacts — is not yet implemented. Today, container(...) exists only for declaring build containers (toolchain-musl, toolchain-glibc, …) from a Dockerfile. The planned extension repurposes the same builtin name for deployable application containers: when called with artifacts = [...], the unit emits an OCI image rather than building a Dockerfile. See Deployable Containers spec for the spec and the current implementation status. The architectural shape this section describes — distros as orthogonal axes, multi-distro projects, three-layer separation — is current behavior; only the deployable-container form of the container(...) builtin is future work.

Both build from the same PROJECT.star, share the same source-built userland where applicable (a source unit consumed by both builds twice — once musl-linked for the alpine container, once glibc-linked for the debian host — under separate cache keys), and ship together as part of the same project release.

Other multi-distro shapes exist (a product line with a small alpine edge device and a larger debian gateway, both shipped from one repo) but the alpine-app-in-debian-host pattern is the one yoe’s distro mixing was designed to make ergonomic. For the practical current-state behavior of multi-distro projects on versions where catalog separation is still landing, see module-debian.md known limitations.

How distros plug in (high-level)

Each distro is delivered as a module that the project pulls in:

• module-alpine registers alpine.main and alpine.community synthetic feeds, supplies the toolchain-musl container unit, and ships the upstream signing keys for verifying APKINDEX. Source: module-alpine.md.
• module-debian registers debian.main synthetic feed, supplies the toolchain-glibc container unit, and ships the upstream signing keys for verifying InRelease. Source: module-debian.md.
• module-ubuntu registers ubuntu.main synthetic feed over Ubuntu’s split archive/ports mirrors, supplies its own toolchain-glibc container unit, and ships the Ubuntu archive keyring. It rides Debian’s shared apt/dpkg/glibc backend. Source: module-ubuntu.md.

These modules use the same yoe primitives — module_info(), alpine_feed() / apt_feed(), container(), and a small units/*-enable.star companion layer for services the maintainer wants exposed at boot. The internal Go support — internal/apkindex, internal/feeds/alpine, internal/dpkg, internal/feeds/debian — is parallel by design: each distro has its own format-named parser, its own materializer, its own update-feeds driver. No special-case branching in the resolver beyond the distro field on Unit and the per-distro views in the catalog.

For the resolver-side mechanics — how synthetic modules materialize lazily, how per-distro views resolve cross-distro collisions, how effective distro flows into cache keys — see Catalog and Materialization. For the apk-specific mirror-verbatim mechanism, see Alpine apk Passthrough. For the apk signing trust chain, see apk Signing.

Adding a new distro

The pattern is parallel across distros: a Go-side parser for the upstream format, a feed builtin that registers a synthetic module with a Lookup callback, a materializer that constructs *Unit objects from upstream entries, a project repo emitter for republishing verified-mirror packages, and an image assembler branch that knows how to install packages of the format. The two existing distros are the reference templates:

• Alpine: internal/apkindex/, internal/feeds/alpine/, internal/artifact/apk.go, internal/repo/index.go.
• Debian: internal/dpkg/, internal/feeds/debian/, internal/deb/, internal/repo/deb_emitter.go.

Ubuntu was the cheapest next distro and is already shipped — it’s .deb-format with different upstream keys and URLs, so module-ubuntu mostly shims over apt_feed() with a different keyring, suite, and split archive/ports mirrors (see module-ubuntu.md). Fedora / RHEL would need a new format parser (.rpm, repodata), a new materializer, and a new image-assembler branch (dnf --installroot instead of mmdebstrap); the infrastructure is already factored to make this additive rather than invasive.

module-alpine — wrapping prebuilt Alpine packages

module-alpine is a yoe module that wraps prebuilt Alpine Linux .apk files as yoe units. Where module-core builds packages from upstream source, this module fetches a binary apk from a pinned Alpine release, verifies its integrity, and repacks it as a yoe artifact. The unit’s “build” is just extracting the apk into $DESTDIR.

It declares Alpine’s main and community repos as two alpine_feed(...) calls in MODULE.star, rather than shipping a .star file per package. The feed exposes every package in those repos; units materialize lazily as a project’s runtime closure references them.

The module lives at https://github.com/yoebuild/module-alpine. Open it to browse the checked-in feeds/**/APKINDEX, the alpine_feed declarations in MODULE.star, or to send a PR adding a service-enable companion unit.

Implementation details: how Alpine apks pass through yoe’s pipeline (signature swap, noarch routing, lazy feed materialization, the docker-openrc punt) live in apk-passthrough.md. This doc is the “when to reach for it” rubric; the other is the “how it works end-to-end” reference.

When to reach for it

The policy yoe follows:

1. Yoe builds the easy stuff. Small leaf libraries (zlib, xz, expat, libffi, readline, ncurses, …) and small userland tools (less, htop, vim, procps-ng, iproute2, …) stay in module-core even though Alpine ships them too. Their build is cheap, and keeping them in yoe preserves the option to retarget glibc or a different init system later.
2. module-alpine ships Alpine-native and hard-to-build packages. Alpine-native means musl, apk-tools, alpine-keys, alpine-baselayout — things that only make sense from Alpine. Hard-to-build means packages where Alpine’s expertise (configure flags, security review, codec/license decisions, multi-language coupling) earns its keep: openssl, openssh, curl, eventually python, llvm, qt6-qtwebengine, and similar.
3. Keep building from source anything where the build defines the product. Toolchain, kernel, bootloader, busybox, init scripts, base-files — these are not packages, they are the distribution.

For the broader strategic context — why this rubric exists, where Alpine doesn’t fit (notably edge AI on Jetson), and how yoe expects to handle glibc/systemd targets in the future — see libc-and-init.md.

Alpine release coupling

The Alpine release pinned in MODULE.star and classes/alpine_pkg.star (_ALPINE_RELEASE = "v3.21" at the time of writing) must match the FROM alpine:<release> line in @module-core//containers/toolchain-musl/Dockerfile. All currently point at v3.21.

The coupling is not aesthetic. Three things tie them together:

1. libc ABI. Anything compiled in the toolchain container links against the toolchain’s musl headers and libc. Anything the feed fetches was compiled against a specific Alpine release’s musl. Mix versions and you produce images that compile and link cleanly, then crash on first run when the dynamic linker resolves a symbol whose layout has changed.
2. Signing keys. Every Alpine release ships with a build-host signing key. Prebuilt apks are signed by that key, and apk-tools inside the target image verifies signatures against the keyring baked into the toolchain container at build time. A version skew means the keyring doesn’t recognise the signatures on the packages you’re trying to install.
3. Library co-versioning. Many Alpine packages declare D:so:libfoo.so.N runtime dependencies pinned to specific minor versions. Pulling package-A from one release and package-B from another lands you with conflicting so: constraints that apk will refuse to install.

When bumping the Alpine release, do all three in lockstep across the yoe repo and the module-alpine repo:

1. Update FROM alpine:<release> in modules/module-core/containers/toolchain-musl/Dockerfile in the yoe repo, then rebuild the toolchain container so its baked apk-tools keyring matches.
2. Update _ALPINE_RELEASE in MODULE.star (the branch each alpine_feed pins) and in classes/alpine_pkg.star in the module-alpine repo.
3. Run yoe update-feeds in the module-alpine repo to refresh every checked-in feeds/**/APKINDEX to the new release, then review the diff and commit (see the maintainer playbook below). Every package’s version and integrity hash comes from the refreshed, signature-verified APKINDEX — there are no per-package files to hand-edit.

alpine_feed: declaring a whole repo as one module entry

alpine_feed(...) is a Starlark builtin that turns a checked-in directory of APKINDEX files into a lazily-materialized synthetic module. One alpine_feed call exposes thousands of packages from an upstream Alpine repo (main, community, etc.) with a single declaration. Units materialize on demand as an image’s runtime closure references them, so a project pulling 300 packages from a 60k-entry feed pays for 300 unit allocations, not 60k. This is the normal way packages come out of module-alpine — there are no per-package .star files.

The two declarations in module-alpine/MODULE.star:

module_info(name = "alpine")

_ALPINE_KEYS = [
    "keys/alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub",  # x86_64
    "keys/alpine-devel@lists.alpinelinux.org-616ae350.rsa.pub",  # aarch64
]

alpine_feed(
    name    = "main",                                # synthetic module is alpine.main
    url     = "https://dl-cdn.alpinelinux.org/alpine",
    branch  = "v3.21",                               # Alpine release tag
    section = "main",                                # repo section
    index   = "feeds/main",                          # dir holding <arch>/APKINDEX
    keys    = _ALPINE_KEYS,
)

alpine_feed(
    name    = "community",
    url     = "https://dl-cdn.alpinelinux.org/alpine",
    branch  = "v3.21",
    section = "community",
    index   = "feeds/community",
    keys    = _ALPINE_KEYS,
)

Alpine signs each arch’s APKINDEX with a separate key, so both are listed — update-feeds accepts whichever the upstream mirror serves for a given arch.

The composed module name is <parent>.<feed-name> — alpine.main, alpine.community. The resolver consults synthetic modules after every real module so a from-source override (module-core/units/openssl.star, say) wins against the feed automatically.

Maintainer playbook: yoe update-feeds

When Alpine cuts a new release or ships a security patch, the module-alpine maintainer refreshes the checked-in APKINDEX files with one command. Run it inside the module repo:

cd path/to/module-alpine
yoe update-feeds                    # refresh every alpine_feed for every existing arch
yoe update-feeds --arch x86_64      # restrict to one arch
yoe update-feeds --module-dir ../some/other/module

What it does, per alpine_feed() call, per arch:

1. Fetch <url>/<branch>/<section>/<arch>/APKINDEX.tar.gz over HTTP.
2. Verify the RSA-SHA1 signature against the keys declared in alpine_feed(keys=[...]). Pure-Go verification — never consults /etc/apk/keys/ on the maintainer’s host, so the trust list the module declares is the one that’s actually enforced.
3. Decompress the inner APKINDEX and atomically write it to <module>/<index>/<alpine-arch>/APKINDEX.

yoe update-feeds writes only — it does not stage, commit, or push. The intended workflow is:

yoe update-feeds                # refresh every feed
git diff feeds/                 # spot-check version bumps, new packages, removals
git add feeds/
git commit -m "module-alpine: refresh feeds to Alpine v3.21.2"
git push                        # ships to consumers on next `yoe build`

When the diff looks unexpected

• Lots of new packages or removals: confirm the Alpine release moved (a point release or branch flip).
• A signature failure: either Alpine rotated keys (see below) or the download was tampered. The failing key fingerprint is in the error message; cross-reference against Alpine’s release signing keys before adding a new key.
• HTTP 404: the upstream mirror dropped the branch (very old release) or the section name in alpine_feed is wrong.

Key rotation

When Alpine rotates its signing key (rare, but happens around major release boundaries), commit the new public key alongside the old one and add it to alpine_feed(keys=[...]):

alpine_feed(
    name    = "main",
    # ... other fields ...
    keys    = [
        "keys/alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub",  # old
        "keys/alpine-devel@lists.alpinelinux.org-5e69ca50.rsa.pub",  # new
    ],
)

Both keys verify during the transition period. Once every active Alpine release the module ships has rotated to the new key, drop the old one in a follow-up commit.

Hand-writing an alpine_pkg unit (rare)

Normally you never write a per-package unit — you name an Alpine package in deps and the feed materializes it. Reach for the alpine_pkg class directly only when you need to pin one specific apk the feed doesn’t expose: a revision the live mirror has dropped, a package from a different release, or a unit you want to hand-tune. The class is what the feed materializer produces under the hood, so a hand-written unit and a feed-materialized one behave identically.

load("@module-alpine//classes/alpine_pkg.star", "alpine_pkg")

alpine_pkg(
    name = "sqlite-libs",
    version = "3.48.0-r4",
    license = "blessing",
    description = "SQLite shared library (Alpine v3.21)",
    runtime_deps = ["musl"],
    sha256 = {
        "x86_64": "...",
        "arm64":  "...",
    },
)

The version is Alpine’s full pkgver (e.g., 3.48.0-r4), not just the upstream version. The sha256 dict keys are yoe canonical arches; the class maps them to Alpine arch tokens (arm64 → aarch64).

To find the version + sha256 for a package:

# 1. Find the version in the APKINDEX:
curl -sLO https://dl-cdn.alpinelinux.org/alpine/v3.21/main/x86_64/APKINDEX.tar.gz
tar -xzOf APKINDEX.tar.gz APKINDEX | awk -v RS= '/(^|\n)P:sqlite-libs(\n|$)/ { print; exit }'

# 2. Fetch the apk and sha256 it:
curl -sLO https://dl-cdn.alpinelinux.org/alpine/v3.21/main/x86_64/sqlite-libs-3.48.0-r4.apk
sha256sum sqlite-libs-3.48.0-r4.apk

Repeat for each architecture you target.

How dependencies resolve

Alpine packages declare runtime dependencies via the D: field in APKINDEX, including so:libfoo.so.N and cmd:foo tokens. The two paths handle these differently:

• Feed-materialized units follow the D: closure automatically. As the feed materializes a unit, it walks each dep token and resolves it through a project-wide providers table built from every feed’s APKINDEX — so a community package’s so:libcrypto.so.3 finds main’s openssl-libs without anyone listing it. Only the packages a runtime closure actually reaches are materialized.
• Name shadowing keeps the import surface honest. Because the resolver consults the feed after every real module, a dep that resolves to a bare name yoe already ships from source (busybox, musl, …) binds to that source unit, not the feed’s copy. Auto-following is safe precisely because the things yoe wants to own still win by name.
• Hand-written alpine_pkg units list runtime_deps explicitly. The Starlark class does not read the D: field — when you hand-write a unit (the rare case above), declare the deps you need in runtime_deps and leave out the ones you don’t.

Override with a from-source unit

Because units in module-alpine use the bare names (musl, sqlite-libs, …), any later-priority module — including the project itself — can override them by defining a unit with the same name. See naming-and-resolution.md.

# PROJECT.star
modules = [
    module("https://github.com/yoebuild/module-alpine.git", ref = "main"),  # ships musl, sqlite-libs, …
    module("https://github.com/yoebuild/yoe.git", ref = "main", path = "modules/module-core"),  # source-built kernel, busybox, …
    module(..., path = "modules/my-overrides"),  # last → wins
]

# modules/my-overrides/units/musl.star
unit(name = "musl", source = "https://git.musl-libc.org/git/musl",
     tag = "v1.2.5", tasks = [...])

The override unit produces an apk under the same name. Consumers writing runtime_deps = ["musl"] get the override automatically.

Alpine apk passthrough

How yoe consumes prebuilt Alpine packages through module-alpine, and the sharp edges around metadata, noarch routing, and -dev subpackages. Read this before adding a new feed, debugging a “no such package” install error, or expanding the Alpine surface beyond module-core’s source-built userland.

See Catalog and Materialization for the resolver-side mechanics that back the passthrough path — how alpine_feed registers a synthetic module, when units actually materialize, and what the working set looks like. This page focuses on what passes through and why.

Why this exists

Yoe started by treating every package as something it builds from source — each unit produced a $DESTDIR of files and internal/artifact/apk.go packaged that destdir into a fresh .apk with a yoe-generated PKGINFO and a project-key signature. For module-alpine units (which fetch a prebuilt Alpine apk), the same path applied: extract Alpine’s apk into $DESTDIR, then rebuild a yoe-flavoured apk on top.

That works as long as Alpine’s PKGINFO is just a list of names — but Alpine’s apks carry a lot more:

• replaces = busybox so two packages can both ship a path without apk failing the install.
• provides = so:libcrypto.so.3=3.5.4-r0 so packages that link against a shared library find their dep cleanly.
• provides = cmd:sh=1.37.0-r14 so file-deps like /bin/sh resolve.
• triggers = /usr/lib/firmware* so kernel module updates re-fire hot-plug helpers.
• .pre-install / .post-install / .trigger shell scripts that run at install-time inside a chroot of the rootfs.

Regenerating PKGINFO from a hand-written .star drops every field the generator didn’t enumerate. Most visibly: busybox’s .post-install is where applet symlinks (/bin/sh, /sbin/init, …) get created via /bin/busybox --install -s. Without it the kernel boots and finds no working init.

The current architecture — passthrough — sidesteps all of this by publishing Alpine’s apk verbatim, only swapping the signature.

Passthrough, in two pieces

1. alpine_feed materializes synthetic units lazily

module-alpine/MODULE.star is two alpine_feed(...) calls — one per Alpine repo section (main, community) — and a small units/*-enable.star companion layer for service enablement. No per-package .star files; the ~3,700-entry Alpine main catalog is checked in as one decompressed APKINDEX text file per arch.

# module-alpine/MODULE.star (production shape)
alpine_feed(
    name    = "main",
    url     = "https://dl-cdn.alpinelinux.org/alpine",
    branch  = "v3.21",
    section = "main",
    index   = "feeds/main",                            # in-tree APKINDEX dir
    keys    = ["keys/alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub"],
)

Each alpine_feed call registers a SyntheticModule named <parent>.<feed-name> (alpine.main, alpine.community). The resolver materializes a *Unit on demand the first time a closure walk references the package name — see Catalog and Materialization for the cache + lookup flow. The materialized unit carries PassthroughAPK = "<pkgname>-<pkgver>.apk" and an install task constructed from the upstream APKINDEX entry.

The companion layer is small and hand-written. Today: units/docker-enable.star and units/navidrome-enable.star — units with no build steps that declare services = ["docker"] / ["navidrome"] so the runlevel symlink lands in the package’s data tar. See the “package-driven service enablement” decision in CLAUDE.md for why service enablement is its own unit rather than a flag on the feed.

2. The executor calls RepackAPK instead of CreateAPK

internal/build/executor.go branches on unit.PassthroughAPK:

• Empty → artifact.CreateAPK(destDir, ...) — the original “build a fresh apk” path. Source-built module-core units take this path.
• Set → artifact.RepackAPK(srcAPK, ...) — splits Alpine’s apk into its three concatenated gzip streams, drops the Alpine signature, re-signs the control stream (PKGINFO + install scripts) with the project key, and concatenates [new_sig, control, data] into the published apk.

RepackAPK does not rewrite anything inside the control or data segments. Alpine’s PKGINFO, replaces, provides, triggers, install scripts, file checksums — all unchanged.

The destdir extraction (the materialized unit’s install task) is still useful: yoe’s per-unit sysroots are built by hardlinking each dep’s destdir into <unit>/sysroot/, so a unit that gcc -lfoos against a module-alpine library finds headers and shared objects there. Image-time apk add reads the published apk (passthrough) and never looks at the destdir.

Legacy: alpine_pkg class

classes/alpine_pkg.star is still in the module but no production unit uses it. It was the pre-feed entry point — one hand-written .star file per package, calling alpine_pkg(...) with hashes baked in. The class is preserved for one-off external uses (a downstream module that wants to wrap a single upstream apk without standing up a whole feed); for the in-tree module-alpine, feeds replaced it. If you’re tempted to add a per-package .star calling alpine_pkg, ask first whether the feed should have the package already — adding a hand-written wrapper for a name the feed already exposes will produce a conflicting registration.

Two metadata systems, two purposes

After passthrough, every unit has metadata in two places:

• The materialized *Unit (Name, Version, RuntimeDeps, Provides, Replaces, Distro, …) drives yoe’s resolver: build-order DAG, runtime-closure walk for image artifacts, virtual-package routing (linux → linux-rpi4), TUI USED-BY/PULLS-IN trees, the per-image distro visibility filter (an alpine image’s closure doesn’t see debian-tagged units and vice versa). For feed-materialized units this view is constructed from the APKINDEX entry at lookup time (apkindex.MaterializeUnit in internal/apkindex/); for source-built and companion units, it’s whatever the .star file declared.
• Upstream PKGINFO (inside the apk’s control segment) drives apk-tools at install time on the target: real shared-library deps, file-dep resolution, install-script execution, conflict checking.

These overlap conceptually but serve different stages. yoe’s resolver doesn’t see so:libcrypto.so.3 because it’s not in the materialized unit’s runtime_deps; apk-tools doesn’t see yoe’s virtual linux because that’s a yoe concept, not an apk one.

The materialized unit therefore should mirror enough of upstream’s metadata that yoe’s resolver makes the same decisions apk-tools would — without duplicating every field. For feed-materialized units this happens at lookup time: MaterializeUnit reads the APKINDEX entry’s dep list, runs each token through the project-wide provides table (cross-feed siblings included via multiFeedProviders), and produces a *Unit whose RuntimeDeps name yoe units rather than apk virtuals. Hand-written companion units like docker-enable set yoe-specific overrides (services = ["docker"]) that the feed couldn’t infer from APKINDEX alone.

noarch routing — the four-part fix

apk-tools is unforgiving here: it constructs fetch URLs from PKGINFO’s arch field, not from where it found the index entry. So a noarch apk has to physically live at <repo>/noarch/<file> — putting it under <repo>/<arch>/ and listing it in <arch>/APKINDEX doesn’t make apk look there. Conversely, apk’s solver only reads one arch’s APKINDEX per repository invocation, so noarch entries also have to appear in the per-arch index.

The full design now in tree:

1. executor.go routes noarch passthrough apks to <repo>/noarch/. The arch comes from upstream PKGINFO via artifact.ReadAPKArch, not from the build arch.
2. GenerateIndex scans the sibling <repo>/noarch/ tree when building a per-arch index, so each arch’s APKINDEX advertises every noarch package as A:noarch. apk’s solver finds the entry from any per-arch index.
3. Publish regenerates every per-arch APKINDEX after a noarch publish. Without this, the per-arch indexes go stale on every noarch unit rebuild.
4. cacheValid looks under <repo>/noarch/ when the apk isn’t in the per-arch dir, so noarch passthrough units don’t rebuild on every yoe build invocation.

Symptoms when one of these halves is missing:

• package mentioned in index not found — usually file in arch dir but PKGINFO says noarch (apk fetches from <base>/noarch/, 404s).
• <name> (no such package): required by world[<name>] — file in noarch dir but per-arch APKINDEX doesn’t reference it.
• noarch unit shows [building] every run despite the published apk being unchanged — cacheValid was checking the wrong directory.

Auto-emitted so: provides

For yoe-source-built units, internal/artifact/apk.go walks $DESTDIR, opens every regular file with Go’s debug/elf, reads DT_SONAME, and emits one provides = so:<soname>=<ver>-r<rel> line per shared library. This matches Alpine’s abuild convention and lets Alpine prebuilts that declare depend = so:libcrypto.so.3 resolve cleanly against a yoe-built openssl.

The mirror — auto-emit depend = so:<soname> from DT_NEEDED — is on the roadmap (see docs/roadmap.md’s “Auto-depend from ELF DT_NEEDED”).

Auto-versioned provides

Explicit virtuals listed in a unit’s provides = [...] field are also stamped with =<ver>-r<rel> on emit. So:

unit(name = "openssl", version = "3.4.1", provides = ["libssl3", "libcrypto3"])

emits provides = libssl3=3.4.1-r0 and provides = libcrypto3=3.4.1-r0 in the package’s PKGINFO. Without the version, apk treats the provide as unversioned and refuses to use it to satisfy consumer constraints like depend = libssl3>=3.3.0 (which is what Alpine’s prebuilt python3 ships). If the entry already carries a constraint (=, <, >, ~), it’s emitted verbatim — useful when a unit needs to claim a specific older version’s API contract.

Worked example: why we couldn’t use Alpine’s docker-openrc

Tested end-to-end during the OpenRC switch. Documenting because the same shape of problem will recur with any Alpine package whose dep tree pokes deep enough into module-core’s source-built userland.

The goal: wire dockerd into the OpenRC default runlevel using Alpine’s docker-openrc package (which ships /etc/init.d/docker and a /etc/conf.d/docker config template Alpine maintains).

The dep tree (drawn out from upstream PKGINFOs):

docker-openrc
└── log_proxy
    ├── musl
    └── glib
        ├── pcre2
        ├── libffi
        ├── libintl
        └── libmount
            └── libblkid

log_proxy is a tiny Alpine utility for capturing daemon stdout/stderr to syslog. Glib is needed because log_proxy uses GIO. libmount/libblkid are in glib’s transitive deps because GIO has mount-table integration.

The conflict. Yoe’s source-built util-linux (in module-core) ships libmount.so.1 and libblkid.so.1 directly — it’s a monolithic build. Alpine splits util-linux: libmount and libblkid are separate apks. When apk’s solver tries to install both yoe’s util-linux and Alpine’s libmount/libblkid, it fails because both packages own the same library paths.

First attempt: prefer_modules = {"alpine": {"util-linux": "alpine.main"}}. Forces the Alpine prebuilt instead of yoe’s source-built version (pin syntax names the synthetic module, not the parent — alpine.main rather than alpine). Resolves the library conflict. But Alpine’s util-linux apk is a meta package — it ships nothing on disk; the actual binaries live in util-linux-misc, util-linux-login, the libraries in libuuid/libmount/libblkid, and the headers + unversioned .so symlinks needed at compile time live in util-linux-dev.

After pulling subpackages in via runtime_deps, the next layer: e2fsprogs (yoe-source-built) needs libuuid headers + the unversioned libuuid.so symlink to compile. Those live in util-linux-dev. Adding that pulls libfdisk, liblastlog2, libsmartcols, sqlite-dev — none of which have yoe units. Each one in turn pulls more.

The yak shave. To fully consume Alpine’s util-linux-dev, we’d need units for at least a dozen Alpine subpackages, plus their -dev counterparts, plus careful conflict bookkeeping where yoe-source-built packages still ship competing files. That’s days of work and a much larger Alpine surface to maintain.

The trade. A 30-line yoe-side OpenRC service script (in modules/module-core/units/net/docker-init/) gives us the same boot behaviour with no transitive deps. We give up Alpine’s /etc/conf.d/docker config template and the log_proxy stdout-capture story; for a yoe image those costs are minor.

The lesson generalizes: Alpine’s -dev subpackage convention is fundamentally at odds with yoe’s monolithic source-built libraries. Picking off Alpine packages one at a time is fine; widening the surface to consume Alpine’s whole library-development ecosystem is a significant architecture decision, not a one-off fix.

What’s still rough

Items where the architecture is “works for now” but obviously incomplete.

• No support for -dev packages. All the architectural reasons in the docker-openrc example. Until yoe has a story for splitting headers out of source-built libraries (or for systematically wrapping Alpine’s -dev ecosystem), pulling new Alpine packages in is a manual review for “does this transitively need any -dev subpackage.”

• No triggers execution. Alpine apks ship .trigger scripts that fire on path changes (e.g. udev re-runs hot-plug rules when a module is added). The passthrough copy includes them, but yoe’s image assembly doesn’t currently invoke them in any consistent way. apk’s on-target trigger machinery handles them after first boot, but image-build-time triggers (-t in apk) don’t happen.

• Auto-depend from DT_NEEDED. Counterpart to the auto-so:-provides scan that already runs. Would catch the class of bug where a unit’s RuntimeDeps silently misses a transitive shared-lib dependency. Roadmap item; design in docs/roadmap.md.

• prefer_modules with subpackage expansion. When you push a monolithic source-built unit (util-linux) to Alpine’s split form, yoe’s resolver follows runtime_deps from the meta package — but build-time deps (unit.Deps) on util-linux don’t pull subpackage destdirs into the build sysroot. Workaround: declare downstream units’ build deps on the subpackages directly. Long-term the resolver should walk runtime_deps for build-deps too, or unit.Deps should accept the same expansion.

• RepackAPK re-sign vs upstream-keys passthrough. The current path strips Alpine’s signature and re-signs with the project key. An alternate design — keep Alpine’s keys + signature, ship Alpine’s keyring on-target as an additional trust anchor — is captured in docs/specs/2026-05-18-mirror-alpine-keep-keys.md (spec only, not implemented). The trade-off: re-signing means the on-target trust list stays “one key per project” but every passthrough requires cryptographic work; keeping upstream keys removes the re-sign cost but multiplies on-target trust anchors (one per distro the project consumes from). No decision yet on which way to land.

Reference

• internal/artifact/apk.go — CreateAPK, RepackAPK, ReadAPKArch, scanSONAMEs.
• internal/feeds/alpine/builtin.go — alpine_feed builtin, SyntheticModule registration, populateBuildFields (sets PassthroughAPK, Source URL, Distro = "alpine", install task with control-file exclusions). The pre-feed wrapper class lives at testdata/.../module-alpine/classes/alpine_pkg.star for legacy / external one-off use.
• internal/apkindex/materialize.go — MaterializeUnit: APKINDEX entry → *Unit. Wraps multiFeedProviders for cross-feed dep resolution.
• internal/build/executor.go — passthrough branch in the build loop; cacheValid for the noarch lookup.
• internal/repo/local.go — Publish (with cross-arch reindex on noarch) and index.go’s GenerateIndex (sibling-noarch scan).
• internal/feeds/alpine/update.go — yoe update-feeds driver: fetches upstream APKINDEX, verifies RSA-SHA1 against declared keys, atomically writes to the in-tree feed index.
• docs/catalog.md — resolver-side mechanics (synthetic modules, lazy materialization, working-set sizes, invariants).
• docs/module-alpine.md — when to reach for module-alpine vs module-core (rubric, not architecture); maintainer playbook for yoe update-feeds.

apk Signing

yoe signs every .apk and the APKINDEX.tar.gz at build time with an RSA-PKCS#1 v1.5 SHA-1 signature, matching what apk-tools 2.x verifies. Booted systems include the matching public key under /etc/apk/keys/, so on-target apk add, apk upgrade, and image-time package installation all run without --allow-untrusted.

What you need to know

• yoe auto-generates a 2048-bit RSA keypair on first build and stores it at ~/.config/yoe/keys/<project>.rsa (private) and ~/.config/yoe/keys/<project>.rsa.pub (public).
• The matching public key is published into your local repo under <projectDir>/repo/<project>/keys/<project>.rsa.pub and into the rootfs at /etc/apk/keys/<project>.rsa.pub (via base-files).
• A different signing key per project is the default. Two projects with the same name field share keys; use unique project names if that isn’t what you want.

Inspecting the current key

$ yoe key info
Signing key: /home/you/.config/yoe/keys/myproj.rsa
Public key:  /home/you/.config/yoe/keys/myproj.rsa.pub
Key name:    myproj.rsa.pub
Fingerprint: 1f3a:c2:e0:9d:42:8c:b6...

Use the fingerprint to confirm two systems are talking about the same key without printing the full public key.

Generating a key explicitly

yoe key generate is a no-op when the configured key already exists; if not, it creates a fresh 2048-bit RSA pair at the configured path. The build pipeline does the same auto-generation lazily, so most users never need to run this.

$ yoe key generate
Signing key: /home/you/.config/yoe/keys/myproj.rsa
Public key:  /home/you/.config/yoe/keys/myproj.rsa.pub
Key name:    myproj.rsa.pub
Fingerprint: 1f3a:c2:e0:9d:42:8c:b6...

Pinning a key path explicitly

Override the default by setting signing_key on project() in PROJECT.star:

project(
    name = "myproj",
    version = "0.1.0",
    signing_key = "/secrets/myproj.rsa",
    ...
)

The configured path is treated the same way as the default — yoe loads it if it exists, generates a new keypair there if it doesn’t.

Key rotation

When you replace a key, every existing rootfs becomes unable to verify new packages until the new public key is shipped. The recommended flow is:

1. Generate the new key (yoe key generate after deleting the old ~/.config/yoe/keys/<project>.rsa.pub, or by setting signing_key to a fresh path).
2. Run yoe build --force so every cached apk gets re-signed with the new key. The build cache is content-addressed and doesn’t include the signing key in its hash, so a fresh build after a key swap will otherwise replay cached apks signed with the old key.
3. Build a new image so base-files carries the new public key.
4. Flash or upgrade devices with the new image.
5. Once every device is rotated, retire the old key.

Because both keys can coexist under /etc/apk/keys/ on-target, you can also stage a rollover: drop both .rsa.pub files into the rootfs (e.g., via an overlay), let devices upgrade onto the new key over a period, and then strip the old one in a later release.

What’s signed and what isn’t

Signed:

• Every .apk produced by yoe build. The signature covers the SHA-1 of the gzipped control stream; data integrity flows through the PKGINFO datahash field that the control stream carries.
• The per-arch APKINDEX.tar.gz regenerated on every publish.

Not signed:

• Bootstrap apks emitted by yoe bootstrap. These exist only inside the build container and are never installed on a target.
• Source archives, docker images, intermediate build artifacts. Only the final .apk and the index are signed.

module-debian — wrapping prebuilt Debian packages

module-debian is a yoe module that wraps prebuilt Debian .deb files as yoe units, mirroring the role module-alpine plays for Alpine. Where module-core builds packages from upstream source, units in this module fetch a binary .deb from a pinned Debian release, verify its SHA256 against the upstream-signed Packages catalog, and republish it through yoe’s project repo. The unit’s “build” is just extracting the deb’s data.tar into $DESTDIR.

The module lives at https://github.com/yoebuild/module-debian. Open it to browse the bootstrap keyring, the in-tree Packages snapshots, or to send a PR adding a new feed/component.

Implementation details: how Debian debs pass through yoe’s pipeline (apt_feed, the InRelease verify path, mmdebstrap-driven image assembly, the project repo emitter) live in docs/specs/2026-05-25-module-debian.md and the matching plan under docs/plans/. This doc is the “when to reach for it” rubric.

When to reach for it

The same policy yoe follows for Alpine applies to Debian. The choice between the two is whether the image targets glibc (Debian) or musl (Alpine); the rest of the rubric — yoe builds the small stuff, the distro module ships the hard-to-build complexity — is identical.

1. Yoe builds the easy stuff in module-core regardless of distro target. The same zlib, xz, expat, … source units compile against either toolchain via the container = "toolchain" virtual reference.
2. module-debian ships Debian-native and hard-to-build packages. Debian-native means dpkg, apt, debianutils, base-files, libc6/libc-bin. Hard-to-build means packages where Debian’s expertise earns its keep: openssl, openssh-server, curl, python3, clang, and the entire linux-image-* lineage when running stock kernels makes sense.
3. Keep building from source anything where the build defines the product. Toolchain, kernel (when custom), bootloader, init scripts, board-specific firmware — these are not packages, they are the distribution.

Debian release coupling

The Debian suite pinned in MODULE.star (_DEBIAN_SUITE = "bookworm" at the time of writing) must match the FROM debian:<release> line in @module-debian//containers/toolchain-debian-13/Dockerfile. Both currently point at bookworm.

The coupling matters for three reasons:

• glibc ABI. Source units that link against headers/libs from the toolchain container produce binaries that need a matching glibc on the target rootfs. Mixing bookworm-slim headers with trixie runtime libs is a silent ABI mismatch.
• Signing keys. Each Debian release has its own archive signing key, and the in-tree keys/debian-archive-keyring.gpg is what yoe update-feeds verifies against. Bumping the suite without rotating the bootstrap keyring produces an untrusted key error at first update-feeds after the bump.
• Cache invalidation. Source units cache by hash; switching the toolchain container’s FROM tag rolls every hash through it. Plan the bump for a full rebuild cycle.

Trust chain

sources.list.d/<project>.sources
  ├── Signed-By: /etc/apt/keyrings/<project>.gpg
  └── URIs: https://<host>/<project>/debian

apt fetch InRelease
  → gpg verify against /etc/apt/keyrings/<project>.gpg
  → REJECT if Valid-Until expired
apt fetch Packages
  → SHA256 verified against InRelease
apt fetch <pkg>.deb
  → SHA256 verified against Packages
  → install + run maintainer scripts via dpkg

The project repo is regenerated every time a unit changes; the InRelease is re-signed each emit. Valid-Until defaults to 30 days, configurable per-project — short enough to bound rollback windows, long enough for disconnected development. Embedded fleets with strict security cadence may want a shorter window; offline-tolerant fleets may want longer. The trade-off is fleet-specific; pick a value that matches your update cadence and ability to push fresh InRelease files when needed.

Repository URLs must be HTTPS. yoe validates this at project evaluation time; an http:// URL in a apt_feed(...) call fails fast with a clear error. Plaintext mirrors expose the trust chain to MITM injection — the bootstrap keyring’s job is to verify what the mirror says, but the mirror can’t be trusted to deliver bytes faithfully without TLS.

Maintainer playbook

The flow mirrors module-alpine’s. Inside a checked-out module-debian:

1. Refresh in-tree Packages snapshots. Run yoe update-feeds inside the module directory. The command peeks MODULE.star for every apt_feed(...) call, fetches each declared suite’s InRelease from the pinned mirror, verifies it against keys/debian-archive-keyring.gpg with Valid-Until enforcement, fetches per-arch Packages.gz, decompresses, and atomically writes the result into feeds/<component>/<arch>/Packages. Writes only — review with git diff feeds/ and commit when ready.
2. Push upstream. yoe’s external-module workflow (CLAUDE.md) fetches a pinned ref on every build, so the new Packages snapshot needs to land on the canonical remote before the next consumer’s yoe build will see it.
3. Key rotation. When Debian rotates a release signing key — typically when a new stable ships — yoe update-feeds will refuse the new key until its fingerprint is in keys/allowed-fingerprints. Verify the fingerprint against https://ftp-master.debian.org/keys.html, then either edit allowed-fingerprints directly or use yoe update-feeds --allow-key-update=<fpr> to append it in one step.

Declaring a feed

In MODULE.star:

apt_feed(
    name = "main",
    url = "https://deb.debian.org/debian",
    suite = "bookworm",
    component = "main",
    arches = ["amd64", "arm64"],
    index = "feeds/main",
    keyring = "keys/debian-archive-keyring.gpg",
)

Each call registers a SyntheticModule named <parent>.<component> (e.g. debian.main, debian.contrib, debian.non-free) — matching alpine’s alpine.main / alpine.community shape. The suite kwarg configures which on-disk Packages file is parsed but does not appear in the module name; one Debian suite per project, enforced at evaluation, so the suite has no disambiguating role at the module level. Units materialize lazily as the runtime closure references them, so a project pulling in openssh-server parses about a thousand entries on the way to its closure — not the full 60k-entry catalog. See Catalog and Materialization for the resolver-side mechanics (how synthetic modules differ from real modules, lazy-Lookup contract, and the working-set sizes the resolver operates at).

Multiple feeds compose: declaring debian.main plus security and updates overlays (each with its own apt_feed(...) call, same suite, different component or apt-overlay URL) gives apt-equivalent priority resolution on the project side. The closure walker consults each in declaration order; first match wins.

Verifying a Debian image

End-to-end verification — does the image actually boot? — runs against the debian-base-image fixture under testdata/e2e-project/. The fixture targets the smallest closure that boots in QEMU and accepts SSH: kernel, init, networking, openssh-server.

prefer_modules is scoped per consuming distro, so the alpine pins in the e2e-project PROJECT.star (xz, zstd, util-linux, curl → alpine.main) don’t bleed into the debian closure: a debian image build resolves those names through their distro-neutral module-core equivalents. The fixture builds out of the box on a mixed-distro project.

cd testdata/e2e-project

# 1. Refresh the in-tree Packages files if upstream has moved since the
#    cached snapshot was taken. Safe to skip on a clean check-out.
yoe update-feeds

# 2. Build the image. This pulls every artifact's .deb from the cached
#    bookworm feed, builds toolchain-debian-13 on first run, installs the
#    closure into the rootfs with `mmdebstrap` (apt + dpkg in one pass,
#    running maintainer scripts), stages the project APT keyring + deb822
#    sources file, and writes a bootable disk image. Expect ~5–10 min
#    on first run (toolchain build); subsequent runs hit the cache.
yoe build debian-base-image

# 3. Boot under QEMU. The fixture's machine config forwards host port
#    2222 → guest port 22 so SSH lands without extra flags.
yoe run debian-base-image

# 4. From another terminal, connect to the running image.
ssh -p 2222 root@localhost

If apt-get update and apt-get install work from inside the booted image against the project’s own repo (https://<feed-host>/<project>/debian), the verification has fully closed: project repo emission, on-device APT trust staging, and the iterate–deploy–update loop all work end-to-end.

When the build fails or the image won’t boot, the failure usually surfaces in one of these places:

• mmdebstrap inside the toolchain container — postinst error in the configure log; check whether the package needs network access (see Known limitations).
• Bootloader install — extlinux / syslinux-common must be present in the toolchain-debian-13 Dockerfile so _install_syslinux_debian can find /usr/lib/SYSLINUX/mbr.bin.
• Init startup — kernel and systemd-sysv pull in /sbin/init transitively; if the kernel boots but init doesn’t run, check that init (the symlink package) is in the closure.
• SSH not running on first boot — Debian’s openssh-server package enables itself via systemd preset; verify with systemctl status ssh on the device console.

Known limitations

Three structural properties of the debian backend that users will encounter regardless of yoe version. None is a bug or a transitional gap — all are deliberate trade-offs that the architecture chose, and changing any one is a substantial follow-up rather than routine work.

• mmdebstrap --variant=custom installs the resolved closure, not Debian’s base system. To keep images content-addressed and minimal, yoe tells mmdebstrap to install exactly the closure yoe resolved (--variant=custom) rather than the implicit Essential / Priority:required base that debootstrap and the stock mmdebstrap variants pull in. An image therefore contains only what its closure names plus apt’s hard-dependency expansion — there is no rescue userland, no Priority: standard set, unless an image lists it. Three consequences follow. All are handled automatically during assembly, but they are visible in the log and shape what an image must declare:

  • The Essential / required userland is seeded explicitly. Debian maintainer scripts assume sed, grep, awk, find, gzip, login, and the rest of the Priority:required toolset are present — libc6’s own preinst calls sed. Custom variant pulls none of it implicitly, so the image class seeds a fixed Essential + required baseline into every Debian image’s closure. A package whose maintainer script reaches for a tool outside that baseline must add the tool to the image.
  • usr-merge is established before extraction. Custom variant skips the /bin→/usr/bin merge the normal variants set up. A setup-hook creates the merged-usr symlinks against the empty target before any package unpacks; without it the usrmerge package’s post-hoc conversion fails inside the build chroot.
  • Configuration is one unordered dpkg --install --force-depends pass. The whole closure unpacks and then configures, instead of the staged configure-essentials-first bootstrap debootstrap performs. The assembly log shows benign ignoring pre-dependency problem warnings (e.g. systemd Pre-Depends on a libc6 that is unpacked but not yet configured) — dpkg proceeds and the configure pass resolves them. A tool provided through update-alternatives (notably awk via mawk) can be needed before its provider’s postinst registers the link, so the image class pre-stages those links. A final dpkg-query audit fails the build loudly if any package is left half-configured, so a genuinely broken closure never ships as a subtly incomplete image.

• Some upstream .deb postinsts assume network access. yoe runs mmdebstrap under --network=none for hash stability and reproducibility — a configure pass that reaches out to a DNS resolver, a metadata server, or a license-prompt download produces different output depending on what’s reachable when, which would break the content-addressed cache. Packages whose postinsts do this (cloud-init provisioning, telemetry agents, license-prompt downloaders, a small set of enterprise-software installers) fail loudly during image assembly. The narrow set this affects isn’t appropriate for embedded images anyway; replace with a from-source module-core unit if equivalent functionality is needed, or carry the package and provide the configuration it would have fetched via the project rootfs overlay.

• One Debian suite per project, enforced at evaluation. Every apt_feed(...) call in a project must agree on its suite kwarg; the resolver errors at load time if it sees bookworm and trixie declared in the same project. The constraint exists because the toolchain container (@module-debian//containers/toolchain-debian-13) pins one Debian release, and source units built against that toolchain’s headers/libs can’t safely mix with prebuilt packages from a different release’s libc. Multi-suite support would require a suite axis in the toolchain cache key and parallel toolchain containers per suite — feasible but out of scope today. For most projects this is the correct constraint: a fleet runs one Debian release at a time.

module-ubuntu — wrapping prebuilt Ubuntu packages

module-ubuntu wraps prebuilt Ubuntu .deb files as yoe units, mirroring the role module-debian plays for Debian and module-alpine plays for Alpine. A unit fetches a binary .deb from a pinned Ubuntu release, verifies its SHA256 against the upstream-signed Packages catalog, and republishes it through yoe’s project repo. The unit’s “build” is just extracting the deb’s data.tar into $DESTDIR.

The module lives at https://github.com/yoebuild/module-ubuntu. Open it to browse the bootstrap keyring, the in-tree Packages snapshots, or to send a PR adding a new feed/component.

Ubuntu shares Debian’s apt/dpkg/glibc machinery, so this module is thin: it declares feeds with the same apt_feed() builtin module-debian uses, ships an Ubuntu/glibc build toolchain, and rides the shared mmdebstrap rootfs assembly, .deb packaging, and on-device apt that yoe applies to the whole apt family. Read module-debian for the apt-family mechanics that aren’t repeated here; this page covers what is Ubuntu-specific.

When to reach for it

The same “yoe builds the small stuff, the distro module ships the hard-to-build complexity” rubric from module-debian applies. The only axis that picks Ubuntu over Debian is the target: choose module-ubuntu when an image must match Ubuntu’s userland, ABI, or vendor BSP expectations. Source units in module-core compile against either glibc toolchain through the container = "toolchain" virtual reference, so most of a closure is shared regardless of which apt distro the image targets.

Ubuntu is its own distro

apt_feed(distro = "ubuntu", ...) tags every materialized unit with Distro = "ubuntu", and the images set distro = "ubuntu". That makes Ubuntu a first-class distro in yoe’s resolver — an Ubuntu image’s closure sees only Ubuntu-tagged units, so a single project can declare both module-debian and module-ubuntu and the two never collide. Under the hood Ubuntu rides the shared apt/dpkg/glibc backend; only the feed identity, suite, and mirror differ.

Ubuntu release coupling

The suite pinned in MODULE.star (_UBUNTU_SUITE, tracking Resolute Raccoon / 26.04 LTS at the time of writing) must match the FROM ubuntu:<release> line in containers/toolchain-ubuntu-26.04/Dockerfile. The same three couplings Debian documents apply: the glibc ABI between toolchain headers and target runtime libs, the per-release archive signing key in keys/ubuntu-archive-keyring.gpg, and the full cache invalidation that a suite bump rolls through every source-unit hash. Plan a suite bump for a rebuild cycle.

The Ubuntu and Debian glibc toolchains are not interchangeable. apt is not forward-compatible across suites, so Debian-trixie’s apt crashes when it reads Ubuntu-resolute’s repository metadata — an Ubuntu rootfs must be assembled by the Ubuntu toolchain, and vice versa. Because the container image tag is yoe/<unit-name>:<version>-<arch>, each toolchain carries its release in its name (toolchain-ubuntu-26.04, Debian’s toolchain-debian-13) so the two never share a tag and overwrite each other’s image.

Split mirrors (amd64 + arm64)

Ubuntu serves its architectures from two hosts: amd64/i386 live on http://archive.ubuntu.com/ubuntu, while arm64 and the other ports arches live on http://ports.ubuntu.com/ubuntu-ports. A single apt_feed spans both via the optional arch_urls map, which overrides the base url per architecture — used both when yoe update-feeds fetches each arch’s Packages and when the build downloads each .deb. The InRelease is fetched once from url for signature verification; both mirrors ship an InRelease signed by the same Ubuntu archive key. Debian’s single mirror serves every arch and needs no such override.

Networking

Ubuntu images use NetworkManager as the connection manager, the same choice the Debian images make. It self-enables via its postinst, integrates with the systemd-resolved already in the image for DNS, and is the foundation for adding wifi and cellular to a device image later.

Ubuntu needs one extra piece Debian does not. Ubuntu’s network-manager package ships /usr/lib/NetworkManager/conf.d/10-globally-managed-devices.conf, which restricts NetworkManager to wifi and cellular and delegates wired ethernet to netplan. yoe images carry no netplan configuration, so out of the box the wired NIC is brought up by nothing — NetworkManager sees the device and then ignores it (nmcli device status shows it unmanaged). To restore the zero-config wired-DHCP behavior Debian has by default, the Ubuntu images include the nm-manage-ethernet unit. It lays down a higher-priority drop-in at /etc/NetworkManager/conf.d/15-yoe-manage-ethernet.conf that re-includes ethernet in NetworkManager’s managed set, so the wired NIC auto-DHCPs with no connection profile.

If a custom Ubuntu image lists network-manager but has no connectivity, confirm nm-manage-ethernet is also in its closure. On the device console, nmcli device status should show the ethernet device connected (not unmanaged), and ip addr should show a DHCP lease.

Verifying an Ubuntu image

End-to-end verification mirrors the Debian flow in module-debian — build the ubuntu-base-image (or ubuntu-dev-image) fixture under testdata/e2e-project/, boot it under QEMU, and confirm SSH lands over the forwarded port. The image is reachable on first boot with no connection profile because nm-manage-ethernet brings the wired NIC up automatically.

Layout

MODULE.star                # apt_feed(distro="ubuntu", ...) declaration
feeds/main/<arch>/Packages # checked-in catalog snapshots (archive + ports)
keys/                      # bootstrap keyring + fingerprint allow-list
containers/toolchain-ubuntu-26.04  # Ubuntu/glibc build toolchain (provides "toolchain")
classes/kernel.star        # ubuntu_kernel() -> linux-image-generic
images/                    # base-image, ssh-image, dev-image

Architecture

This page introduces yoe’s core concepts and traces a unit through its lifecycle — build, packaging, deployment, and development. Use it as a map before diving into the reference docs.

Core concepts

The four nouns at the heart of yoe: project, module, unit, and package.

Project

The project is the top of the tree. It is a directory containing a PROJECT.star file, which declares:

• which modules the project uses (and at what Git ref),
• the machine to build for,
• any prefer_modules resolution pins,
• project-local units under units/ and machines under machines/.

A project is what you check into version control for a specific product. It is what yoe init scaffolds and what the yoe CLI operates on from your working directory.

See Unit & Configuration Format for the full PROJECT.star surface and Naming and Resolution for how module references and prefer-rules work.

Modules

A module is a Git repository (or a subdirectory of one) that provides reusable building blocks: classes, units, machine definitions, container definitions, and image definitions. Projects compose modules to get the pieces they need.

Typical modules:

• module-core — base classes (autotools, cmake, go), common units (busybox, openssl, openssh, kernel), and reference images.
• module-bsp and module-jetson — BSP modules with machine definitions (Raspberry Pi 4/5, BeaglePlay, NVIDIA Jetson) and the matching kernel / bootloader / firmware units.
• module-alpine — passthrough access to upstream Alpine .apk packages.
• module-debian — passthrough access to upstream Debian .deb packages (experimental; see module-debian.md for current status and limitations).

Modules are referenced by URL and Git ref in PROJECT.star. The [yoe] CLI clones them into the project’s cache. See Naming and Resolution for module naming, directory structure, and load-path semantics.

Units

A unit is a .star file describing how to build a single piece of software. Units live in a module’s units/ directory (or the project’s own units/), and they call into a class (autotools, cmake, go, …) that encodes the build pattern.

A unit declares its source, version, dependencies, and any build-time configuration. The [yoe] build system resolves the DAG of units, runs each in its own sandboxed build environment, and installs results into the build sysroot so downstream units can find them.

Units are inputs to the build system: developer-edited, version-controlled, and a CI concern. See Unit & Configuration Format for the unit, class, and machine API.

Packages

A package is the build output — an .apk for alpine-targeted units or a .deb for debian-targeted units. Packages are content-addressed, cached, signed, and published to a repository. They are consumed by apk (alpine images) or dpkg / apt (debian images) at image-assembly time and by the on-device package manager for over-the-air updates.

One unit produces one package today — .apk or .deb is chosen per the consuming image’s distro, not per unit. A small set of subpackage splits (-dev, -dbg) is planned for cases where the runtime image should not carry headers or debug info. See metadata-format.md#units-vs-packages for the contract between units and packages, apk Signing for the alpine pipeline, module-debian.md for the debian pipeline, and Feed Server for how packages get published and deployed.

How they fit together

The build flow is unit → build → .apk → repository → image / device. The conceptual flow is project references modules, modules provide units, units produce packages, packages assemble into images:

For an explanation of why this split exists — versus Yocto’s recipe/layer model — see Comparisons. For the language used to express units and configuration, see Build & Configuration Languages.

Build

Building a unit means turning declared inputs into a packaged artifact. Three angles matter: the environment the build runs in, the inputs that feed it, and how an abstract name like linux finds a concrete provider.

The build environment

Builds run on the host through a tiered environment. The host provides only yoe and a container runtime; everything else is nested inside the container that yoe spawns:

Each unit builds inside its own bwrap sandbox with only its declared deps visible. See Build Environment for the tier-by-tier details, the bootstrap process, and the rationale behind bwrap-over-Docker for per-unit isolation.

Dependency sources

A unit pulls inputs from four independent sources, each managed by the right tool for the job:

Host tools (compilers, language runtimes) come from Docker containers; library deps from the apk sysroot built up by other yoe units; distro packages (full libraries, runtime services, applications) come from prebuilt upstream apks via module-alpine; and language-native deps (Go modules, Cargo crates, pip wheels) are handled by each language’s own package manager inside the container. See Build Dependencies and Caching for why this split exists and how it interacts with the build cache, and Alpine apk Passthrough for the prebuilt-apk path.

Abstract-name resolution

An image’s artifacts list and a unit’s runtime_deps/build_deps can reference abstract names like linux or init. The resolver matches each abstract name against a registry of provides claims from every unit across every module, with module declaration order in project() deciding ties:

This is what makes images machine- and project-portable: an image asks for linux, and a Raspberry Pi machine config points linux at linux-rpi4 while a Jetson machine points it at a Tegra kernel — same image, different hardware. Concrete names that match directly skip the registry.

For multi-distro projects, resolution is also distro-aware: a unit tagged for one distro is invisible to images of another, and virtuals like toolchain route to the matching toolchain unit (toolchain-musl for alpine, toolchain-debian-13 for debian, toolchain-ubuntu-26.04 for ubuntu) via the same provides mechanism. See Naming and Resolution for collision rules, name shadowing, and the replaces mechanism, and Catalog and Materialization for the in-memory data structures that hold units while a project is being evaluated, how synthetic feed units materialize lazily, the distro visibility filter, and the working-set sizes the resolver operates at.

Packaging

Every artifact published by yoe — whether built from source or repacked from a distro — flows through one of two parallel format pipelines, both signed by the project key. The pipelines mirror each other: same content-addressed cache, same source paths, same yoe build invocation; only the on-disk format and signing mechanism differ to match the consuming image’s distro.

• .apk pipeline — used by alpine images. Per-.apk RSA-SHA1 signature plus a signed APKINDEX.tar.gz per arch. Verified on-device by apk-tools.
• .deb pipeline — used by debian images. Per-.deb SHA256 in the Packages file plus a clearsign-GPG InRelease per suite. Verified on-device by apt with Signed-By: scoped to the project keyring. Experimental — see module-debian.md for current status.

A single project can have both — one image targeting alpine and another targeting debian — and each lands in its own per-distro repository subtree.

Distro passthrough

module-alpine units don’t rebuild Alpine packages — they repack each upstream .apk, swapping the signature so the device’s apk-tools verifies against the project key like any other yoe-built package:

The control segment (PKGINFO, install scripts, file checksums) and data segment pass through byte-for-byte, so apk-tools on the device sees Alpine’s metadata, install behavior, and shared-library deps unchanged. Only the signature changes. See Alpine apk Passthrough for the two-metadata-systems story (.star fields drive the yoe resolver; PKGINFO drives apk-tools at install time) and the noarch routing details.

module-debian follows a parallel but distinct pattern. Upstream .deb files are mirrored verbatim (no repack), and only the project’s InRelease is re-signed with the project’s GPG key. Each downloaded .deb’s SHA256 is verified at mirror time against the upstream-signed Packages entry, and the device’s apt trust is scoped to the project key via deb822 Signed-By: — so the per-.deb upstream signature isn’t on the trust path at all, only the project-signed InRelease and the per-.deb SHA256 inside it. See module-debian.md for the verbatim-mirror rationale and the Valid-Until posture.

Signing and trust

Each pipeline has its own signing primitive, but both anchor on the same per-project key bootstrapped under ~/.config/yoe/keys/<project>/:

• apk pipeline — RSA-SHA1 per-.apk signature + signed APKINDEX.tar.gz, public half shipped in the rootfs via base-files.

  

• deb pipeline — clearsign-GPG InRelease per suite, public key staged at /etc/apt/keyrings/<project>.gpg and referenced from the deb822 .sources file’s Signed-By: field (scoping trust to the project source only, not the system-wide trust store). HTTPS-only URLs enforced at evaluation. Experimental status applies.

For both: the private key never leaves the workstation, and the public key travels through two independent channels (the project repo for inspection, the rootfs for verification). See apk Signing for the alpine key generation / rotation surface and the exact apk bytes that get signed. See module-debian.md for the deb trust details.

Deployment

A unit’s job ends when its package lands on a running device. The same apk repo and signing key serve image-time installs, the dev loop, and on-device OTA, so there’s only one delivery mechanism to understand.

Reaching a running device

Built packages flow from the workstation to a running yoe device through a small set of orthogonal channels: mDNS for discovery, HTTP for the package pull, and SSH for orchestration. The delivery mechanism is one — the per-distro package format is two:

• Alpine images consume an apk repo at repo/<project>/alpine/<arch>/ with the project’s RSA-signed APKINDEX. yoe device repo add writes the matching /etc/apk/repositories entry; apk add / apk upgrade then work on-device against the project’s own feed.
• Debian images consume a Debian-format repo at repo/<project>/debian/dists/<suite>/. The project’s GPG key signs the InRelease; image assembly stages /etc/apt/sources.list.d/<project>.sources (deb822 format) referencing the keyring via Signed-By:. apt update and apt install on the device verify against the project key only, so other apt sources can’t smuggle packages into the project’s namespace.

Same project key, same HTTP transport, same mDNS + SSH channels — the apk vs apt split is on-device tooling, not on-workstation infrastructure.

yoe serve is the long-lived HTTP + mDNS server, yoe device repo add does the one-time /etc/apk/repositories setup, and yoe deploy orchestrates the whole “build → ship → install” round trip. See Feed Server and yoe deploy for the workflows, command reference, and trust model, and module-debian for the apt side end-to-end.

Development

When a unit needs local changes — a fix to upstream, a vendored patch, an experimental tweak — yoe leans on plain git rather than a separate “dev mode.”

Source modifications round-trip

Every unit’s build directory is a regular git repo, living under build/<distro>/<unit>.<scope>/. The per-distro segment lets a source unit consumed by both an Alpine and a Debian image keep two destdirs (one built against musl, one against glibc) so each image gets the right libc without clobbering its peer between builds. Upstream source is checked out at the version pinned by the unit and tagged upstream; any patches the unit declares are applied as commits on top; your local edits become further commits. There’s no separate workspace, no mode to enter:

yoe dev extract turns the commits above upstream back into reviewable .patch files in your project repo — git format-patch under the hood — so the source of truth stays version-controlled even when iteration happens in the build dir. See yoe dev for the command surface and the upstream-rebase workflow.

Unit & Configuration Format

[yoe] uses Starlark — a deterministic, sandboxed dialect of Python — for all build definitions. Units, classes, machine definitions, and project configuration are all .star files. See Build Languages for the rationale behind this choice.

Units vs. Packages

These are distinct concepts in [yoe]:

• Units — .star files in the project tree that describe how to build software. They live in version control and are a development/CI concern.
• Packages — .apk files that units produce. They are installable artifacts published to a repository and consumed by apk during image assembly or on-device updates.

The build flow is: unit → build → .apk unit(s) → repository → image / device.

Units are inputs to the build system. Packages are outputs. A developer edits units; a device only ever sees packages.

Sub-packages (planned)

Status: Today [yoe] produces exactly one .apk per unit — internal/artifact/apk.go packages $DESTDIR into a single archive, and the Starlark subpackages = field is not yet parsed. This section describes the intended future model so units and classes can be written with it in mind.

A single unit will be able to produce a small number of .apk packages from one source build. The goal is targeted — keep runtime images lean — not exhaustive like Yocto’s auto-split of every recipe into 7+ packages.

The only two splits [yoe] plans to support as subpackages:

What is deliberately not a subpackage:

• Docs, man pages, info pages, locale data, examples. Classes strip these from $DESTDIR by default (e.g., autotools removes /usr/share/{doc,man,info,locale,gtk-doc,bash-completion} and /usr/share/*/examples). A unit that genuinely needs man pages on the device can opt out of the strip; most don’t.
• -src, -staticdev, -locale-*, -bin / -common style splits. Yocto produces these automatically; [yoe] does not. The cognitive cost (which-of-seven-packages-holds-this-file) and per-unit metadata surface isn’t worth it for yoe’s target audience.
• Library SONAME splits (libfoo0 separate from foo). Debian splits these to allow multiple ABI versions to coexist; [yoe] is rolling and ships one ABI at a time, so the split is unnecessary.

Rationale. Yocto’s auto-split-everything model exists because recipe authors cannot be trusted to strip docs/locale/staticdev consistently, so the build system does it mechanically. That logic doesn’t apply to [yoe]: the class library is small, AI-written units follow the class, and the image is already targeting single-digit MB. A rm -rf $DESTDIR/usr/share/{doc,man,…} in the class does what Yocto’s -doc subpackage does, with one package instead of two.

Planned unit surface:

load("//classes/autotools.star", "autotools")

autotools(
    name = "openssl",
    version = "3.2.1",
    source = "https://www.openssl.org/source/openssl-3.2.1.tar.gz",
    deps = ["zlib"],
    # Opt in to the two subpackages that matter on constrained devices.
    subpackages = ["dev", "dbg"],
)

With no subpackages field, the unit produces a single .apk containing everything in $DESTDIR after the class’s default strip. That is the expected case for most units.

Planned split rules:

• -dev claims /usr/include/**, /usr/lib/*.a, /usr/lib/pkgconfig/**, /usr/lib/cmake/**, /usr/share/aclocal/**, /usr/share/pkgconfig/**, /usr/bin/*-config (e.g., xml2-config).
• -dbg claims /usr/lib/debug/** (produced by running objcopy --only-keep-debug / strip --only-keep-debug on ELF binaries in $DESTDIR before packaging).
• Everything else stays in the main package.

For custom splits (e.g., separating openssh-server from openssh-client because an image ships one but not both), the plan is to allow explicit file lists:

autotools(
    name = "openssh",
    subpackages = ["dev", "dbg"],
    extra_subpackages = {
        "server": files(
            "/usr/sbin/sshd",
            "/etc/ssh/sshd_config",
        ),
        "client": files(
            "/usr/bin/ssh",
            "/usr/bin/scp",
            "/usr/bin/sftp",
        ),
    },
)

This path is lower priority; most services can be shipped as one package and enabled/disabled by the image.

In image units (planned consumption):

image(
    name = "production-image",
    artifacts = [
        "openssh",
        "networkmanager",
    ],
)

image(
    name = "dev-image",
    artifacts = [
        "openssh",
        "openssh-dev",          # headers for on-device development
        "gdb",
    ],
)

Alpine’s apk already supports subpackages natively (Alpine’s openssl APKBUILD produces openssl, openssl-dev, openssl-dbg, etc.), so the plumbing in apk is already proven — what [yoe] needs to build is the Starlark surface, the split engine, and the default strip logic in the shared classes.

Dependency resolution at image time

There are two places dependency information lives in [yoe], and they serve different phases:

• Unit metadata (deps, runtime_deps in .star files) — drives the build graph. Tells the build executor what order to compile things in and what goes into each unit’s sysroot.
• Package metadata (.PKGINFO inside each .apk; aggregated into an APKINDEX) — drives the install graph. Tells apk what to pull in when a package is added to a rootfs.

The unit author writes runtime_deps = [...] once; the build emits those into .PKGINFO as depend = lines. From that point the package metadata is authoritative for installation: image assembly invokes apk add --root <rootfs> -X <local-repo> inside the build container, and apk-tools resolves the install graph from APKINDEX. The Starlark-side _resolve_runtime_deps is still used to flatten the artifact list for the build DAG (so all required apks get built first), but apk-tools owns install-time ordering, file-conflict detection, and /lib/apk/db/installed population.

Why this is the right split:

• Subpackages. When openssl splits into openssl and openssl-dev, the unit graph no longer has a node named openssl-dev. The dep openssl-dev → openssl = ${version} lives only in the generated PKGINFO. A unit-graph walker cannot see it; apk’s resolver can.
• provides: / replaces: / conflicts:. apk’s metadata supports virtual packages and alternatives (e.g., two SSH implementations both provides = ssh, one replaces the other). A Starlark-only walker would have to re-implement apk’s resolver to honor these.
• External repositories compose cleanly. A project that pulls packages from an Alpine aports mirror or a vendor BSP repo has no Starlark unit to walk — only APKINDEX metadata. apk treats yoe-built packages and external-repo packages identically.
• Single source of truth on the device. What the image builder sees is what the on-device apk upgrade sees: same metadata, same resolver.

Why Starlark

• One language — units, classes, machines, and project config are all .star files. No TOML + shell + something-else stack.
• Python-like syntax — most developers can read it immediately.
• Deterministic — no side effects, no mutable global state. Critical for content-addressed caching.
• Sandboxed — units cannot perform arbitrary I/O or network access.
• Go-native — the go.starlark.net library embeds directly in the yoe binary.
• Composable — functions, load(), and **kwargs provide natural composition for modules and overrides.
• Battle-tested — used by Bazel (Google), Buck2 (Meta), and Pants.

Unit Types

Machine Definition (machines/<name>.star)

Describes a target board or platform.

machine(
    name = "beaglebone-black",
    arch = "arm64",
    description = "BeagleBone Black (AM3358)",
    kernel = kernel(
        repo = "https://github.com/beagleboard/linux.git",
        branch = "6.6",
        defconfig = "bb.org_defconfig",
        device_trees = ["am335x-boneblack.dtb"],
    ),
    bootloader = uboot(
        repo = "https://github.com/beagleboard/u-boot.git",
        branch = "v2024.01",
        defconfig = "am335x_evm_defconfig",
    ),
)

QEMU machines include emulation configuration:

machine(
    name = "qemu-x86_64",
    arch = "x86_64",
    kernel = kernel(
        unit = "linux-qemu",
        cmdline = "console=ttyS0 root=/dev/vda2 rw",
    ),
    qemu = qemu_config(
        machine = "q35",
        cpu = "host",
        memory = "1G",
        firmware = "ovmf",
        display = "none",
    ),
)

Image Unit (units/<name>.star)

An image is a unit that assembles a root filesystem from packages and produces a disk image. Image units use the image() class function instead of unit(). They participate in the same DAG, use the same caching, and are built with yoe build.

load("//classes/image.star", "image")

image(
    name = "base-image",
    version = "1.0.0",
    description = "Minimal bootable system",
    # Packages installed into the rootfs.
    # The base system (C library + busybox + init) is implicit unless excluded.
    artifacts = [
        "openssh",
        "networkmanager",
        "myapp",
        "monitoring-agent",
    ],
    # hostname defaults to ctx.machine (e.g. "raspberrypi4"); set to override.
    timezone = "UTC",
    locale = "en_US.UTF-8",
    services = ["sshd", "NetworkManager", "myapp"],
    partitions = [
        partition(label="boot", type="vfat", size="64M",
                  contents=["MLO", "u-boot.img", "zImage", "*.dtb"]),
        partition(label="rootfs", type="ext4", size="fill", root=True),
    ],
)

Image Composition and Variants

Image variants use plain Starlark variables and list concatenation — no special inheritance mechanism:

load("//classes/image.star", "image")

BASE_PACKAGES = [
    "openssh",
    "networkmanager",
    "myapp",
    "monitoring-agent",
]

BASE_SERVICES = ["sshd", "NetworkManager", "myapp"]

BBB_PARTITIONS = [
    partition(label="boot", type="vfat", size="64M",
              contents=["MLO", "u-boot.img", "zImage", "*.dtb"]),
    partition(label="rootfs", type="ext4", size="fill", root=True),
]

image(
    name = "base-image",
    version = "1.0.0",
    packages = BASE_PACKAGES,
    services = BASE_SERVICES,
    partitions = BBB_PARTITIONS,
    # hostname defaults to ctx.machine; pass an explicit string to override.
)

image(
    name = "dev-image",
    version = "1.0.0",
    description = "Development image with debug tools",
    packages = BASE_PACKAGES + ["gdb", "strace", "tcpdump", "vim"],
    exclude = ["monitoring-agent"],
    services = BASE_SERVICES,
    partitions = BBB_PARTITIONS,
)

Conditional packages per machine:

artifacts = ["openssh", "myapp"]
if machine.arch == "arm64":
    packages += ["arm64-firmware"]

Package Unit (units/<name>.star)

Describes how to build a system-level package (C/C++ libraries, system daemons, etc.) and produce an .apk. Uses a class function like autotools(), cmake(), or the generic unit().

load("//classes/autotools.star", "autotools")

autotools(
    name = "openssh",
    version = "9.6p1",
    description = "OpenSSH client and server",
    license = "BSD",
    source = "https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-9.6p1.tar.gz",
    sha256 = "...",
    configure_args = ["--sysconfdir=/etc/ssh"],
    deps = ["zlib", "openssl"],
    runtime_deps = ["zlib", "openssl"],
    services = ["sshd"],
    conffiles = ["/etc/ssh/sshd_config"],
)

Or using the generic unit() for custom build steps:

unit(
    name = "openssh",
    version = "9.6p1",
    source = "https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-9.6p1.tar.gz",
    sha256 = "...",
    deps = ["zlib", "openssl"],
    runtime_deps = ["zlib", "openssl"],
    build = [
        "./configure --prefix=$PREFIX --sysconfdir=/etc/ssh",
        "make -j$NPROC",
        "make DESTDIR=$DESTDIR install",
    ],
    services = ["sshd"],
    conffiles = ["/etc/ssh/sshd_config"],
)

Patches

Units can apply patches to upstream source after fetching and before building. Patches are listed in order and applied with git apply or patch -p1:

unit(
    name = "busybox",
    version = "1.36.1",
    source = "https://busybox.net/downloads/busybox-1.36.1.tar.bz2",
    patches = [
        "busybox/fix-ash-segfault.patch",
        "busybox/add-custom-applet.patch",
    ],
    build = ["make -j$NPROC", "make DESTDIR=$DESTDIR install"],
)

Patch file paths are relative to the directory holding the unit’s .star file, so a module ships its patches alongside the unit that uses them (e.g., modules/module-core/units/net/mdnsd/0001-…patch for a unit at modules/module-core/units/net/mdnsd.star). Patch contents are included in the unit’s cache hash — changing a patch triggers a rebuild.

Module overrides for patches work through the standard function composition pattern:

# upstream: @module-core/busybox.star
def busybox(extra_patches=[], **overrides):
    unit(
        name = "busybox",
        version = "1.36.1",
        source = "https://busybox.net/downloads/busybox-1.36.1.tar.bz2",
        patches = [
            "busybox/fix-ash-segfault.patch",
        ] + extra_patches,
        build = ["make -j$NPROC", "make DESTDIR=$DESTDIR install"],
        **overrides,
    )

# vendor module: adds a patch without modifying upstream
load("@module-core//busybox.star", "busybox")
busybox(extra_patches=["vendor-busybox-audit.patch"])

Alternatives to patches:

• Git-based sources — fork the repo, apply changes as commits, point the unit at your branch/tag. Cleaner history, easier to rebase on upstream updates.
• Overlay files — for config file changes on the target, the overlays/ directory is simpler than patching source.

Tasks and Per-Task Containers (planned)

Status: task() and unit-level container = are shipped — every built-in class in modules/module-core/classes/ (autotools, cmake, go, container, image) already generates tasks = [task(...)] and the build executor (internal/build/executor.go) runs each task’s steps inside the unit’s resolved container. The per-task container= override described below is planned: the task struct in Starlark accepts the field but the executor currently ignores it and uses the unit-level container for every task in the unit. Wire-through is the remaining work.

Units can define named build tasks via task(), each with an optional Docker container. This replaces the flat build = [...] string list with structured steps that can each run in different environments.

Container resolution order: task container → package container → bwrap (default).

# Simple — build list works as before (bwrap, no containers)
autotools(name = "zlib", source = "...", ...)

# Package-level container — all tasks inherit it
go_binary(
    name = "myapp",
    container = "golang:1.22-alpine",
    tasks = [
        task("build", run="go build -o $DESTDIR/usr/bin/myapp"),
        task("test", run="go test ./..."),
    ],
)

# Task-level override — codegen uses a different container
unit(
    name = "complex-app",
    container = "golang:1.22-alpine",       # default for all tasks
    tasks = [
        task("codegen",
             container="protoc:latest",     # overrides package default
             run="protoc --go_out=. api/*.proto"),
        task("compile",
             run="go build -o $DESTDIR/usr/bin/app"),  # inherits golang
        task("install",
             run="install -D app.service $DESTDIR/usr/lib/systemd/system/"),
    ],
)

# Mix of container and bwrap in one unit
unit(
    name = "hybrid-tool",
    tasks = [
        task("generate",
             container="codegen-tools:latest",
             run="generate-code --out src/"),
        task("compile", run="make -j$NPROC"),  # no container → bwrap
        task("install", run="make DESTDIR=$DESTDIR install"),
    ],
)

The build = [...] field remains for backward compatibility — internally converted to unnamed tasks without containers. Classes generate tasks:

# classes/autotools.star generates three tasks
def autotools(name, version, source, configure_args=[], **kwargs):
    unit(
        name=name, version=version, source=source,
        tasks = [
            task("configure",
                 run="test -f configure || autoreconf -fi && "
                     "./configure --prefix=$PREFIX " + " ".join(configure_args)),
            task("compile", run="make -j$NPROC"),
            task("install", run="make DESTDIR=$DESTDIR install"),
        ],
        **kwargs,
    )

Extending a class’s tasks — when a unit passes tasks=[...] to a class (autotools, cmake, go_binary), the class merges the overrides into its default task list rather than replacing them entirely. Merge rules:

• Same name → replace at the existing position (the override’s steps fully replace the base’s; merging steps is not supported).
• New name → append to the end.
• task("name", remove=True) → drop that task from the base list.

# Adds an init-script task without restating the class's default build task.
go_binary(
    name = "simpleiot",
    ...
    tasks = [
        task("init-script", steps = [
            "mkdir -p $DESTDIR/etc/init.d",
            install_file("simpleiot.init",
                         "$DESTDIR/etc/init.d/simpleiot", mode = 0o755),
        ]),
    ],
)

Merging is implemented by merge_tasks(base, overrides) in modules/module-core/classes/tasks.star. Custom classes that want the same behavior should load("//classes/tasks.star", "merge_tasks") and call it before passing tasks to unit().

See per-unit containers plan for the full design.

Application Unit (units/<name>.star)

Applications built with language-native build systems use language-specific class functions that delegate to the language toolchain.

load("//classes/go.star", "go_binary")

go_binary(
    name = "myapp",
    version = "1.2.3",
    description = "Edge data collection service",
    license = "Apache-2.0",
    source = "https://github.com/example/myapp.git",
    tag = "v1.2.3",
    package = "./cmd/myapp",
    services = ["myapp"],
    conffiles = ["/etc/myapp/config.toml"],
    environment = {"DATA_DIR": "/var/lib/myapp"},
)

Language-specific classes handle the build details — go_binary() sets up GOMODCACHE, runs go build, and packages the result.

Status: Only go_binary() (in modules/module-core/classes/go.star) is implemented today. Similar classes for Rust (rust_binary()), Zig (zig_binary()), Python (python_unit()), and Node.js (node_unit()) are planned but not yet shipped. Applications in those languages can still be built by using unit() directly with explicit build steps.

Project Configuration (PROJECT.star)

Top-level configuration that ties everything together.

project(
    name = "yoe",
    version = "0.1.0",
    description = "`[yoe]` embedded Linux distribution",
    defaults = defaults(
        machine = "qemu-arm64",
        image = "base-image",
    ),
    cache = cache(
        path = "/var/cache/yoe/build",
        remote = [
            s3_cache(
                name = "team",
                bucket = "yoe-cache",
                endpoint = "https://minio.internal:9000",
                region = "us-east-1",
            ),
        ],
        retention_days = 90,
        signing = "keys/cache.pub",
    ),
    sources = sources(
        go_proxy = "https://proxy.golang.org",
    ),
    modules = [
        # Module in a subdirectory of a repo — path specifies where MODULE.star is
        module("https://github.com/yoebuild/yoe.git",
              ref = "main",
              path = "modules/module-core"),
        # Module at the root of its own repo
        module("git@github.com:vendor/bsp-units.git", ref = "main"),
    ],
)

Classes

Classes are Starlark functions that define build pipelines for different unit types. They encapsulate the how to build logic so that units only declare what to build.

Built-in Classes

These ship with the module-core module (at modules/module-core/classes/) or are under the (planned) roadmap:

Class Composition

Classes compose through function calls. A unit can use multiple classes, and classes can wrap other classes:

load("//classes/autotools.star", "autotools")
load("//classes/systemd.star", "systemd_service")

# Use both autotools and systemd classes
autotools(
    name = "openssh",
    version = "9.6p1",
    configure_args = ["--sysconfdir=/etc/ssh"],
    deps = ["zlib", "openssl"],
)

systemd_service(
    name = "openssh",
    unit = "sshd.service",
    conffiles = ["/etc/ssh/sshd_config"],
)

Or create a combined class:

# classes/systemd_autotools.star
load("//classes/autotools.star", "autotools")
load("//classes/systemd.star", "systemd_service")

def systemd_autotools(name, unit, conffiles=[], **kwargs):
    autotools(name=name, **kwargs)
    systemd_service(name=name, unit=unit, conffiles=conffiles)

Custom Classes

Projects can define their own classes in classes/ for patterns specific to their codebase:

# classes/my_go_service.star
load("//classes/go.star", "go_binary")
load("//classes/systemd.star", "systemd_service")

def my_go_service(name, version, source, **kwargs):
    """Standard pattern for our Go microservices."""
    go_binary(
        name = name,
        version = version,
        source = source,
        **kwargs,
    )
    systemd_service(
        name = name,
        unit = name + ".service",
        conffiles = ["/etc/" + name + "/config.toml"],
    )

Extensibility: Starlark and Go

Starlark is not a standalone language — it runs embedded inside the yoe Go binary. Every built-in function (unit(), machine(), image(), etc.) is a Go function registered into the Starlark environment. When Starlark code calls unit(name="openssh", ...), it executes Go code that has full access to the host runtime.

This means the system is extensible in two directions:

Go to Starlark (primitives): The yoe binary provides built-in functions that Starlark code can call. These have capabilities Starlark alone cannot — filesystem I/O, network access, executing system tools (apk, bwrap, git), managing the build engine state. Adding a new built-in is a Go function with the right signature:

// In Go: register a new built-in function
func (e *Engine) fnDeploy(thread *starlark.Thread, fn *starlark.Builtin,
    args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
    target := kwString(kwargs, "target")
    // Full access to Go runtime — HTTP, filesystem, exec, etc.
    return starlark.None, nil
}

// Register it in builtins():
"deploy": starlark.NewBuiltin("deploy", e.fnDeploy),

Now any .star file can call deploy(target="production").

Starlark to Starlark (composition): Users define functions in .star files that compose the Go-provided primitives. Classes, macros, and helpers are just Starlark functions that call built-in functions:

# classes/my_service.star — user-defined class wrapping Go builtins
def my_service(name, version, **kwargs):
    go_binary(name=name, version=version, **kwargs)  # calls Go
    systemd_service(name=name, unit=name + ".service")  # calls Go

The architecture mirrors Bazel: Go provides the primitives (package creation, image assembly, sandbox execution, cache management), Starlark provides the composition layer (classes, conditionals, module overrides, shared variables). Starlark code cannot perform arbitrary I/O — it can only call the Go functions that yoe explicitly exposes, maintaining the sandboxed, deterministic evaluation model.

Directory Structure

A typical [yoe] project layout:

my-project/
├── PROJECT.star
├── machines/
│   ├── beaglebone-black.star
│   ├── raspberrypi4.star
│   └── qemu-arm64.star
├── units/
│   ├── base-image.star         # image() class
│   ├── dev-image.star          # image() class, extends base
│   ├── openssh.star            # autotools() class
│   ├── zlib.star
│   ├── openssl.star
│   ├── myapp.star              # go_binary() class
│   └── monitoring-agent.star
├── classes/                    # reusable build rule functions
├── commands/                  # custom yoe subcommands
│   ├── my_go_service.star
│   └── ...
└── overlays/
    └── custom-configs/         # files copied directly into rootfs
        └── etc/
            └── myapp/
                └── config.toml

Build Flow

  units/*.star               (all unit types: package and image)
       │
       ▼
  yoe build                    (evaluate Starlark, resolve DAG, build)
       │
       ├─ unit() ──▶ compile source ──▶ *.apk artifacts ──▶ repository/
       │
       └─ image()   ──▶ apk install deps into rootfs
                        ──▶ apply overlays + config
                        ──▶ partition + format
                        ──▶ disk image (.img / .wic)

Modules

Modules are external Git repositories that provide units, classes, and machine definitions. They are the primary mechanism for reusing and sharing build definitions across projects — BSP vendors ship modules, and product teams compose them.

Declaring Modules in PROJECT.star

project(
    name = "my-product",
    version = "1.0.0",
    modules = [
        # Module in a subdirectory of a repo
        module("https://github.com/yoebuild/yoe.git",
              ref = "main",
              path = "modules/module-core"),
        # Module at the root of its own repo
        module("git@github.com:vendor/bsp-imx8.git", ref = "v2.1.0"),
    ],
)

Each module() call declares a Git repository URL and a ref (tag, branch, or commit SHA). The optional path field specifies a subdirectory within the repo where MODULE.star lives — this allows a single repo to contain multiple modules or a module to be part of a larger project. The yoe tool fetches and caches these repositories, making them available as @module-name in load() statements. The module name is derived from the last component of path (if set) or the URL.

Module Manifests (MODULE.star) (planned)

Status: The module_info() Starlark builtin is wired up in internal/starlark/builtins.go and the ModuleInfo struct is populated when a MODULE.star is evaluated, but the module resolver in internal/module/ never reads those declared deps. Transitive module resolution — both the v1 “error on missing” and v2 “auto-fetch” behaviors below — is planned. Today only the top-level modules = [...] list in PROJECT.star is fetched.

Modules can declare their own dependencies via a MODULE.star file in the repository root. This enables BSP vendors to ship self-contained modules without requiring users to manually discover transitive dependencies.

# In github.com/vendor/bsp-imx8/MODULE.star
module_info(
    name = "vendor-bsp-imx8",
    description = "i.MX8 BSP units and machine definitions",
    deps = [
        module("github.com/vendor/hal-common", ref = "v1.3.0"),
        module("github.com/vendor/firmware-imx", ref = "v5.4"),
    ],
)

Dependency Resolution Rules

Module dependencies follow the Go modules model — the root project has final authority over versions:

1. PROJECT.star always wins. If PROJECT.star and a MODULE.star both reference the same repository, the version in PROJECT.star takes precedence. This gives the project owner full control over the dependency tree.

2. Transitive deps are checked, not silently fetched (v1). In the initial implementation, yoe reads each module’s MODULE.star and errors if a required dependency is missing from PROJECT.star, rather than silently fetching it. The error message tells the user exactly what to add. This is explicit and debuggable.

3. Automatic transitive resolution (v2). In a future version, transitive dependencies declared in MODULE.star are fetched automatically when not overridden by PROJECT.star. yoe module list shows the full resolved tree so nothing is hidden.

4. Diamond dependencies resolve to the highest version. If two modules depend on different versions of the same repository, yoe selects the higher version (semver comparison) unless PROJECT.star pins a specific version.

Example — v1 behavior (missing transitive dep):

$ yoe build --all
Error: module "vendor-bsp-imx8" requires "github.com/vendor/hal-common" (ref v1.3.0)
       but it is not declared in PROJECT.star.

Add this to your PROJECT.star modules list:
    module("github.com/vendor/hal-common", ref = "v1.3.0"),

Example — PROJECT.star overriding a transitive version:

# PROJECT.star
modules = [
    module("github.com/yoe/module-core", ref = "v1.0.0"),
    module("github.com/vendor/bsp-imx8", ref = "v2.1.0"),
    # Override the version that bsp-imx8 requests (v1.3.0 → v1.4.0)
    module("github.com/vendor/hal-common", ref = "v1.4.0"),
]

Local Module Overrides

During development, you often want to work on a module locally instead of fetching from Git. The local parameter overrides the remote URL:

modules = [
    # Local override — point at a checkout on disk instead of fetching
    module("https://github.com/yoebuild/yoe.git",
          local = "../yoe",
          path = "modules/module-core"),
    # Local override for a standalone module
    module("git@github.com:vendor/bsp-imx8.git", local = "../bsp-imx8"),
]

When local is set, yoe uses the local directory directly (no fetch, no ref checking). If path is also set, it is appended to the local path. This is equivalent to Go’s replace directive in go.mod.

Label-Based References

Inspired by Bazel’s label system and GN’s //path/to:target, [yoe] uses a label scheme for referencing units and classes across repositories:

# Local references (within the current project)
load("//classes/autotools.star", "autotools")   # from project root
load("//units/openssh.star", "openssh_config") # load shared config

# External references (from modules)
load("@module-core//openssh.star", "openssh")
load("@vendor-bsp//kernel.star", "vendor_kernel")

Module names (@module-core, @vendor-bsp) map to the modules declared in PROJECT.star. When yoe evaluates units, it fetches and caches external modules, then resolves all load() references to concrete files.

Module Composition

Modules enable the vendor BSP / product overlay pattern without modifying upstream units:

# Module 1: @module-core/openssh.star — base unit as a function
def openssh(extra_deps=[], extra_configure_args=[], **overrides):
    autotools(
        name = "openssh",
        version = "9.6p1",
        deps = ["zlib", "openssl"] + extra_deps,
        configure_args = ["--sysconfdir=/etc/ssh"] + extra_configure_args,
        **overrides,
    )

# Module 2: @vendor-bsp/openssh.star — vendor extends it
load("@module-core//openssh.star", "openssh")
openssh(extra_deps=["vendor-crypto"])

# Module 3: product unit — further customization
load("@vendor-bsp//openssh.star", "openssh")
openssh(extra_configure_args=["--with-pam"])

Each module is explicit about what it modifies and where the base comes from. This is more traceable than Yocto’s bbappend system — you can grep for the function call to find all modifications.

Design Notes

• Starlark over TOML/YAML — pure data formats accumulate escape hatches (conditional deps, shell in strings, inheritance). Starlark makes the implicit explicit while remaining readable for simple cases. See Build Languages for the full analysis.
• Prefer git sources over tarballs — git sources give you upstream history, clean git rebase for patch updates, natural yoe dev workflow (edit, commit, extract patches), and no SHA256 to maintain. Use source = "https://...git" with a tag to pin the version.
• One file per unit — each unit is its own .star file. This keeps diffs clean and makes it easy to add/remove components.
• Units and packages are separate concerns — units are version-controlled build instructions; packages are binary artifacts. This separation enables building once and deploying many times, sharing packages across teams, and on-device incremental updates via apk.
• Classes as functions — build patterns (autotools, cmake, go) are Starlark functions, not a type system. Multiple classes compose through function calls. This is simpler and more flexible than Yocto’s class inheritance.
• Unified unit directory — system packages, application packages, and images all live in units/. The class function determines the output: unit() / autotools() / etc. produce .apk files, image() produces disk images. One concept (unit), one directory, one DAG.
• apk for image assembly — image units declare their packages as dependencies. yoe build <image> creates a clean rootfs and runs apk add to populate it from the repository, exactly like Alpine’s image builder. This leverages apk’s dependency resolution rather than reimplementing it.

Naming and Resolution

How modules, units, and dependencies are named, referenced, and resolved in [yoe].

See metadata-format.md for the full unit/class/module Starlark API. See build-environment.md for how build isolation and caching work.

Modules

A module is a Git repository (or subdirectory of one) that provides units, classes, machine definitions, and images. Modules are declared in PROJECT.star:

project(
    name = "my-product",
    modules = [
        module("https://github.com/yoebuild/yoe.git",
              ref = "main",
              path = "modules/module-core"),
        module("https://github.com/vendor/bsp-imx8.git",
              ref = "v2.1.0"),
    ],
)

Module name is derived from the path field’s last component if set, otherwise the URL’s repository name. Examples:

Module names are used in load() statements: load("@module-core//classes/autotools.star", "autotools").

Module directory structure

<module-root>/
  MODULE.star         # module metadata and dependencies
  classes/            # build pattern functions (autotools, cmake, etc.)
  units/              # unit definitions (.star files)
  machines/           # machine definitions (.star files)
  images/             # image definitions (.star files)

Evaluation order

1. Phase 1 — PROJECT.star is evaluated. Modules are synced (cloned/fetched).

2. Phase 1b — Machine definitions from all modules are evaluated.

3. Phase 2 — Units and images from all modules are evaluated. A single ctx struct is predeclared, exposing the active build context: ctx.arch, ctx.machine, ctx.project_version, ctx.machine_config, and ctx.provides (a callable dict — use ctx.provides.get(name) to resolve a virtual to a concrete unit name).

   The closure walk that used to live in Starlark — and that needed ctx.runtime_deps, a dict pre-populated with every unit’s deps — is now a Go-side resolve_closure(artifacts) builtin. It walks the runtime-dep graph on demand and materializes synthetic-module units (see Feeds as synthetic modules) lazily, so the working set stays bounded by closure size rather than catalog size. Image classes call it directly: resolved = resolve_closure(explicit_artifacts).

Within each phase, modules are evaluated in declaration order. Within a module, .star files are evaluated in filesystem walk order.

Units

A unit is a named build definition declared via unit(), image(), or a class function like autotools() or cmake(). Each unit produces one or more .apk packages.

Current naming model

Unit names are flat strings with no module namespace. Within a single module the name must be unique — defining unit(name = "zstd", ...) twice in one module is an error. Across modules, a same-named unit is a shadow: the higher-priority unit wins and a notice is emitted on stderr. Priority follows the project’s module list order (project root > last module > … > first module). See Unit replacement via name shadowing for the full rule and use cases.

Dependencies

Units declare two kinds of dependencies:

• deps — build-time. The dependency’s output is available in the build sysroot during compilation. Resolved by the yoe DAG.
• runtime_deps — install-time. Recorded in the .apk package metadata and resolved by apk during image assembly or on-device install.

Both reference units by name:

autotools(
    name = "curl",
    deps = ["openssl", "zlib", "zstd"],
    runtime_deps = ["openssl", "zlib", "zstd"],
)

Transitive dependencies

Build-time deps are resolved transitively by the DAG. If curl depends on openssl and openssl depends on zlib, curl’s build sysroot includes both.

Runtime deps are resolved transitively by apk at install time.

Load references

Starlark load() statements use three forms:

The // form is context-aware: if the file is inside a module, // resolves to that module’s root. Otherwise it resolves to the project root. This means a unit in module-core can load("//classes/autotools.star", ...) and it resolves within module-core, not the project root.

Virtual packages (ctx.provides)

The ctx.provides dict maps virtual names to concrete unit names. This allows images to reference abstract capabilities rather than specific units:

# Machine definition contributes:
machine(
    name = "raspberrypi4",
    kernel = kernel(unit = "linux-rpi4", provides = "linux"),
)

# Unit can also declare provides — apk-style list of virtual names:
unit(name = "linux-rpi4", provides = ["linux"], ...)

# Image uses the virtual name:
image(name = "base-image", artifacts = ["busybox", "linux", "init"], ...)
# "linux" resolves to "linux-rpi4" via ctx.provides
# "init" resolves to whichever init system the project includes

This pattern extends to any swappable core component. For example, the init system can be abstracted behind a virtual name, with thin configuration modules providing the concrete implementation:

# modules/config-systemd/units/init.star
unit(name = "systemd", ..., provides = ["init"])

# modules/config-busybox-init/units/init.star
unit(name = "busybox-init", ..., provides = ["init"])

The project selects which init system to use by including the appropriate module:

# projects/product-a.star
project(name = "product-a", modules = [
    module("...", path = "modules/module-core"),
    module("...", path = "modules/config-systemd"),
])

# projects/product-b.star
project(name = "product-b", modules = [
    module("...", path = "modules/module-core"),
    module("...", path = "modules/config-busybox-init"),
])

Images reference init in their artifacts — they don’t need to know whether the product uses systemd or busybox init.

ctx.provides is populated in two stages:

1. After phase 1 (machines) — kernel.provides entries are added
2. After phase 2 (units) — unit provides fields are added

See Collision Detection for scoping and priority rules.

Unit replacement via name shadowing

The simplest way to replace an upstream unit is to define one with the same name in a higher-priority module. The higher-priority unit shadows the upstream — only it is registered in the DAG; the lower-priority unit is discarded with a notice on stderr.

Priority follows declaration order in project(). The project root has the highest priority overall; among modules, later in the list wins:

project(name = "product", modules = [
    module("https://github.com/yoebuild/module-alpine.git", ref = "main"),  # lowest priority
    module("...", path = "modules/soc-module"),    # overrides module-alpine
    module("...", path = "modules/som-module"),    # highest priority among modules
])
# Project root (units/ in the project directory) overrides all three.

Concrete example — replacing Alpine’s prebuilt musl with a from-source build:

# @module-alpine//units/musl.star
alpine_pkg(name = "musl", version = "1.2.5-r0", ...)

# @my-overrides//units/musl.star  (listed after module-alpine)
unit(name = "musl", source = "https://git.musl-libc.org/git/musl",
     tag = "v1.2.5", tasks = [...])

Every other unit’s deps = ["musl"] and runtime_deps = ["musl"] resolve to the winner automatically — there is nothing to change in consumers when an override happens. The build emits:

notice: unit "musl" from module "my-overrides" shadows the same name from module "module-alpine"

Use shadowing for 1:1 replacement — “my musl instead of yours.” It is the right tool whenever a module wants to swap an upstream unit for a different implementation while keeping consumers unchanged.

Unit replacement via provides

provides is for a different problem: N:1 alternative selection. Several units in the same project can each satisfy a virtual role, and the project (or machine) selects which one wins at evaluation time. The canonical case is a kernel — a single module ships linux-rpi4 and linux-bb, both declaring provides = ["linux"], and the active machine picks one.

# @module-core//units/kernels.star
unit(name = "linux-rpi4", provides = ["linux"], ...)
unit(name = "linux-bb",   provides = ["linux"], ...)

# machines/raspberrypi4.star
machine(name = "rpi4", kernel = kernel(unit = "linux-rpi4", provides = "linux"))

# machines/beaglebone.star
machine(name = "bbb",  kernel = kernel(unit = "linux-bb",  provides = "linux"))

# Images reference the virtual name; resolution picks the right kernel.
image(name = "base", artifacts = ["busybox", "linux"])

Both kernel units coexist in the namespace — they have distinct real names — and ctx.provides["linux"] is set per machine. This is something shadowing can’t express: shadowing requires identical real names, so multiple alternatives can’t both be present.

The same module-priority rule applies when two modules each contribute a provides for the same virtual name — the higher-priority module wins, with a stderr notice. But for the common “override an upstream unit” case, prefer shadowing: it requires no virtual-name layer, and reading the override file tells the whole story.

When NOT to use provides

provides is powerful but has a hidden cost: the build cache hashes resolved deps recursively, so a provides swap forks every transitive consumer into a machine-specific apk variant. Used carelessly it can turn a clean cross- machine apk repo into hundreds of near-identical packages.

The rule that keeps the apk repo lean:

provides is for leaf artifacts referenced by other units only as runtime_deps — kernel, base-files, init, bootloader. It is not for build-time libraries, and not for runtime alternatives that can be selected at boot.

This means:

• Don’t provides a build-time library. Swapping openssl ↔ libressl via provides would fan out every curl, openssh, python apk per selection. If you need a different crypto library, give it a different name and have consumers reference it explicitly.
• Don’t put machine-flavored units in a generic library’s build-time deps. A library should depend on other libraries, never on linux, base-files, or any unit that varies by machine — otherwise the library’s apk forks per machine even though its compiled output is identical.
• Don’t use provides for runtime alternatives. For pairs like mdev (busybox) vs eudev, udhcpc (busybox) vs dhcpcd, or busybox ntpd vs ntp-client, install both packages and pick which daemon runs at boot from an init script. The init script lives in a config unit (e.g., network-config) that’s already project- or machine-flavored, so the choice doesn’t propagate into generic library hashes.

In short: keep machine variability at the edges of the DAG (kernel, bootloader, machine config, init scripts). Generic libraries and tools should have one hash regardless of which machine the project targets.

Shadow files (REPLACES)

When two packages legitimately ship the same file path — most often a real implementation overriding a busybox stub — the owning package needs to opt into the shadow with replaces. apk refuses to install a package whose files conflict with already-installed ones unless the installing package declares it’s allowed to overwrite the loser.

# util-linux ships real /bin/dmesg, /bin/mount, /bin/umount, /sbin/fsck,
# /sbin/hwclock, /sbin/losetup, /sbin/switch_root, /usr/bin/logger,
# /usr/bin/nsenter, /usr/bin/unshare — all paths busybox also claims.
unit(
    name = "util-linux",
    ...
    replaces = ["busybox"],
)

Mechanics worth remembering:

• Direction is per-file: the package that overwrites is the one that declares. If util-linux installs after busybox and overwrites busybox’s stubs, util-linux declares replaces = ["busybox"]. Declaring it on busybox would only help if busybox were the one installing later.
• apk install order is set by the dep graph. ncurses precedes busybox in the dev-image not because of the artifact list but because ncurses is a runtime dep of util-linux, less, vim, htop, and procps-ng — apk has to install it first. busybox is a dependency-graph leaf, so it lands later and is the one whose clear/reset overwrite ncurses’. Hence busybox declares replaces = ["ncurses"].
• replaces is not a package fork. The annotation lives on a single generic .apk that every project shares. apk uses it to decide who owns the file in /lib/apk/db/installed, so future operations on either package do the right thing.

When you see a “trying to overwrite X owned by Y” install error, the fix is one of:

1. Add replaces = ["Y"] to the unit that owns the overwriting package.
2. Stop the duplication at its source — e.g., split a package into a subpackage that doesn’t ship the conflicting paths (subpackages are a future apk-compat phase; until then replaces is the lever).
3. Disable the offending applet in the loser via runtime config — only if it can be done without forking the unit’s build, which is rarely possible for fine-grained busybox knobs.

Keep units generic — resolve variation at runtime

The previous section is one expression of a broader principle: a unit produces one .apk that every project and every machine shares. When two images need different behavior from the same package, the answer is almost never “fork the package.” It’s “resolve the difference at runtime, in a component that’s allowed to vary.”

Concretely, when you reach for a per-project or per-machine variant of a generic unit, prefer instead:

• Init scripts that detect what’s installed. The network OpenRC service checks command -v dhcpcd and falls back to busybox udhcpc when it’s missing — one network-config unit, two viable runtimes, no DHCP-client fork.
• Conditional config files in a project- or machine-scoped config unit (e.g., base-files-<project>, network-config). Those units are already flavored, so they’re the right place for choices that have to vary.
• replaces: annotations on the unit that owns the shadow. When busybox and ncurses both ship /usr/bin/clear, declaring replaces on one of them lets apk pick a winner without touching either build. Both apks stay generic.
• Runtime alternative selection at boot — install both candidates, start one from an init script.

Reach for build-flag forking only when runtime resolution is genuinely impossible: kernel defconfig (the kernel binary literally varies by machine), bootloader target, machine-specific firmware blobs. Everything else — busybox config knobs, library build flags, optional features — has to stay one .apk for every consumer.

The cost of forking generic units is real: build cache surface multiplies, binary reuse across projects breaks, and complexity moves from a few clean conditionals in one config unit into N parallel build configurations scattered across the tree. The cost of runtime resolution is a small init script or a one-line replaces annotation — pay that instead.

Module composition

Modules extend upstream units without modifying them by importing the unit as a callable function:

# @module-core provides openssh as a function with a default name
def openssh(name="openssh", extra_deps=[], **overrides):
    autotools(name = name, deps = ["zlib", "openssl"] + extra_deps, **overrides)

openssh()  # registers "openssh" — module-core works standalone

# @vendor-bsp extends it with a different name
load("@module-core//units/openssh.star", "openssh")
openssh(name = "openssh-vendor", extra_deps = ["vendor-crypto"])

The downstream unit has a distinct name (openssh-vendor), so there is no collision with the upstream openssh. Images that need the vendor variant reference openssh-vendor in their artifacts list. This is explicit and traceable — grep for the function call to find all extensions. See metadata-format.md for details.

Recursive module dependencies

A module’s MODULE.star can declare its own deps = [...] list of modules. The loader walks this transitively — each declared module is synced, peeked for its own deps, synced again, and so on until the dep set stabilizes:

# module-bsp-imx8/MODULE.star
module_info(
    name = "bsp-imx8",
    deps = [
        module("https://github.com/yoebuild/module-alpine.git", ref = "v1.2"),
        module("https://github.com/vendor/imx8-firmware.git", ref = "main"),
    ],
)

A project consuming module-bsp-imx8 doesn’t need to re-declare module-alpine or imx8-firmware — they come along automatically.

Canonical identity and dedup

Two declarations of the same module collapse to one:

• Remote modules: same (URL, ref, path) triple — .git suffix is stripped before comparing, so https://github.com/foo/bar and https://github.com/foo/bar.git are the same module.
• Local modules: the absolute path after filepath.EvalSymlinks — two relative paths that resolve to the same directory dedup.

Same-name conflicts

When two declarations name the same module (module_info(name = "shared")) but resolve to different identities, the project-level declaration always wins — the transitive declaration is silently overridden. Two transitive declarations at incompatible refs error with both reference paths and a hint to pin one explicitly at the project level.

Cycle detection

The loader runs DFS over the dep graph and surfaces any cycle as a clear path in the error: module dep cycle: A → B → C → A. Self-loops report the same way (A → A).

Feeds as synthetic modules

A feed is a third kind of module entry, alongside directory (local override) and remote (git clone). It absorbs an upstream package repo as a single declaration whose units materialize lazily on demand.

Two feed builtins exist: alpine_feed(...) for Alpine’s apk archive and apt_feed(...) for the apt/dpkg family (Debian and Ubuntu share it, picked apart by the distro kwarg):

# module-alpine/MODULE.star
module_info(name = "alpine")

alpine_feed(
    name    = "main",                    # synthetic module is alpine.main
    url     = "https://dl-cdn.alpinelinux.org/alpine",
    branch  = "v3.21",
    section = "main",
    index   = "feeds/main",              # dir holding <arch>/APKINDEX
    keys    = ["keys/alpine-devel@lists.alpinelinux.org-6165ee59.rsa.pub"],
)

# module-ubuntu/MODULE.star
module_info(name = "ubuntu")

apt_feed(
    name      = "main",                  # synthetic module is ubuntu.main
    distro    = "ubuntu",                # stamped on every materialized unit
    url       = "http://archive.ubuntu.com/ubuntu",
    arch_urls = {"arm64": "http://ports.ubuntu.com/ubuntu-ports"},
    suite     = "resolute",
    component = "main",
    arches    = ["amd64", "arm64"],
    index     = "feeds/main",            # dir holding <arch>/Packages
    keyring   = "keys/ubuntu-archive-keyring.gpg",
)

Each call registers a synthetic module named <parent>.<feed> (e.g., alpine.main, alpine.community). The resolver consults synthetics in priority order alongside real modules, but synthetics always rank below every non-feed module — a from-source override in module-core wins against the feed automatically without prefer_modules.

The on-disk APKINDEX is checked into the module repo. yoe update-feeds refreshes it from upstream, verifying the RSA-SHA1 signature against alpine_feed(keys=[...]) before writing. See module-alpine.md for the maintainer workflow.

Lazy materialization

Synthetic units don’t allocate up front — SyntheticModule.Lookup(name) runs only when the closure walk references that name. A project pulling 300 packages from a 60k-entry feed allocates 300 *Unit pointers, not 60k. The on-disk APKINDEX cache (header-versioned, content-keyed) keeps re-parse times under ~300ms even for the full Debian-class case.

See Catalog and Materialization for the internal data structures and lifecycle that back this — the SyntheticModule contract, the closure walker’s role as materialization driver, working-set sizes per feed, and the allocation invariants the resolver depends on.

Companion units (the enable-service pattern)

A feed gives you every package’s .apk but doesn’t enable services — Alpine ships init scripts disabled (apk’s setup-<pkg> is a human helper, and yoe has no humans on the image-assembly path). The convention is one tiny companion unit per service the maintainer wants to expose:

# module-alpine/units/docker-enable.star
unit(
    name = "docker-enable",
    version = "0.1.0",
    runtime_deps = ["docker-openrc"],   # ships /etc/init.d/docker
    services = ["docker"],              # → /etc/runlevels/default/docker
)

The companion has no tasks. The build executor falls through to the apk-build path when services = [...] is non-empty so the runlevel symlink lands in the package’s data tar. A project that wants Docker running adds docker-enable to its image’s artifacts list (alongside docker itself, which the unit’s runtime_deps will pull in).

This keeps the policy where it belongs: the package author — not the image, not the project — decides whether installing the package also enables it. See CLAUDE.md “Key Design Decisions” → “Units declare their own services” for the rationale.

Collision Detection

Unit name duplicates

Within a single module (or within the project root), defining two units with the same name is a hard error at evaluation time:

unit "zstd" already defined (first defined in module "module-core")

Across modules, a same-named unit is treated as a shadow: the higher-priority unit wins, the lower-priority one is dropped from the unit map, and a notice is emitted to stderr. Priority is project root > last module in the list > … > first module in the list. See Unit replacement via name shadowing.

ctx.provides duplicates

If two units from the same module provide the same virtual name, the build errors. If two units from different modules provide the same virtual name, the higher-priority module (later in the module list) wins and a notice is emitted to stderr. The active set is scoped to the selected machine — units from unselected machines do not participate. This allows multiple machines to each provide linux via different kernel units without conflict:

# machine/raspberrypi4.star — only active when this machine is selected
machine(name = "raspberrypi4",
    kernel = kernel(unit = "linux-rpi4", provides = "linux"))

# machine/beaglebone.star — only active when this machine is selected
machine(name = "beaglebone",
    kernel = kernel(unit = "linux-bb", provides = "linux"))

# base-image.star — "linux" resolves to whichever kernel the selected machine provides
image(name = "base-image", artifacts = ["busybox", "linux", "openssh"])

Images reference provides names directly — no prefix or namespace. The image declares what should be installed; resolution handles where it comes from.

Projects as module scoping

A project defines which modules are active for a build. Only units from included modules participate in the DAG. This is the primary mechanism for controlling which units can override or conflict with each other — if a module isn’t in the project’s module list, its units don’t exist for that build.

This reduces the collision problem: instead of needing replaces or shadow semantics, a project simply includes only the modules it needs. A vendor module that provides its own openssh-vendor with provides = ["openssh"] works cleanly when the project doesn’t include a second module that also provides openssh.

A single repository may define multiple projects (similar to KAS YAML files in yoe-distro), each selecting a different subset of modules for different products or build configurations:

# projects/dev.star
project(
    name = "dev",
    modules = [
        module("...", path = "modules/module-core"),
        module("...", path = "modules/dev-tools"),
    ],
)

# projects/customer-a.star
project(
    name = "customer-a",
    modules = [
        module("...", path = "modules/module-core"),
        module("...", path = "modules/vendor-bsp"),
        module("...", path = "modules/customer-a"),
    ],
)

The --project flag selects a project file: yoe --project projects/customer-a.star build. It is available on all subcommands. When omitted, yoe uses PROJECT.star at the repo root.

A default project (PROJECT.star at the repo root) can delegate to another project using standard Starlark load(). Two cases:

Use a project as-is — load it for the side effect (its project() call registers the project):

# PROJECT.star
load("projects/customer-a.star")

Extend a project with additional modules — load the exported module list and build on it:

# projects/customer-a.star
MODULES = [
    module("...", path = "modules/module-core"),
    module("...", path = "modules/vendor-bsp"),
    module("...", path = "modules/customer-a"),
]

project(name = "customer-a", modules = MODULES)

# PROJECT.star
load("projects/customer-a.star", "MODULES")

project(
    name = "default",
    modules = MODULES + [
        module("...", path = "modules/dev-tools"),
    ],
)

This lets a developer run yoe build without specifying --project while keeping per-product project definitions separate. No new concepts needed — Starlark’s load() handles composition naturally.

Per-project APK repo

The APK repo is scoped per project. If two projects share a single repo (e.g., one uses systemd, the other busybox-init), switching projects would leave stale packages in the APKINDEX. Since apk resolves runtime dependencies from the index, it could transitively pull in packages from the wrong project.

Build output is scoped as:

repo/<project>/APKINDEX.tar.gz

Each project gets a clean repo containing only packages from its resolved module and unit set. Individual unit builds are still cached by content hash — if two projects build the same unit with the same inputs, the build runs once and the resulting apk is placed into both project repos.

The build cache handles provides swapouts automatically: each unit’s cache key includes the hashes of its resolved dependencies (recursively). When init resolves to systemd in one project but busybox-init in another, any unit that depends on init gets a different cache key because the resolved dependency’s hash differs. No special virtual-name logic is needed in the hasher — it just hashes the resolved unit, not the virtual name string.

Catalog and Materialization

This page describes yoe’s in-memory unit catalog — the runtime data structure that holds every unit a project knows about, how units enter that structure (eagerly or lazily), and how the catalog is queried during the build. It is the resolver’s address book: the closure walker and the build executor both ask the catalog the same question — “give me the Unit for this name in this context” — and the catalog’s design governs how that answer is computed.

For the user-facing surface (what unit(), image(), alpine_feed(), and prefer_modules look like in Starlark) see metadata-format.md and naming-and-resolution.md. This page is the internals view: storage shapes, lifecycle, allocation cost, and the invariants the resolver relies on.

Terminology

A handful of terms recur throughout this page. They’re defined here so the body sections can use them without re-introducing each one.

Unit. The yoe representation of one buildable artifact — a *Unit struct holding name, version, runtime/build deps, source URL, container choice, install task, distro tag, and so on. Created either by a .star builtin (unit(...), image(...), container(...), …) or by a synthetic feed’s materialization callback.

Closure. The transitive runtime-dependency set of an image — the set of every unit reachable from the image’s artifacts = [...] list by following RuntimeDeps edges. If unit A runtime-depends on B and B on C, then C is in A’s closure. Term borrowed from graph theory (the transitive closure of a binary relation) and from the Nix/Guix package-manager tradition that uses it for the same concept.

Synthetic module. A registration in the catalog that names a feed (alpine.main, debian.main, …) and provides a Lookup(name) → *Unit callback. The callback runs only when something asks for a name the feed exposes — registration is eager (one call per alpine_feed() / apt_feed() in MODULE.star), but per-name *Unit allocation is lazy.

Materialization. The act of allocating a *Unit for a name a synthetic module exposes. A synthetic’s Lookup parses the upstream catalog entry (Alpine APKINDEX or Debian Packages), builds dep tokens, constructs the *Unit, and returns it. The walker then registers it into UnitsByModule and updates the affected DistroViews entries.

BFS (breadth-first search). The traversal algorithm the closure walker uses: maintain a queue, dequeue from the front, enqueue each visited unit’s RuntimeDeps at the back, mark visited names in a seen set so cycles don’t loop. Chosen over recursive depth-first because the queue keeps the working set bounded by closure size, not dep-tree depth — a deeply nested transitive chain can’t blow the call stack.

Provides resolution. Replacing a virtual name in a deps list (linux, toolchain, init) with the concrete unit that satisfies it (linux-rpi4, toolchain-debian-13, busybox-init). Driven by the project’s Provides map plus per-distro filtering (a provides entry tagged for a different distro is invisible to the lookup).

Distro view. A precomputed table DistroViews[distro][name] → *Unit populated once at the end of the loader’s evaluation phase. Maps every name reachable in any image’s closure to the winner of the per-distro resolution (filter by distro tag → apply prefer_modules pin → apply module priority). Consumers query through LookupUnit which reads this map in O(1).

Three classes of units

Every Unit in the catalog falls into one of three categories. They differ in when they enter the catalog and what the catalog actually stores.

Source-declared real units. A .star file in a module’s units/ directory calls unit(...), image(...), machine(...), container(...). The builtin handler allocates a *Unit, fills its fields from the call’s kwargs, and registers it eagerly during evaluation. Source-declared units are present in the catalog by the end of the loader’s evaluation phase, regardless of whether any image references them.

Synthetic units (feed-materialized). A MODULE.star calls alpine_feed(...) or apt_feed(...). The builtin does NOT allocate one *Unit per upstream package; it registers one SyntheticModule with a Lookup(name) → *Unit callback. The 60k-entry upstream index sits parsed-but-unmaterialized on disk and in a single archCache struct. A *Unit for a specific name appears in the catalog only when something asks for it (see Lazy materialization).

Virtual references. A unit’s provides = ["toolchain"] registers the name toolchain as an alias for the providing unit’s canonical name. Virtuals are not separate *Unit entries — they’re entries in Project.Provides (a map[string]string) that the resolver walks once at lookup time. A reference to "toolchain" in a class’s container = "toolchain" resolves to whichever unit currently provides it (see virtual packages).

Storage shape

The catalog has two layers: a primary store keyed by source module, and a set of precomputed per-distro views that consumers actually query.

type Engine struct {
    unitsByModule    map[string]map[string]*Unit  // [module][name]*Unit
    syntheticModules []*SyntheticModule
    project          *Project
    ...
}

type Project struct {
    UnitsByModule    map[string]map[string]*Unit  // primary storage; shared with Engine
    DistroViews      map[string]map[string]*Unit  // [distro][name]*Unit; precomputed
    Provides         map[string]string
    SyntheticModules []*SyntheticModule
    ...
}

UnitsByModule is the primary store. Every Unit registration — eager from .star evaluation, lazy from a SyntheticModule.Lookup return — lands under its source module. Cross-module same-name registrations coexist; module-core’s openssl and alpine.main’s openssl live in separate buckets and never overwrite each other.

DistroViews is what consumers query. Built once at the end of the loader’s evaluation phase via buildDistroViews(proj). For each distinct unit name across the project and for each distro the project sees, the loader runs a three-step resolution:

1. Filter the candidate pool to units in UnitsByModule[*][name] whose Distro is "" (visible to every distro) or matches the target distro. Cross-distro entries are eliminated structurally.
2. Pin — if prefer_modules[name] names a module still among survivors, that module’s variant wins. Pins are hints, not guarantees: a pin that names a module the distro filter eliminated falls through to step 3 with a diagnostic.
3. Priority — pick the survivor from the highest-priority module. Project root outranks every external module; later-declared external modules outrank earlier-declared ones; every synthetic (feed-materialized) module ranks below every real module. The “synthetics rank below reals” rule means a from-source override in module-core automatically beats a same-named feed entry, without needing a prefer_modules pin to make it so.

The result is DistroViews[distro][name] → *Unit. Read-only after construction. The closure walker, build executor, and any other consumer with distro context call:

func (p *Project) LookupUnit(distro, name string) *Unit {
    return p.DistroViews[distro][name]
}

— a single map access. Consumers without distro context (TUI list-all, source workspace) iterate via AllUnits(), an iter.Seq2[string, *Unit] over UnitsByModule that yields every registered unit. For same-name units across modules, AllUnits() yields each separately; the caller decides what to do with the collision.

Distro is a visibility filter; module is the priority axis. Two orthogonal concerns. The catalog’s job is to keep them separate: storage keys by module (the source-of-truth label), the views slice by distro (the runtime-compatibility class). This preserves the “module-core wins by default” semantics — module-core’s source-built openssl wins for any image’s openssl lookup because module-core is the highest-priority module — while letting alpine.main’s libcap2 and debian.main’s libcap2 coexist in separate candidate pools, each visible only to closures of its own distro.

Diagnostics-not-mutation. Shadowing within a distro view is observable but not visible in DistroViews itself: the loser is dropped from the view and the collision is recorded in Project.Diagnostics.Shadows for the TUI to surface. This is intentional — DistroViews is the resolved state; the journey is in Diagnostics. The same applies to a prefer_modules pin that fell through because its module was distro-filtered out: the diagnostic records the fallthrough so the user can see why their pin didn’t take effect.

Lazy materialization

Where it starts

Materialization is triggered by image evaluation. The loader walks every images/*.star file across the project root and every loaded module; each image(...) call invokes resolve_closure(artifacts, distro=...) with its own artifacts list and effective distro. So a project with five images defined across its modules triggers five closure walks during load — not one per build, but one per image found at evaluation time. A representative debian image:

image(
    name = "debian-base-image",
    distro = "debian",
    artifacts = ["apt", "openssh-server", "linux-image-amd64"],
)

invokes resolve_closure(["apt", "openssh-server", "linux-image-amd64"], distro="debian"). The Go-side builtin takes the artifacts list as the roots of a breadth-first walk through the runtime-dep graph; every name visited triggers a lookup, and lookups that miss the catalog drive materialization.

Materializations don’t repeat across closures. If three alpine images all reference openssh-server, the synthetic Lookup fires once (during the first image’s walk); the other two walks read the cached *Unit from DistroViews["alpine"]["openssh-server"]. The cost is union-of-closures, not sum-of-closures.

What doesn’t trigger materialization:

• Modules listed in PROJECT.star but containing no images.
• Names that exist in upstream catalogs but aren’t reached from any image’s closure (the 50,000-entry Debian main catalog parses to the archCache once, but only the few hundred names reached by some image’s closure ever become *Unit objects).
• A feed type the project doesn’t use — a project that declares module-debian but defines no debian image (and no alpine image pulls in a debian-tagged name through provides) parses the debian Packages file the first time some Lookup references it, which for a no-debian-image project never happens. The feed is registered eagerly; everything beyond registration is gated on actual use.

The materialization cycle, step by step

For each name dequeued from the BFS frontier:

1. Resolve provides. If the name is a virtual like toolchain, ResolveProvidesForDistro(distro, name) substitutes the concrete providing unit’s name (e.g. toolchain-debian-13 for distro=debian).
2. Check the view. LookupUnit(distro, resolved) reads DistroViews[distro][resolved]. Hit → return the existing *Unit, no allocation. (This is the common case after the first walk visits a name.)
3. Walk synthetics on miss. Visit each SyntheticModule in priority order. For each, call sm.Lookup(resolved).
4. First synthetic that has the name materializes it. Inside sm.Lookup:
   • Pick the active arch (e.g. x86_64 → debian arch amd64).
   • Load the archCache if it’s not loaded yet — this is the one-time ~50–150ms parse of feeds/<section>/<arch>/APKINDEX or feeds/<section>/<arch>/Packages from disk into a []Entry plus a byName map.
   • Look up resolved in the byName map. Miss → return nil; the walker continues to the next synthetic. Hit → continue.
   • Call MaterializeUnit(entry, providers, moduleName). This parses the upstream Depends: / depends: list, runs each token through the project-wide provides table (cross-feed via multiFeedProviders for Debian), and constructs one *Unit with its RuntimeDeps, Provides, Replaces, etc. filled in.
   • populateBuildFields adds the build-transport metadata: the upstream URL, the PassthroughAPK / PassthroughDeb filename, the toolchain container, the install task that extracts the archive into $DESTDIR, and the unit’s Distro tag.
   • Return the *Unit.
5. Register and update views. The walker stores the returned *Unit under UnitsByModule[<module>][resolved] and updates the affected DistroViews[*][resolved] entries (only views for distros the unit is visible to — debian-tagged units land in DistroViews["debian"], untagged units land in every view).
6. Push runtime-deps onto the queue. Each name in the new unit’s RuntimeDeps goes onto the back of the BFS queue. Already-visited names (in a seen set) are skipped so cycles don’t loop.

Repeat until the queue is empty. Then topologically sort the visited set so deps come before dependents, and hand the result to the DAG builder.

Why “lazy”

The synthetic feeds are registered eagerly during module evaluation — one alpine_feed() or apt_feed() call per repo section. But each call only registers the SyntheticModule (a name + a Lookup callback + the in-tree APKINDEX / Packages path); no *Unit structures exist yet. The 50,000-entry Debian catalog is on disk as text and in the archCache after first parse, but the resolver allocates *Unit objects only for names the closure actually references.

This dual structure — module-keyed storage plus precomputed per-distro views — keeps the lookup-time path O(1) without sacrificing the laziness story. Materialization happens on first reference; disambiguation (which feed’s variant wins for which distro) is resolved once during view construction, not on every lookup.

Scale

The materialization pass gives the resolver a O(closure size) working set against an upstream index that can be much larger:

The archCache (per-arch, per-feed) parses the on-disk APKINDEX / Packages once on first Lookup call (~150ms for Debian’s main; ~50ms for Alpine’s), holds the parsed entries in a []Entry plus a name index (map[string]*Entry), and serves every subsequent lookup from the cache. Per-process parse cost is bounded by the number of active arches × feeds; allocation is paid only for names actually consumed.

Allocation cost per materialization is the price of one MaterializeUnit call: parse the upstream Depends: / depends: list into yoe’s dep tokens, look up each token through the provides table (which crosses sibling feeds for Debian — multiFeedProviders), construct one *Unit and its Tasks / Source fields, return. This is the cost the resolver pays at first reference of each name; the returned pointer is then catalog-stable.

The SyntheticModule contract

The Lookup callback the cycle calls is supplied by whichever feed builtin registered the synthetic module (alpine_feed or apt_feed). The shape:

type SyntheticModule struct {
    Name     string             // composed name, e.g. "alpine.main"
    Parent   string             // owning module, e.g. "module-alpine"
    Priority int                // negative; below every real module
    Lookup   func(name string) (*Unit, error)
    Names    func() []string    // enumeration for diagnostics/TUI
}

The walker doesn’t know or care which format a synthetic wraps — APK indexes, Debian Packages files, or anything else a future feed type adds. It just calls Lookup and trusts the contract: return a fully-populated *Unit for known names, return nil for misses, return an error only for genuine failures (corrupt index, missing arch).

One Lookup per name is load-bearing. The materialization path allocates fresh *Unit structures and triggers a Provides parse; calling Lookup for every synthetic on every name — to probe for a tagged variant before falling back — pays that cost for names the walker would discard. Multiplied across a closure walker’s quadratic topological iteration, this allocates and throws away *Unit structures unboundedly. The catalog’s precomputed-views design exists specifically to avoid this: disambiguation lives in the view construction at load time, where each name is resolved exactly once; the walker never re-resolves the same name twice.

The closure walk as materialization driver

resolve_closure(artifacts, distro=...) is a Go-side Starlark builtin (fnResolveClosure in internal/starlark/closure.go, registered as a builtin in internal/starlark/builtins.go). Image classes call it from Starlark — modules/module-core/classes/image.star invokes it with the image’s effective distro and its artifacts = [...] list. The Go implementation drives lazy materialization. For each invocation, the closure walker:

1. BFS the runtime-dep graph rooted at the artifact names. For each name dequeued:

   • Resolve provides through ResolveProvidesForDistro(distro, name).
   • LookupUnit(distro, resolved) returns the *Unit from DistroViews[distro][resolved]; on a miss, the synthetic walk fires and registers the result before returning.
   • Push the returned unit’s RuntimeDeps onto the back of the queue.

2. Topological sort of the visited set. Emits units in dependency order so the DAG builder can validate edges and the build executor can schedule producers before consumers.

By the time the closure walker returns its ordered name list, DistroViews[distro] contains every name the image actually needs for its closure. The DAG builder (internal/resolve/dag.go) walks these names again via LookupUnit, constructs edges from Unit.Deps, Unit.Artifacts, and container references, and hands the executor the topologically-sorted plan.

The closure walker runs once per image during evaluation. Its output is cached for the build executor; it does not run again between yoe build and yoe deploy. Mutation of UnitsByModule is bounded by the number of synthetic-unit names actually referenced across all images; mutation of DistroViews is bounded by the same set times the number of distinct distros the project targets.

Hashing and the distro axis

Once units are in the catalog, each one’s build output is content- addressed by a hash over (a) the unit’s metadata, (b) the hashes of its build-time dependencies (recursively), (c) source inputs (commit sha / tarball digest), and (d) the consuming image’s effective distro. The hash is computed in internal/resolve/hash.go’s UnitHash, called per-image with the image’s effective distro.

An image’s effective distro is resolved through a three-level cascade: the image’s own distro = "..." field wins if set; otherwise the project’s local.star default_distro_override (per-developer, not committed) wins if set; otherwise the project’s defaults.distro in PROJECT.star is used; if none of the three is set the image errors at evaluation. The cascade lets a developer experiment with a different distro locally without editing committed configuration.

Including effective distro in the hash gives every source-declared unit the build-twice-along-the-libc-axis property: a single source unit (module-core/openssl) builds once in toolchain-musl for an alpine image and once in toolchain-debian-13 for a debian image, producing two distinct binary outputs with two distinct cache entries. The catalog stores one *Unit (in UnitsByModule["module-core"]["openssl"]); the build artifacts live under per-distro paths on disk (build/alpine/openssl.target/ vs build/debian/openssl.target/); the hash key disambiguates the cache entries so a debian build never reads back a musl-linked binary the alpine build produced.

For feed-materialized units, the Distro field on the materialized *Unit is set by the feed ("alpine" for alpine_feed, "debian" for apt_feed); the unit’s hash naturally differs across distros because the unit itself differs. For untagged source-built units, the consumer’s effective distro is what disambiguates — the unit definition is the same, but the cache key isn’t.

Working set in practice

A representative measurement from the e2e-project (alpine-only, qemu-x86_64, base-image with the standard module set):

• Source-declared real units registered during load: ~80 across module-core (busybox, openssl, openssh, kernel, etc.), module-bsp, module-jetson, and the project root. These land in UnitsByModule["module-core"], UnitsByModule["module-bsp"], etc.
• Synthetic modules registered: ~5 (alpine.main, alpine.community, debian.main when listed). Each is one *SyntheticModule struct plus a per-arch archCache that’s loaded lazily.
• Synthetic units materialized by the closure walk: ~150 from alpine.main, ~0 from alpine.community (community is registered but rarely consumed in the e2e closure).
• Total *Unit entries across UnitsByModule[*][*] after evaluation: ~230.
• DistroViews["alpine"] size after view construction: ~230 (every visible unit is reachable in some closure).
• Total Go heap held by Engine post-evaluation: low tens of MB (units + provides + synthetic module struct + per-arch archCache for one arch + the precomputed views, which are pointer maps not unit copies).

The catalog is small enough that storage shape is not a memory or speed concern; the structural property the design buys is correctness of cross-distro disambiguation, not scale.

Lifecycle and persistence

The catalog lives entirely in memory and is rebuilt from scratch on every yoe invocation. Understanding what survives between processes and what doesn’t tells you when you can edit something and have it take effect, and when you have to restart.

Per-invocation: everything in memory is fresh

A yoe invocation — yoe build, yoe deploy, yoe dry-run, yoe tui, yoe update-feeds, … — is a fresh process. The Engine struct, the archCache, the materialized *Unit pointers, UnitsByModule, DistroViews, the Provides map — all are constructed during loader evaluation and discarded when the process exits.

So every invocation re-runs the loader in this order:

1. Module discovery. Parse PROJECT.star, resolve modules = [...] to clone paths, evaluate each MODULE.star in priority order.
2. Eager registration. Classes (classes/*.star), source-declared units (units/*.star), machines (machines/*.star), and synthetic modules (each alpine_feed(...) / apt_feed(...) call) all register during this phase. No archCache parse yet — the feed builtin only stores the on-disk index path and the callback.
3. Image evaluation. Every image(...) call in every module fires resolve_closure(artifacts, distro=...), which drives BFS through the runtime-dep graph. The first time a feed’s Lookup runs, its archCache parses the on-disk APKINDEX or Packages file (~50–150ms one-time). Subsequent lookups against the same feed are cheap map accesses.
4. Distro views. buildDistroViews(proj) runs once at the end of evaluation, filtering / pinning / priority-ranking per name per distro, producing the read-only DistroViews map.
5. The actual command. Build executor, deploy, TUI render — all read from the now-frozen catalog through LookupUnit and AllUnits.

What survives between invocations

The in-memory catalog rebuilds every time, but several on-disk caches make that rebuild cheap on the second-and-later invocations:

• Build cache. build/<unit>.<scope>/destdir/ plus the content-addressed apk/deb output per unit. The build executor hashes each unit’s inputs (source digest, dep hashes, effective distro) and re-uses any matching cache entry. A second yoe build with no source changes finishes in seconds because nothing actually compiles.
• Source cache. Downloaded tarballs and git clones under cache/sources/. A unit’s source is fetched once per (URL, ref) tuple.
• Module cache. External modules cloned under cache/modules/. A yoe build does a git fetch and resets to the pinned ref but doesn’t re-clone.
• Feed indexes. APKINDEX for Alpine, Packages for Debian — both live as plain text inside the module repos (module-alpine/feeds/<section>/<arch>/APKINDEX, module-debian/feeds/<section>/<arch>/Packages). These are refreshed only by yoe update-feeds; ordinary builds read what’s checked in.

So every invocation re-parses these on-disk files into the in-memory archCache, but the underlying data isn’t regenerated unless you explicitly run update-feeds.

Reload semantics

There is no in-process reload API. The archCache and DistroViews are computed once per process by design — making the in-memory state authoritative for the lifetime of the process avoids race conditions between “what the resolver thinks” and “what’s on disk.” If the resolver could re-read the catalog mid-run, a build executor partway through a closure could find names resolving differently than they did at the start of the build, a class of bug worth avoiding structurally rather than handling explicitly.

For one-shot commands (yoe build, yoe deploy, yoe dry-run, etc.), each invocation is a fresh process; any edit to any .star or feed index is picked up on the next command automatically. For long-running surfaces (the TUI, or a future daemon), a restart is required after any change that affects what the catalog contains — see Restarting after edits in the yoe-tool guide for the change-vs-restart table.

Invariants the resolver relies on

The catalog’s contract to the rest of the system:

• Pointer stability after registration. Once a *Unit enters UnitsByModule, the pointer doesn’t change. The DAG builder, the executor, the TUI, and the diagnostics layer all hold pointers into this map and assume they continue to point at the same Unit. DistroViews entries are aliases of the same pointers, so view reads are pointer-stable too.
• One Lookup per name per project. The lazy materialization path pays the per-call cost (provides parse, dep parse, struct alloc) exactly once per name across the entire project; subsequent references — from any closure walk, any image — hit the cached pointer via DistroViews.
• Synthetic registration is module-priority-ordered. The first SyntheticModule registered against an engine gets the highest synthetic priority (Priority = 0); each subsequent one is one step lower. All synthetics rank strictly below every real module.
• View construction is single-pass. buildDistroViews runs once at the end of the loader’s evaluation phase, after every module has finished registering and prefer_modules has been validated. Mutation of DistroViews after that point is bounded by lazy materialization registering new entries; the resolution rules used for the initial pass are the same rules used for late-materialized entries, so the view stays consistent.
• Empty Unit.Distro means “compatible with every distro.” An untagged unit appears in the candidate pool for every distro’s view; tagged units appear only in their matching distro’s pool. This is what lets module-core source builds serve both alpine and debian images from a single Unit definition while feed-materialized units stay scoped to their feed’s distro.
• Distro is a property of the Unit; module is a property of the registration. Two orthogonal axes the catalog deliberately keeps separate. The Unit’s Distro field decides which views it appears in; the registering module decides where it lives in UnitsByModule and its priority weight in view construction.

These invariants are what let the resolver run the closure walker with a single map access per name, hold a small working set, and support cross-distro coexistence without rebuilding storage on every lookup.

File Templates

Move inline file content out of Starlark units into external template files processed by Go’s text/template. A unified map[string]any context serves as both the template data and the hash input — one source of truth.

Problem

Units currently embed multi-line file content as heredocs inside shell step strings. This is hard to read, hard to edit, and prevents tools (syntax highlighters, linters) from understanding the embedded content.

Examples of inline content today:

• base-files.star — inittab, os-release, extlinux.conf
• network-config.star — udhcpc default.script, OpenRC network init script
• image.star — sfdisk partition tables, extlinux install scripts

Design

Template Files

Templates live in a directory named after the unit, alongside the .star file:

modules/module-core/
  units/
    base/
      base-files.star
      base-files/                # same name as the unit
        inittab.tmpl
        os-release.tmpl
        extlinux.conf.tmpl
    net/
      network-config.star
      network-config/
        udhcpc-default.script
        network                  # OpenRC service script
      simpleiot.star
      simpleiot/
        simpleiot.init

Files without .tmpl extension are copied verbatim via install_file(). Files with .tmpl are processed through Go’s text/template via install_template().

Unit Context (map[string]any)

A single map[string]any is used for both template rendering and hash computation. The executor auto-populates standard fields, and any extra kwargs passed to unit() are captured into the same map. No separate vars field — just add fields directly to the unit:

unit(
    name = "my-app",
    version = "1.0.0",
    port = 8080,
    log_level = "info",
    debug = True,
    ...
)

Templates access all fields: {{.port}}, {{.log_level}}, {{.name}}.

Auto-populated fields (injected by the executor, not declared in the unit):

Unit kwargs override auto-populated fields if there’s a name collision (explicit wins).

Go implementation: registerUnit() captures all unrecognized kwargs into a map[string]any on the Unit struct. The executor merges auto-populated fields (lower priority) with unit fields (higher priority) to build the context map. Classes pass **kwargs through to unit(), so custom fields flow naturally:

autotools(
    name = "my-lib",
    version = "1.0",
    source = "...",
    custom_flag = "enabled",  # flows through **kwargs to unit()
)

Template Syntax

Go text/template with the unit context map:

# inittab.tmpl
::sysinit:/sbin/openrc sysinit
::sysinit:/sbin/openrc boot
::wait:/sbin/openrc default
{{.console}}::respawn:/sbin/getty -L {{.console}} 115200 vt100
::ctrlaltdel:/sbin/reboot
::shutdown:/sbin/openrc shutdown

# os-release.tmpl
NAME=Yoe
ID=yoe
PRETTY_NAME="Yoe Linux ({{.machine}})"
HOME_URL=https://github.com/yoebuild/yoe

# config.toml.tmpl (custom vars)
[server]
port = {{.port}}
log_level = "{{.log_level}}"
debug = {{.debug}}

Starlark API

Two new builtins are step-value constructors, not side-effecting calls. They return a value that the build executor recognises and dispatches when the task runs, in the same step list as shell strings and Starlark callables:

# install_file(src, dest, mode=0o644) -> InstallStep
# Copies src verbatim from the unit's files directory to dest.

# install_template(src, dest, mode=0o644) -> InstallStep
# Renders src through Go text/template with the unit's context map, then
# writes the result to dest.

They are used directly in task(..., steps=[...]), no fn=lambda: wrapper required:

task("build", steps = [
    "mkdir -p $DESTDIR/etc $DESTDIR/boot/extlinux",
    install_template("inittab.tmpl", "$DESTDIR/etc/inittab"),
    install_template("os-release.tmpl", "$DESTDIR/etc/os-release"),
])

src paths are relative to the calling .star file’s template directory: <dir(file)>/<basename(file) without .star>/. For a call written in units/base/base-files.star, "inittab.tmpl" resolves to units/base/base-files/inittab.tmpl. Paths that escape that directory ("../../etc/passwd") are rejected.

Resolving relative to the call site — not to the resulting unit’s unit() call site — is what lets a helper function package its templates next to itself and reuse them across many units. For example, base_files() in units/base/base-files.star can be called from images/dev-image.star with name = "base-files-dev"; the install steps it returns still find their templates in units/base/base-files/, not in images/base-files-dev/.

dest has environment variables ($DESTDIR, $PREFIX, etc.) expanded from the task’s build environment. Unknown variables expand to the empty string — there is no fallback to the host process environment, to preserve reproducibility.

Install steps are pure data — install_template(...) can be bound to a name, stored in a list, or generated from a helper function before being placed in steps=[...]. They evaluate at unit-load time; execution happens later, in the executor, when the step is reached.

Example: base-files with templates

Before (inline heredocs):

task("build", steps=[
    "mkdir -p $DESTDIR/etc",
    """cat > $DESTDIR/etc/inittab << INITTAB
::sysinit:/bin/mount -t proc proc /proc
::sysinit:/bin/hostname -F /etc/hostname
${CONSOLE}::respawn:/sbin/getty -L ${CONSOLE} 115200 vt100
::ctrlaltdel:/sbin/reboot
::shutdown:/bin/umount -a -r
INITTAB""",
    """cat > $DESTDIR/etc/os-release << OSRELEASE
NAME=Yoe
ID=yoe
PRETTY_NAME="Yoe Linux ($MACHINE)"
HOME_URL=https://github.com/yoebuild/yoe
OSRELEASE""",
])

After (external templates):

base-files/inittab.tmpl:

::sysinit:/sbin/openrc sysinit
::sysinit:/sbin/openrc boot
::wait:/sbin/openrc default
{{.console}}::respawn:/sbin/getty -L {{.console}} 115200 vt100
::ctrlaltdel:/sbin/reboot
::shutdown:/sbin/openrc shutdown

base-files/os-release.tmpl:

NAME=Yoe
ID=yoe
PRETTY_NAME="Yoe Linux ({{.machine}})"
HOME_URL=https://github.com/yoebuild/yoe

unit(
    name = "base-files",
    version = "1.0.0",
    tasks = [
        task("build", steps = [
            "mkdir -p $DESTDIR/etc $DESTDIR/root $DESTDIR/proc $DESTDIR/sys"
                + " $DESTDIR/dev $DESTDIR/tmp $DESTDIR/run"
                + " $DESTDIR/boot/extlinux",
            install_template("inittab.tmpl", "$DESTDIR/etc/inittab"),
            install_template("os-release.tmpl", "$DESTDIR/etc/os-release"),
            install_template("extlinux.conf.tmpl",
                             "$DESTDIR/boot/extlinux/extlinux.conf"),
        ]),
    ],
)

Example: simpleiot init script

simpleiot/simpleiot.init:

#!/sbin/openrc-run
command="/usr/bin/siot"
command_background="yes"
pidfile="/run/simpleiot.pid"

depend() {
    need net
}

go_binary(
    name = "simpleiot",
    version = "0.18.5",
    services = ["simpleiot"],
    tasks = [
        task("build", steps = [...]),
        task("init-script", steps = [
            "mkdir -p $DESTDIR/etc/init.d",
            install_file("simpleiot.init",
                         "$DESTDIR/etc/init.d/simpleiot", mode = 0o755),
        ]),
    ],
)

Example: custom app with extra fields

unit(
    name = "my-app",
    version = "2.0.0",
    port = 8080,
    workers = 4,
    enable_tls = True,
    tasks = [
        task("config", steps = [
            "mkdir -p $DESTDIR/etc/my-app",
            install_template("app.conf.tmpl", "$DESTDIR/etc/my-app/app.conf"),
        ]),
    ],
)

my-app/app.conf.tmpl:

# Generated by Yoe for {{.machine}}
listen_port = {{.port}}
workers = {{.workers}}
{{if .enable_tls}}tls_cert = /etc/ssl/certs/ca-certificates.crt{{end}}

Hashing

The unit context map (map[string]any) is JSON-serialized with sorted keys and included in the unit hash. This means:

• Changing any unit field changes the hash and triggers a rebuild
• Auto-populated fields (arch, machine) already affect the hash through existing mechanisms, but including them in the context map makes it explicit
• No separate hash logic needed for template fields vs build fields

Additionally, all files in the unit’s files directory (<DefinedIn>/<unit-name>/) are hashed by content. Changing a template file changes the hash.

Path Resolution

Template paths resolve to <DefinedIn>/<unit-name>/<relPath>:

func resolveTemplatePath(unit *Unit, relPath string) string {
    return filepath.Join(unit.DefinedIn, unit.Name, relPath)
}

This matches the existing container convention:

Go Implementation

Install steps are pure data values produced at Starlark evaluation time and executed by the build executor. There is no thread-local wiring, no placeholder builtins, and no “must be called inside a task fn” error path — they’re third-class steps alongside shell strings and Starlark callables.

New file: internal/build/templates.go

• BuildTemplateContext — build the per-unit map[string]any from unit identity fields, Extra, and auto-populated arch/machine/console/project
• doInstallStep — execute a resolved InstallStep against a unit: read from <DefinedIn>/<unit-name>/<src>, render (if template) or copy, write to expanded dest
• resolveTemplatePath — resolve <DefinedIn>/<unit-name>/<relPath> with escape protection
• expandEnv — expand $DESTDIR etc. in destination paths using the task’s build env (no host fallback, for reproducibility)

Custom Go template functions (e.g. sizeMB, sfdiskType) are out of scope for this spec and belong to the starlark-packaging-images work that migrates image.star partition templates.

Modified: internal/starlark/builtins.go

• Register install_file and install_template as ordinary global builtins that return *InstallStepValue. No placeholder-delegate pattern needed — they have no side effects.
• Capture unrecognized unit() kwargs into Extra map[string]any on the Unit struct.

Modified: internal/starlark/types.go

• New InstallStepValue — a starlark.Value implementation carrying (Kind, Src, Dest, Mode). Frozen on construction; implements Hash so tasks containing install steps are deterministic.
• New InstallStep — Go-native mirror of the above, referenced by Step.
• Step gains an Install *InstallStep field.
• Unit gains an Extra map[string]any field.
• ParseTaskList recognises *InstallStepValue entries in steps=[...] and converts each to Step{Install: &InstallStep{...}}.

Modified: internal/build/executor.go

• Build a per-unit map[string]any template context via BuildTemplateContext.
• Task step loop gains a third case: step.Install != nil → doInstallStep(unit, step.Install, ctxData, env). Command and Fn cases are unchanged.

Modified: internal/resolve/hash.go

• JSON-serialize the context map (sorted keys) and include in the unit hash.
• Hash contents of all files in the unit’s files directory.

What is NOT needed (vs. an earlier side-effecting design)

• No thread-local TemplateContext key on the build thread
• No SetTemplateContext helper
• No placeholder/delegate builtins in internal/starlark/builtins.go
• No BuildPredeclared entries for install_file / install_template
• No fn=lambda: _install() boilerplate in unit files

What Stays in Go

Template rendering runs on the host (Go executor), not in the container. This keeps template data (machine config, unit metadata) accessible without passing it through environment variables. The rendered files are placed in the build directory, then the container mounts them.

Implementation Order

1. Extra field on Unit — capture unrecognized kwargs in registerUnit().
2. InstallStepValue + constructors — Starlark value type and the install_file / install_template global builtins. Pure, side-effect-free.
3. Step.Install + ParseTaskList dispatch — extend the Go Step type and recognise install-step values inside steps=[...].
4. Executor dispatch + doInstallStep — BuildTemplateContext, executor case for step.Install, and doInstallStep I/O. This step also removes the earlier thread-local wiring (TemplateContext thread key, SetTemplateContext) now that it is dead.
5. Hashing — include context map JSON (sorted keys) and files-directory contents in the unit hash.
6. Migrate base-files — inittab, os-release, extlinux.conf as install steps.
7. Migrate network-config — udhcpc script and network init script as install steps.
8. Migrate simpleiot — init-script task becomes a one-line install step.

Non-Goals

• Jinja2 or other template engines. Go text/template is in stdlib and sufficient.
• Template inheritance or includes. Keep templates flat and simple.
• Build-time template rendering in the container. Templates are rendered by the Go executor on the host.

Build & Configuration Languages

An analysis of embeddable languages for defining units, build rules, and project configuration in [yoe]. This informs the choice of how users express what to build and how to build it.

The Problem

[yoe] needs a way for users to define:

• Units — what to build, from what source, with what dependencies
• Classes/rules — how to build (autotools, cmake, go, image assembly)
• Project config — cache locations, remote repos, module references
• Machine definitions — architecture, kernel, bootloader, partitions
• Image definitions — package lists, services, hostname, partitions

The simplest approach is a data format (TOML/YAML) for all of these. But experience shows that pure data formats accumulate escape hatches as complexity grows: conditional dependencies, machine-specific overrides, image inheritance, shell commands embedded in strings. These are signs the data format wants to be a language.

Requirements

1. Simple for the common case — defining a package unit should be as readable as a TOML file
2. Composable — modules, overlays, and unit extensions without modifying originals
3. Expressive when needed — conditionals, loops, helper functions for complex build logic
4. Deterministic — same inputs always produce the same output (critical for content-addressed caching)
5. Sandboxed — build definitions cannot perform arbitrary I/O or network access
6. Go-native — embeddable in a Go binary without external dependencies
7. Familiar syntax — low learning curve for developers

Language Survey

Starlark

Used by: Bazel (Google), Buck2 (Meta), Pants, Gazelle

Starlark is a dialect of Python designed specifically for build system configuration. It is deterministic (no import os, no network, no randomness), hermetic, and embeddable. The Go implementation (go.starlark.net) is maintained by Google.

Example unit:

load("//classes/autotools.star", "autotools")

autotools(
    name = "openssh",
    version = "9.6p1",
    source = "https://cdn.openbsd.org/.../openssh-9.6p1.tar.gz",
    configure_args = ["--sysconfdir=/etc/ssh"],
    deps = ["zlib", "openssl"],
)

Strengths:

• Battle-tested at enormous scale (Google’s entire build, Meta’s mobile builds)
• Python-like syntax — most developers can read it immediately
• Deterministic by design — no side effects, no mutable global state
• Mature Go library with good documentation
• Functions and load() provide natural composition
• Built for exactly this use case

Weaknesses:

• No native data merging/overlay system (unlike Nix or CUE) — composition is through explicit function arguments
• Subtle differences from Python can trip up experienced Python developers (no class, no exceptions, no import, dict insertion order matters)
• The load() system adds a dependency resolution layer for build files themselves

Composability model: Function calls and macros. A base unit exports a configurable function; modules call it with overrides. Explicit but verbose:

# module-core/openssh.star — base unit as a function
def openssh(extra_deps=[], extra_configure_args=[], **overrides):
    autotools(
        name = "openssh",
        version = "9.6p1",
        deps = ["zlib", "openssl"] + extra_deps,
        configure_args = ["--sysconfdir=/etc/ssh"] + extra_configure_args,
        **overrides,
    )

# vendor-bsp/openssh.star — vendor module extends it
load("//module-core/openssh.star", "openssh")
openssh(extra_deps=["vendor-crypto"])

CUE

Used by: Dagger, various Kubernetes tooling

CUE is a configuration language created by Marcel van Lohuizen (who also created gofmt). Its defining feature is unification — you define partial configurations in separate files and CUE merges them, checking constraints automatically. Types and values exist on a single lattice; a type is just a constraint on a value.

Example unit:

openssh: {
    version: "9.6p1"
    deps: ["zlib", "openssl"]
    build: ["./configure --prefix=$PREFIX", "make -j$NPROC"]
}

Example overlay (separate file, merges automatically):

openssh: {
    deps: ["zlib", "openssl", "vendor-crypto"]
    configure_args: ["--with-vendor-crypto"]
}

Strengths:

• Closest to Nix-style composability — partial definitions in different files merge automatically without explicit imports
• Types-as-constraints provide built-in validation (version: =~"^[0-9]")
• Go-native implementation
• No Turing-completeness — guaranteed termination
• Excellent for data-heavy configuration

Weaknesses:

• Cannot express imperative build logic — no loops for generating targets, no calling external commands, no procedural steps
• Unusual paradigm (lattice-based unification) — steeper learning curve than expected for what looks like JSON
• Smaller ecosystem and community than Starlark
• Would need pairing with another language for class/rule logic

Composability model: Implicit merging via unification. Define parts in different files within the same package; CUE merges them and reports conflicts. This is the most Nix-like model available outside of Nix itself.

Nickel

Used by: Tweag projects, NixOS-adjacent tooling

Nickel is explicitly designed to be “Nix, but simpler.” It has contracts (gradual typing), merge semantics (like Nix’s // operator), and a Python-like syntax. It aims to be the configuration language Nix should have been.

Example unit:

{
  openssh = {
    version = "9.6p1",
    deps = ["zlib", "openssl"],
    build = fun arch =>
      if arch == "arm64" then
        ["./configure --host=aarch64", "make"]
      else
        ["./configure", "make"],
  }
}

Strengths:

• Designed for Nix-style composition — record merging, overrides, and priority annotations
• Contracts provide validation without a separate type system
• More approachable syntax than Nix
• Deterministic evaluation

Weaknesses:

• Not Go-native — implemented in Rust; embedding in a Go binary requires FFI or running as a subprocess
• Young project — smaller ecosystem, less battle-testing
• Smaller community than Starlark or CUE

Composability model: Record merging with priority, very similar to Nix overlays. Define a base, merge overrides, and Nickel resolves conflicts using priority annotations.

Jsonnet

Used by: Grafana (dashboards), Tanka (Kubernetes), various config generation

A templating language that extends JSON with variables, conditionals, imports, functions, and object composition via the + operator.

Example unit:

local base = import 'module-core/openssh.jsonnet';

base {
  deps+: ['vendor-crypto'],
  configure_args+: ['--with-vendor-crypto'],
}

Strengths:

• Simple mental model — “JSON with functions and imports”
• Object merging with +: (append) and + (override) is intuitive
• Go-native implementation (go-jsonnet)
• Deterministic
• Good for layered configuration

Weaknesses:

• Designed for data generation, not build systems — no concept of targets, dependencies, or build phases
• Verbose for complex logic
• Weaker validation than CUE (no constraint system)
• Less expressive than Starlark for imperative build logic

Composability model: Object inheritance with + operator. Import a base object, override or append fields. Straightforward and explicit.

Lua / Luau

Used by: Neovim, Redis, game engines, Premake (build system)

Lightweight embeddable scripting language. Luau (Roblox) adds gradual typing.

Example unit:

autotools {
    name = "openssh",
    version = "9.6p1",
    deps = {"zlib", "openssl"},
    configure_args = {"--sysconfdir=/etc/ssh"},
}

Strengths:

• Extremely lightweight runtime (~200KB)
• Very fast (LuaJIT, Luau)
• Simple, well-understood language
• Good Go bindings (gopher-lua, go-luau)
• Tables provide natural composition via metatables

Weaknesses:

• Not deterministic by default — has os.execute, io.open, etc. that must be sandboxed by removing from the environment
• Not designed for build systems — no built-in load() or module system suitable for build file composition
• 1-indexed arrays (trivial but annoys developers)
• No built-in constraint/validation system

Composability model: Table merging via metatables or explicit merge functions. Powerful but requires convention — the language doesn’t enforce a composition pattern.

Nix Language

Used by: NixOS, Nixpkgs (100,000+ packages)

A pure, lazy, functional language designed for package management and system configuration.

Example unit:

{ stdenv, zlib, openssl }:
stdenv.mkDerivation {
  pname = "openssh";
  version = "9.6p1";
  buildInputs = [ zlib openssl ];
  configureFlags = [ "--sysconfdir=/etc/ssh" ];
}

Strengths:

• The gold standard for composability — overlays, overrides, and the fixpoint pattern enable arbitrary layered modification of any package
• Lazy evaluation means unused definitions have zero cost
• Proven at massive scale (100,000+ packages in Nixpkgs)
• Perfectly deterministic

Weaknesses:

• Not embeddable — the evaluator is a C++ application, not a library
• Steep learning curve — the language is deceptively complex (laziness, fixpoints, callPackage patterns)
• Error messages are notoriously poor
• Debugging “which overlay changed this attribute?” is difficult
• The very power of overlays is also a debuggability problem — implicit modification from anywhere makes tracing changes hard

Composability model: Overlays and the fixed-point pattern. A base package set is a function; overlays are functions that modify it. The system computes the fixed point, producing the final package set. Extremely powerful, but the indirection makes debugging non-trivial.

Comparison Matrix

Recommendation

Starlark is the recommended choice for [yoe].

Why:

1. Proven for exactly this use case. Bazel and Buck2 demonstrate that Starlark works for build system configuration at the largest scales. No other language on this list has been tested as thoroughly in the build system domain.

2. One language for everything. Units, classes, project config, machine definitions — all Starlark. No TOML + shell + something-else stack. Simple units read like declarative config; complex classes use real control flow.

3. Go-native. The go.starlark.net library embeds directly in the yoe binary. No FFI, no subprocess, no external runtime.

4. Deterministic and sandboxed by design. Critical for content-addressed caching — if the build definition is deterministic, the cache key is reliable. Starlark guarantees this without any configuration.

5. Familiar syntax. Python-like syntax means most developers can read Starlark immediately. The restrictions (no classes, no exceptions, no I/O) are subtractive — you learn what you can’t do, not a new paradigm.

What we give up compared to Nix/CUE:

• No implicit merging — composition is through explicit function calls and **kwargs. This means module overrides are more verbose but also more traceable. When debugging “why does openssh have vendor-crypto in its deps?”, you can grep for the function call. In Nix, you’d have to trace overlay evaluation order.

• No built-in constraint validation — unit validation happens in Go code (the yoe engine) rather than in the language itself. CUE’s constraint system is elegant, but adding a second language isn’t worth it.

Composability pattern for modules:

[yoe]’s module system (vendor BSP modules, product modules) works through Starlark’s function composition:

# Module 1: module-core/openssh.star
def openssh(extra_deps=[], **overrides):
    unit(
        name = "openssh",
        version = "9.6p1",
        deps = ["zlib", "openssl"] + extra_deps,
        **overrides,
    )

# Module 2: vendor-bsp/openssh.star
load("//module-core/openssh.star", "openssh")
openssh(extra_deps=["vendor-crypto"])

# Module 3: product/openssh.star (further customization)
load("//vendor-bsp/openssh.star", "openssh")
openssh(extra_configure_args=["--with-pam"])

Each module is explicit about what it modifies and where the base comes from. This is less magical than Nix overlays but easier to debug.

What This Means for [yoe]

With Starlark as the single language, the project structure becomes:

my-project/
├── PROJECT.star              # project config: name, caches, modules
├── machines/
│   ├── beaglebone-black.star
│   ├── raspberrypi4.star
│   └── qemu-arm64.star
├── units/
│   ├── openssh.star          # package unit
│   ├── myapp.star            # app unit (Go)
│   ├── base-image.star       # image unit
│   └── dev-image.star        # image unit (extends base)
├── classes/                  # reusable build rule functions
│   ├── autotools.star
│   ├── cmake.star
│   ├── go.star
│   └── image.star
└── overlays/

TOML is eliminated entirely. Units, classes, machines, and project config are all .star files. The Go yoe binary provides the built-in functions (unit(), image(), machine(), project(), etc.) that Starlark code calls.

Starlark Ecosystem & Adoption

Understanding the breadth of Starlark adoption helps validate the choice and provides reference implementations to learn from.

Projects Using Starlark (the language)

These projects implement their own Starlark interpreter (typically in Java or C++):

• Bazel (Google) — the build system Starlark was originally designed for. Java-based Starlark interpreter. The largest and most mature Starlark deployment.
• Buck2 (Meta) — Meta’s next-generation build system, uses Starlark for BUCK files. Rust-based interpreter.
• Pants — a Python-ecosystem build system that uses Starlark for BUILD files. Rust-based interpreter.
• Copybara (Google) — a tool for transforming and moving code between repositories. Java-based.

Projects Using starlark-go (the Go library)

These projects embed the go.starlark.net Go library — the same library [yoe] would use:

• Tilt — microservice dev environment; uses Starlark for Tiltfile configuration
• Delve — the standard Go debugger; uses Starlark as a scripting language for automation
• Drone — CI/CD platform; supports Starlark as an alternative to YAML pipelines
• Isopod (Cruise Automation) — DSL framework for Kubernetes configuration
• Kurtosis — developer tool for packaging and running containerized service environments
• envd — CLI for building Docker images for ML development and production
• Bramble — a purely functional build system and package manager
• Gazelle (Bazel) — BUILD file generator for Go/Protobuf projects; uses starlark-go for evaluating directives
• AsCode — infrastructure-as-code using Starlark on top of Terraform
• AutoKitteh — developer platform for workflow automation and orchestration
• FizzBee — system design language for verifying distributed systems

Why This Matters for [yoe]

The starlark-go library is actively maintained by Google and used in production by a diverse set of Go projects. The pattern of embedding starlark-go to provide a sandboxed, deterministic configuration language in a Go CLI is well-established — [yoe] would be following a proven approach, not blazing a new trail.

Open Questions

• Class composition: Should multiple classes be applied via multiple function calls (autotools() + systemd_service()) or via a single wrapper macro (systemd_autotools())? Both work; the question is which to encourage as convention.
• Machine-specific conditionals: Should machine properties be available as Starlark globals during unit evaluation, or passed explicitly? Globals are convenient but reduce hermeticity.
• REPL / interactive evaluation: Should yoe provide a Starlark REPL for debugging unit evaluation? Bazel has bazel query; a similar introspection tool would help users understand how their units resolve.

Security and Threat Model

[yoe] is a build system. It runs arbitrary code that you and the modules you import write — Starlark logic plus shell scripts inside a build container. This page describes what that container actually protects you against, what it does not, and how to think about trusting the code yoe will execute on your behalf.

The short version: treat every unit and every module the same way you treat a curl | sh URL. If you import it, you are running it. The build container is a convenience for hermetic toolchains, not a security boundary.

Threat model

[yoe] is designed for a developer or build operator running it on a machine they control, against source code and modules they have chosen to import. It is not designed to safely execute untrusted units.

In particular:

• Trusted. You. Your project’s PROJECT.star, your project’s unit .star files, every module you list in modules = [...], every upstream source URL and git remote those units pull from.
• Untrusted. The booted target device, network traffic to/from on-device package installs (apk add, yoe deploy). These are protected by the apk signing chain — see apk Signing.
• Out of scope. Running other people’s PROJECT.star files, hosting yoe builds on a multi-tenant machine, sandboxing one project from another on the same host. yoe does not attempt any of this today.

If the question is “can a rogue unit damage the host?”, the honest answer is yes, easily. The rest of this page explains why, what limits exist today, how this will be improved in the future.

Architecture: Starlark for declaration, Go for execution (planned)

Status: Planned. Today, run(..., host=True) and run(..., privileged=True) are accessible from Starlark and are used extensively by the in-tree classes (container.star shells docker build on the host; image.star runs dpkg --configure -a with privileged=True to chown the rootfs). A rogue unit can therefore reach the host shell and root-in-container directly from a class body. The planned cutover restricts every host call and every privileged-container call to Go code paths, removing those kwargs from the Starlark surface. See docs/specs/2026-05-20-starlark-unprivileged-only.md for the spec and current implementation status.

The architectural rule yoe is converging on:

All host-shell execution and all privileged-container execution happens in Go code. Starlark declares what work to do; Go decides whether to run it, in which sandbox, and with what privileges.

Concretely:

• Starlark units declare data — name, version, source URL, runtime deps, install task steps — and assemble that data into *Unit structs through builtins (unit(), image(), container(), …).
• Go code consumes those structs and decides everything that actually touches the host or runs privileged: which container to spawn, which sandbox profile to apply, which paths to mount, which capabilities to drop, whether to shell out to docker buildx or dpkg --configure -a.
• The run(...) Starlark builtin survives for unprivileged in-container shell steps — the install task body of a feed unit extracts a tarball, the build task of an autotools unit runs ./configure && make. These run in the per-unit bwrap sandbox where the worst a rogue command can do is corrupt its own destdir.

Why this matters: a small Go audit surface for arbitrary Starlark

Starlark has no I/O primitives of its own. It can’t open files, can’t spawn processes, can’t make network calls. Every operation that escapes the Starlark interpreter does so through a Go-side builtin the embedding program registered. yoe’s embedding registers a small, enumerable set: unit, image, container, machine, task, run, alpine_feed, apt_feed, resolve_closure, and a handful of supporting builders. The complete list lives in internal/starlark/builtins.go.

Once every Go-side builtin is audited — does it sandbox the work it spawns? does it refuse to escape the build directory? does it drop privileges before running shell? — the answer for every possible Starlark unit is the same answer. A new module a user imports next year cannot expand the attack surface beyond what the existing Go builtins permit. The Starlark code is data; the policy lives in Go.

Contrast with Python or JavaScript embeddings, where the unit author can call subprocess.run, os.system, fetch, eval, import os — the language’s standard library is the attack surface, and there is no enumerable list of escape hatches an auditor can walk to be sure they’ve seen everything. A pure-data DSL like Starlark inverts this: a security review enumerates the embedded builtins, audits each one in Go, and is done. Adding a new builtin is a deliberate choice the maintainer makes; adding a new Starlark unit cannot expand what the system is capable of.

This is the single biggest leverage point in yoe’s security model. The build container, signing chain, repo trust, and on-target apk verification all sit on top of “Starlark is data, Go is policy.” Once the transition is complete, the threat model changes from “every imported module is curl | sh” to “every imported module is data fed to an audited Go program” — still not zero-trust, but the audit surface stops growing with the number of imports.

The remainder of this page describes the current state (where some of this is already true and some isn’t) and what the build container actually protects you against today.

How a build actually runs

Every yoe build step that needs a toolchain runs in a Docker (or Podman) container launched by internal/container.go. The relevant flags are:

docker run --rm --privileged \
  --user <host-uid>:<host-gid> \
  -v <projectDir>:/project \
  -v <srcDir>:/build/src \
  -v <destDir>:/build/destdir \
  -v <sysroot>:/build/sysroot:ro \
  -v <cacheDir>:<containerPath> ...   # per-unit cache_dirs
  -w /project \
  <image> sh -c '<build command>'

Two things in that command line dominate the security picture:

• --privileged is unconditional. Every container yoe launches is privileged. That means all Linux capabilities are granted, the host’s /dev is exposed (or near-equivalent on Docker), AppArmor/SELinux profiles are not enforced, seccomp is off, and /sys is read-write. The container is not a sandbox in any meaningful sense — it is a chroot with a toolchain.
• --user uid:gid runs as you, except when it doesn’t. Most steps drop to the host user, so files written to mounted paths are owned by you and the container cannot directly write host devices that require root. But several paths run as root in the privileged container (see below), and at that point a hostile build step can write /dev/sda, load kernel modules, or pivot the mount namespace and escape.

Code paths that run as root in the privileged container

For these paths, container UID is root, all caps are present, and the host’s /dev is reachable. There is no defense-in-depth layer beneath that.

The apk-extraction step on the image-class row deserves a short note: it runs as root in the container so that chown(path, hdr.uid, hdr.gid) calls during tar extraction actually succeed, which is what makes the assembled rootfs contain (and the resulting ext4 image preserve) per-file ownership like navidrome:navidrome for /var/lib/navidrome or postgres:postgres for /var/lib/postgresql. The earlier workaround — chown -R 0:0 on the rootfs followed by a chown-back-to-host at end-of-build — collapsed all ownership to root and obscured what the booted system would see; the current path preserves real ownership and accepts the cost that build/<image>.<arch>/destdir/rootfs/ is owned by root after a build. yoe cache clean and yoe build --clean route cleanup through the same container so the host user doesn’t need sudo for routine work. See Comparisons § Rootfs Ownership for why this is preferred over LD_PRELOAD (fakeroot/pseudo) or user-namespace (bwrap) alternatives.

run(host = True) — there is no container at all

Units can ask Starlark to execute commands directly on the host:

run("docker build -t %s -f %s/%s %s" % (tag, name, dockerfile, name), host = True)

This is how modules/module-core/classes/container.star builds container images on the host’s Docker daemon. The command runs through bash -c as your host user, in cfg.HostDir (usually the unit’s .star directory). There is no namespace, no mount restriction, no /project-only view. A unit that uses host = True has a shell as you. It can read ~/.ssh, write ~/.config/yoe/keys/, or rm -rf ~.

The bwrap layer

Build steps that opt into sandbox = True are wrapped with bwrap inside the container (internal/build/sandbox.go). The bwrap call binds / to /, read-only-binds /proc and the sysroot, and tmpfs’s /tmp. This is sysroot hygiene, not isolation — it prevents a unit from accidentally linking against host libraries during a hermetic build. The whole bwrap invocation is inside the same privileged container, so a unit that wants to escape can simply call exit from bwrap and run anything it likes outside it, or call run(privileged = True) to skip bwrap altogether.

What a rogue unit can do

Given the above, a unit author can — without warning, prompts, or visible side effects in yoe build output:

• Read and modify the entire project tree. /project is mounted read-write. That includes PROJECT.star, every other unit, the build cache, the apk repo, signing public keys, build logs.
• Read every source the build has pulled. cache/sources/ and cache/modules/ typically map under the project, but a unit’s cache_dirs can bind any directory the user has access to.
• Read environment variables passed to the build. The Go process exports them into the container via -e flags.
• Execute arbitrary host commands as you via run(host = True). This bypasses the container entirely. There is no allowlist, no path restriction, no “are you sure?” prompt. The unit author has the full power of your shell.
• Run as root in a privileged container via run(privileged = True) or by declaring unit_class = "image". From there:
  • Overwrite /dev/sda, /dev/nvme0n1, USB sticks, any block device the kernel exposes.
  • Load kernel modules into the host kernel (insmod, modprobe).
  • Modify host firewall rules (iptables, nft) — the privileged container shares the network namespace by default, so changes are host-wide.
  • Read /proc/<host-pid> for every process on the host.
  • Mount any host filesystem and exfiltrate or modify it.
  • Trigger any of the well-known privileged-container escapes (/sys/kernel/uevent_helper, core_pattern, cgroup release_agent, etc.) to spawn a process on the host as root.
• Tamper with the apk signing pipeline. The project signing key lives at ~/.config/yoe/keys/<project>.rsa. A run(host = True) step trivially reads it. A privileged in-container step can read it if it lives under /project or any mounted cache dir; the default location is in your home, which the container does not see — but run(host = True) does.
• Poison the cache. A unit can plant files in cache/sources/, cache/modules/, or per-unit cache_dirs mounts so the next build of another unit picks up tampered content.

What yoe does limit

The container does provide some friction. It is worth being precise about what:

• Unit builds that don’t go privileged see only /project and their mounts. A run-of-the-mill make && make install step running as your host UID cannot reach $HOME, system files outside /project, or the apk private key in ~/.config/yoe/keys/. It can still corrupt anything inside /project and the configured cache dirs.
• Most builds run as your host UID, not root. Even with --privileged, a non-root container process cannot write block devices owned by root:disk or call mount(2) directly. A unit has to deliberately escalate via privileged = True, unit_class = "image", or host = True to escape this.
• Apks are signed and verified. Output .apk files are signed with the project key, the public key is published to the repo and embedded in the rootfs, and on-device apk add / yoe deploy reject unsigned or wrongly-signed packages. See apk Signing. This protects the device → repo channel; it does not protect the host that produces the apks.
• Source archives can declare integrity hashes. Units that set sha256 = "…" or apk_checksum = "…" get post-download verification in internal/source/fetch.go. Units that omit both run whatever the upstream returned.

Trust model for code yoe executes

yoe does not validate the units it loads. The trust chain for a build is:

1. PROJECT.star — you wrote it (or you imported it from a project you trust). It declares modules with module(url = ..., ref = ...).
2. Modules are fetched with git clone --depth 1 --branch <ref> into cache/modules/<name>/ (internal/module/fetch.go). ref is a branch or tag name — not a commit hash. A module upstream that retags a release ships you the new content on the next yoe module sync. The cache also trusts whatever bytes are already on disk; once cloned, integrity isn’t re-checked.
3. Unit sources come from the URL in each unit’s source = ... field, fetched via HTTPS, HTTP, or git. Integrity is verified if and only if the unit declares sha256 or apk_checksum. Git sources rely on the tag pointing at the right commit at clone time.
4. The build container image is built from a Dockerfile in module-core, module-alpine, or another module — i.e., from the same supply chain as the units. It is not a vendor-supplied vetted image.