NOTICE: This distro build harness and documentation was generated by AI agents. I am obviously no expert in Linux tooling or distros. The script self-verifies Aburi compilation at the end.

Aburi Linux AArch64 workstation

This recipe builds a bootable Alpine Linux Xfce workstation for QEMU's AArch64 virt machine. The Linux kernel is compiled by Aburi through its LLVM backend. The guest userland is intentionally ordinary Alpine software built by the distribution toolchain, and the installed workstation includes both GCC and Clang.

The harness is self-contained: it takes an Aburi executable as an input and writes everything it produces into its own out/ directory. It does not need to live inside an Aburi checkout.

Apple Silicon macOS with QEMU HVF is the supported build and acceptance host. TCG remains available as a slower, opt-in way to boot or test the same image on other hosts.

Host prerequisites

An Aburi executable, Docker, and the packages used to drive Linux's build:

brew install cmake llvm qemu make coreutils gnu-sed zstd xz

Host tools are looked up under HOMEBREW_PREFIX (or brew --prefix), /opt/homebrew, /usr/local, and /opt/local before falling back to PATH. Set ABURI_LINUX_TOOL_PREFIXES to a colon-separated list of prefixes if they live somewhere else. LLVM 22.x supplies Kbuild's assembler and binutils; set LLVM_PREFIX if it is not under one of those prefixes. Docker must be running for the root filesystem stage.

Build

Point the harness at an Aburi binary and build every stage:

./build.sh all --aburi /path/to/aburi

ABURI_BIN=/path/to/aburi does the same thing. To build the compiler from source instead, pass a checkout with --aburi-source /path/to/aburi (LLVM 22.x and CMake are then required); when this harness is checked out inside an Aburi source tree, that tree is used automatically if neither option is given.

The stages can also be run independently:

./build.sh compiler --aburi /path/to/aburi
./build.sh kernel   --aburi /path/to/aburi
./build.sh rootfs
./build.sh bundle

build.sh kernel passes this compiler command to Kbuild for every target C translation unit:

aburi --driver-persona=clang --backend=llvm

The actual recorded command also carries inert macros containing the Aburi binary's SHA-256 digest and the final kernel configuration's digest. They make Kbuild invalidate target objects when the compiler changes at the same path or when an indirect CONFIG_* header dependency changes, rather than accidentally reusing stale output.

Kbuild's host programs use the platform toolchain (/usr/bin/clang on macOS; override with ABURI_LINUX_HOSTCC, ABURI_LINUX_HOSTCXX, and ABURI_LINUX_HOSTLD). Linux assembly and archive steps use LLVM 22 tools, while the ELF linker is discovered separately as ld.lld (Homebrew packages LLD separately from LLVM). The build audits Kbuild's recorded command lines to ensure target C files did not silently fall back to Clang or GCC.

Inputs are pinned in versions.lock; Linux's generic guest fragment and kernel.config are merged over tinyconfig; and packages.lock records the complete Alpine package closure. Starting from tinyconfig keeps unrelated AArch64 SoC drivers out of this QEMU-only image, while every boot-critical driver is explicitly built in. This makes the recipe repeatable but does not claim byte-identical images: ext4 creation and Alpine package metadata can encode run-specific details. Refresh the package closure only as a deliberate repository update:

./build.sh rootfs --refresh-lock

Output layout

Downloads, build trees, images, logs, VM state, and release archives all stay under out/ next to these scripts, and are never repository inputs:

out/work-6.18.42/    work directory for this kernel version
out/dist/            distributable archives
out/state/           persistent qcow2 overlays
out/acceptance.*/    acceptance-test logs and screenshots

Use --out DIR (or ABURI_LINUX_OUT_DIR) to place all of that elsewhere; ABURI_LINUX_WORK_DIR, ABURI_LINUX_DIST_DIR, and ABURI_LINUX_STATE_DIR override the individual directories. ./build.sh clean removes the work directory for the configured kernel version.

The bundle contains the kernel, symbols, configuration, immutable raw root filesystem, package manifest, checksums, launcher, and this document. Its manifest.txt records the Aburi version banner and binary digest that produced the kernel, along with the harness revision.

Boot with HVF

./run.sh

The default is -accel hvf -cpu host, a graphical window, four virtual CPUs, and 4 GiB of RAM. QEMU creates a persistent qcow2 overlay at out/state/workstation.qcow2, leaving the raw root image unchanged. The current directory is exported read/write to /mnt/host through virtio-9p.

The graphical session automatically logs in as the unprivileged user aburi. Use doas for administrative work; the image grants that user passwordless doas. There is intentionally no SSH service. The serial console also autologs in as aburi; with the launcher attached, QEMU monitor escapes begin with Ctrl-A.

Useful alternatives are:

# Throw away guest changes when QEMU exits.
./run.sh --fresh

# Serial-only boot.
./run.sh --headless

# Optional, much slower software emulation.
./run.sh --accel tcg

Use --share DIR, --no-share, --state PATH, --smp N, or --memory MIB to adjust the remaining runtime settings. Delete a qcow2 overlay—not the raw root filesystem—to reset a persistent workstation. The same run.sh launches an unpacked release bundle, using the artifacts next to it.

Acceptance test

On Apple Silicon macOS:

./test.sh

The HVF test boots twice from one qcow2 overlay and verifies the Aburi kernel identity, SMP, writable persistent root, DHCP networking, virtio GPU, Xfce, read/write 9p sharing, and native GCC and Clang compile/run smoke tests. It also checks that the raw backing image did not change. Logs and a QMP framebuffer screenshot are retained in the printed out/acceptance.* directory. test.sh --accel tcg runs the same checks with a longer timeout and is provided for contributors without HVF.

Troubleshooting

• If HVF reports an unavailable accelerator, use an Apple Silicon build of QEMU and run on macOS rather than inside a container.
• If Docker cannot connect, start the Docker daemon before the rootfs stage.
• If an exact Alpine package is no longer present upstream, review current package changes and intentionally refresh packages.lock; do not remove the version constraints from normal builds.
• Kernel compilation errors are Aburi compatibility bugs. Fix them in the compiler with a focused regression test instead of adding source patches or substituting another target C compiler.