Testing the installer

Why it needs its own tiers

The installer is ctrl/deps.sh. What reaches a machine is its generated one-file kit, standalone/default/rigdeps.sh: the AWS Workspace gets that file and nothing else. The machines it must work on are exactly the ones you cannot rebuild to test on:

the Workspace cannot be recreated;
redoing WSL means rebuilding the machine you work on every day;
a fresh install happens once per machine, so a bug there is found by the one person least able to diagnose it.

So each tier is cheaper than the one after it, and each catches what the one before cannot.

tier	runs	needs	proves	cannot prove
1 host fixtures	every `make selftest`	nothing	detection reads each kind of machine right: distro, WSL, memory, overcommit, systemd, `.wslconfig`, the Git Bash refusal	that anything installs
2 clean containers	`make selftest install`	docker, network, ~1–2 min	a stock Ubuntu 22.04 / Debian refuses cleanly when bare, then installs, verifies and fetches the manifests as a non-root user; the offline image works with no network	WSL, the Workspace's own policies, docker itself
3a Workspace snapshot	by hand, when the Workspace changes	the kit, once, on the Workspace	tier 1 replays the real Workspace's shape from then on	its install (that is tier 2's Ubuntu 22.04 plus the real run)
3b WSL throwaway	by hand, before teaching or after a WSL change	a Windows machine	the whole path in a real WSL distro that is not your daily one	Windows-side setup (not built, see below)

Tier 1 — host fixtures

tests/hosts/<name>/ is a stand-in machine:

root/        the files detect reads: etc/os-release, proc/version, proc/meminfo,
             proc/sys/vm/overcommit_memory, etc/wsl.conf, mnt/c/Users/<u>/.wslconfig
env          optional KEY=value lines, e.g. UNAME_S=MINGW64_NT-10.0 (a fact no file carries)
expect.txt   "+ text" must appear, "- text" must not, "exit N" (default 0)

bash ctrl/hosttest.sh [DIR...] runs deps.sh detect all with HOST_ROOT pointing at the root (which also sets MEMINFO and OVERCOMMIT_FILE) and checks the lines. Only host facts are asserted: docker, PATH and the filesystem belong to the machine running the test.

Shipped: ubuntu-22.04 (the Workspace's shape: 7.6 GB, overcommit 1, swap in use), debian-trixie, wsl-bare (systemd off, no .wslconfig), wsl-ready, git-bash. To add a case, add a folder. Anything true of one real machine goes with an overlay or in local/, never here.

Tier 2 — clean containers

make selftest install (ctrl/installtest.sh [IMAGE...]). It first refuses to run on a stale kit, then, for ubuntu:22.04 and debian:trixie-slim:

bare: install must refuse and name curl/wget — the bootstrap paradox;
after the one root step (apt-get install curl ca-certificates), as a plain user: install dev, verify dev, manifests --to ~/m. The dev tier lands in ~/.local/bin, the PATH advice is printed, and all three manifests are there, verified.

Then it builds deps-full and runs install + manifests with --network none: the air-gapped path. Measured 2026-09-22: 15 checks, 75 s.

Tier 3a — the Workspace snapshot

bash rigdeps.sh snapshot ~/rig-host-snapshot     # on the Workspace; the kit is enough

It writes the files detect reads, cut down to what detect needs:

the os-release name fields;
the kernel release;
four meminfo numbers;
the overcommit value;
wsl.conf's section headers and its two keys;
a .wslconfig memory line, under the neutral user user;
facts.txt (arch, glibc, date);
expect.txt, the lines detect printed for it.

No environment, no home, no host name: selftest asserts both the file list and the absence of those.

Carry the folder back, keep it in local/hosts/workspace/ (gitignored) or with the overlay, and from then on:

bash ctrl/hosttest.sh local/hosts/workspace

Add your own +/- lines to its expect.txt for what must stay true there. Take a new one when the Workspace changes (an image update, a memory change).

Tier 3b — WSL, in a throwaway distro

Never the distro you work in: a second one, imported from a rootfs, removed afterwards. WSL runs every distro in one VM, so this changes nothing in yours — except that wsl --shutdown stops both; don't run it while you work. From PowerShell:

# a pristine Ubuntu 22.04 rootfs: from cloud-images.ubuntu.com/wsl/, or
# `wsl --export Ubuntu-22.04 ubuntu-22.04.tar` of an untouched install kept for this
wsl --import rig-test C:\wsl\rig-test .\ubuntu-22.04.tar
wsl -d rig-test -u root -- bash -c "apt-get update && apt-get install -y curl ca-certificates && useradd -m t"
copy .\rigdeps.sh \\wsl$\rig-test\home\t\
wsl -d rig-test -u t -- bash -lc "cd ~ && bash rigdeps.sh detect all && bash rigdeps.sh install dev && bash rigdeps.sh verify dev && bash rigdeps.sh snapshot ~/snap"
# carry \\wsl$\rig-test\home\t\snap back as a fixture, then:
wsl --unregister rig-test

What to look for: detect says WSL, and names the systemd and .wslconfig steps; install and verify pass. This is the tier to run before teaching Windows users, or after a WSL update. Nothing in rig automates it: a throwaway-distro harness is the multi-distro machinery that was removed on purpose.

Not built: a Windows-host installer

Everything above starts inside Linux. The Windows side — enabling WSL, getting a distro, and the tools a Windows user needs before rig (python and the like) — is still manual, in the README's "Starting from plain Windows". A Windows-host installer is recorded for the future, for teaching; it would need tier 3b's approach, a machine that is not your daily one, to test.

The hooks the tiers rely on

deps.sh reads host files through HOST_ROOT (host_file()), memory through MEMINFO, the overcommit mode through OVERCOMMIT_FILE, the kernel name through UNAME_S, and WSL through host_file /proc/version. With HOST_ROOT set, MEMINFO and OVERCOMMIT_FILE default into it. The deps image relies on HOST_ROOT=/host for the same reason: a container asking about its host.

6.1 KiB Raw Blame History Unescape Escape