Boot Den In QEMU

This tutorial takes you from a clean checkout to a booted Den prototype in QEMU. You will build the conda root filesystem, build the Buildroot early boot layer, package both into a QEMU bundle, and run the deterministic boot smoke.

Use this tutorial when you want to learn the shape of the system. Use the how-to guides when you already know the model and just need the commands.

Prerequisites

You need:

  • macOS with Docker or OrbStack running,

  • enough disk space for Buildroot output and a 4 GiB rootfs image,

  • network access for conda and Buildroot source downloads,

  • no host conda installation requirement.

The smoke paths can use Docker or OrbStack containers, and the generated build state stays under this checkout. The tutorial should not modify host boot settings or install host packages.

Build The Root Filesystem

From the repository root:

ct run smoke

This command consumes the configured Den package channel, locks the workspace for linux-aarch64, archives the workspace, unarchives the runtime environment under /opt/den, unarchives the system environment under /den/generations/1/sw, applies rootfs layout manifests, and runs userland checks. Den-owned package builds happen in den-forge; this repository stages and smokes the resulting packages.

When it passes, the staged rootfs exists at:

build/rootfs

The active system generation is:

build/rootfs/den/generations/1/sw

Build The Early Boot Layer

Build the QEMU AArch64 kernel and initramfs:

den image early-boot

This downloads Buildroot under build/buildroot-src, builds with Buildroot’s native make interface, and keeps the heavy output under build/buildroot-output.

The copied boot artifacts are:

build/buildroot/images/Image
build/buildroot/images/rootfs.cpio.gz

Build The QEMU Bundle

Package the kernel, initramfs, rootfs image, launcher, manifest, and checksums:

ct run image-bundle

The bundle is:

build/artifacts/den-qemu-aarch64.tar.zst

Boot The Bundle Through The Smoke Path

Run the deterministic smoke:

ct run image-bundle-smoke

The smoke target extracts the bundle into a temporary directory, verifies SHA256SUMS, starts QEMU from the extracted files, boots into packaged systemd, runs den-systemd-smoke.service, prints:

Den systemd: smoke complete

and powers off.

What You Built

You built a small bootable system with two ownership layers:

  • Buildroot owns the kernel, initramfs, static BusyBox, early mount, and switch_root.

  • Conda owns the runtime prefix, system generation, dynamic loader compatibility links, systemd, Den units, release metadata, and generation tooling.

The important part is the handoff. Den is not an Alpine or Buildroot distro with conda added afterward. It is a conda-owned locked package graph with just enough early boot code underneath to reach that graph.

Optional: Build Other Image Forms

After the QEMU bundle works, you can also build the local OCI inspection image and the UEFI disk image:

ct run oci-smoke
ct run uefi-image-smoke

oci-smoke checks the rootfs through Docker/OrbStack. uefi-image-smoke boots a GRUB-backed UEFI raw disk in QEMU and waits for the same systemd smoke unit.