nubjs Linux VM testing
Use a real VM only when the behavior depends on a Linux kernel or guest OS. Prefer Docker for userspace-only clean-cache/config experiments and ci-adhoc-test for unavailable architectures, distributions, or release-platform proof.
Two local backends serve different purposes:
- Lima
landlock-vm: persistent Ubuntu arm64 debugger with the host home mounted read-only. - Tart: disposable Ubuntu arm64 guest for clean-machine or alternate-image reproduction.
Preflight
Inspect both backends before changing VM state:
limactl list
tart list
limactl shell landlock-vm -- bash -lc \
'uname -srm; . /etc/os-release; echo "$PRETTY_NAME"; df -h "$HOME" /tmp'
Confirm the source mount before treating it as writable:
limactl shell landlock-vm -- bash -lc \
'findmnt -T /Users/colinmcd94/Documents/projects/nub'
The known Lima mount is read-only. Never build in /Users/colinmcd94/**. If the guest disk is full, report it and ask before reclaiming space. Never stop, delete, or clean an existing VM merely to make room.
Persistent Lima debugging
Run a short probe synchronously against the exact host source state:
limactl shell landlock-vm -- bash -lc \
'cd /Users/colinmcd94/.cache/nub/worktrees/<worktree> && <probe>'
Trace a guest command without modifying the host checkout:
limactl shell landlock-vm -- bash -lc \
'strace -f -o /tmp/nub.strace -- <command>'
limactl shell landlock-vm -- bash -lc \
'bpftrace -l "tracepoint:syscalls:sys_enter_*" | head'
For a Linux Rust build, copy the exact source state into guest-local storage and use a guest-only target directory:
limactl shell landlock-vm -- bash -lc '
mkdir -p "$HOME/src" "$HOME/.cache/nub/linux-vm-target"
src=/Users/colinmcd94/.cache/nub/worktrees/<worktree>
dest="$HOME/src/nub-<slug>"
rsync -a --delete \
--exclude .git --exclude target --exclude node_modules \
"$src/" "$dest/"
cd "$dest"
export CARGO_TARGET_DIR="$HOME/.cache/nub/linux-vm-target/<slug>"
cargo build -p nub-cli --profile fast
cargo test -p nub-cli --test <test_stem>
'
Repeat the copy after host edits. Use the exact host worktree under test, a distinct guest target for each branch or probe, and direct Cargo commands because the copied tree intentionally omits Git metadata. Remove only probe-owned files after capturing evidence; do not sweep guest caches or unrelated targets.
Start or stop the persistent VM only when required:
limactl start landlock-vm
limactl stop landlock-vm
Clean Tart reproduction
Let the checked-in helper own lifecycle:
tests/vm/tart-vm.sh up <name> <image>
tests/vm/tart-vm.sh exec <name> -- bash -lc '<probe>'
tests/vm/tart-vm.sh run <name> ./probe.sh
tests/vm/tart-vm.sh down <name>
tests/vm/tart-vm.sh rm <name>
Use a unique VM name. The run operation copies one script when sshpass is installed and otherwise streams its body; it does not copy a fixture tree or checkout. Fetch or copy multi-file fixtures deliberately. Finish a throwaway run with rm; down intentionally preserves the disk.
Evidence
Record:
- Host commit plus dirty-state summary.
- Guest distro, kernel, and architecture.
- Exact command and environment overrides.
- Exit status, stdout, and stderr.
- Relevant trace or log path.
Copy concise results to the host before deleting a Tart guest. Do not claim x86_64 coverage from these Apple-Silicon arm64 VMs. Use ci-adhoc-test when the claim requires x86_64-native behavior or another unavailable platform.