Building and testing

This page shows you how to build SlopOS, where the results go, and how to run the test suite and read what it tells you. It ends with every recipe the repository has. It assumes you have run just setup from the Quickstart.

How the build fits together

Every command goes through just, a command runner. The file justfile at the root of the repository defines named recipes, and just <recipe> runs one. just --list prints them all with a line on each.

A bootable SlopOS is made of three things, built in this order:

1. The programs. The shell, the desktop, the coreutils and everything else that runs on SlopOS, compiled for SlopOS with the slopos Rust toolchain.
2. A disk image holding those programs: a file containing an ext4 filesystem, the same format Linux uses, which QEMU presents to the virtual machine as a disk.
3. The kernel, one ELF file.

The boot recipes then wrap the kernel and its programs into something firmware can start: a CD image (ISO) for the live system, or a boot disk for the development machine. You rarely run the steps by hand, because each boot and test recipe builds what it needs first.

Image files are still called ext2 for historical reasons; every image the build makes is ext4. Compiler output goes under builddir/target, and downloaded inputs (the Limine bootloader, the OVMF firmware, LLVM sources) are cached under third_party/.

Every kernel build ends by running checks on the finished ELF (for example, that no function's stack frame is too large), so a build can still fail after the compiler has succeeded. Safety gates lists them.

Optimised and debug kernels

The dev kernel is built quickly, with symbols, and is what just build, just boot-live and the debugger recipes use. The release kernel is optimised, and just boot uses it because the development machine runs a compiler. KERNEL_RELEASE=1 selects the release kernel for any recipe, and KERNEL_RELEASE=0 just boot boots the dev kernel instead.

Passing options to a recipe

Settings such as ROULETTE=0 (skip the Wheel of Fate), DEBUG=1 (more kernel logging) and VIDEO=0 (no window) are environment variables, so they go before just:

ROULETTE=0 DEBUG=1 just boot

A recipe's own arguments go after its name and are positional. Write just test 'slopos_mm::*', not just test FILTER='slopos_mm::*': the second form passes the text FILTER=slopos_mm::* as the filter, which matches nothing. One setting, ports, is a justfile variable and goes between just and the recipe:

just ports=7777,8080 boot

QEMU options lists every environment variable the boot recipes read.

Run the tests

1. Run the whole suite

just test

This builds a kernel with the test harness compiled in, boots it in QEMU with no window, and runs every kernel test and then every userland test. A progress bar shows how far it is. When QEMU exits, the runner prints a summary and exits 0 if every test passed and 1 otherwise. Each run starts from a freshly built test disk, so no run depends on what the last one wrote.

2. Read a failure

For each failing test the runner prints its name (<module>::<test>) and the kernel log lines the test produced while it ran, which is usually where the reason is. Passing tests' logs are hidden; just test-verbose shows them too.

After every run that finished, the names of the failed tests are in builddir/last-fail.list, and this reruns only those:

just test-rerun-failed

If the summary looks wrong, just test-raw prints exactly what came out of the virtual machine's serial port: the test results in KTAP, the plain-text format Linux's kernel tests use, mixed with the kernel log. Test output format describes it.

3. Run some of the tests

Pass a glob, a pattern where * matches anything, as the first argument. It is matched against each test's <module>::<test> name. Separate several globs with commas:

just test 'slopos_mm::*'
just test '*ext2_aaa*,slopos_fs::*'

A filtered run whose tests create files must include '*ext2_aaa*'. That test mounts the test disk, and tests run in alphabetical order, so it is what makes the disk available to the tests after it.

just test-verbose and just test-quiet take the same glob.

Tests that run on your machine

just test-host

This runs the unit tests of the parts of SlopOS that are plain logic (the filesystem, network and TLS cores, the terminal, the shell and others) as ordinary programs on your machine, with no QEMU. It is the fastest way to check a change to one of those parts. Write tests explains where a new test belongs.

What usually goes wrong

• just test stops before booting with a message about LLVM: the test image includes a C++ runtime built with LLVM 18 or later, and your machine has none it can use. See Troubleshooting.
• A filtered run fails on file operations: add '*ext2_aaa*' to the filter.
• just check or a framekernel gate complains that the kernel ELF is missing: run just build first.

All recipes

The justfile is the authoritative list; just --list prints it with each recipe's own description.

Setup and build

Boot

boot-fast and boot-debug start just boot again inside themselves, and a ports= setting does not reach that inner run. To forward ports without the wheel, use ROULETTE=0 just ports=7777 boot.

Persistent root

just boot rebuilds builddir/boot-disk.img on every run, so a kernel the guest installed survives guest reboots but not the next just boot. Installing a system covers boot slots.

Tests

Filesystem and boot-log checks

Verification and code rules

The framekernel explains what the gates protect.

Debugging

Debugging with GDB shows how to use them.

Toolchain for SlopOS

Toolchain explains how these fit together.