Command reference
The common commands — the root Makefile is authoritative
§1make targets
| Target | Meaning |
|---|---|
| make build | build the kernel (riscv64 default; PLATFORM=x86_64 / aarch64 to switch) |
| make run | boot the minimal rootfs in QEMU (mrsh, /bin/sh) |
| make ubuntu-run | build + boot the full Ubuntu 24.04 desktop in an SDL window (default; serial login root/rux — a UBUNTU_IMG override boots the 22.04 GNOME chain) |
| make test | the in-kernel test suite (PLATFORM= switches architecture) |
| make rootfs | build the minimal rootfs image (needs user+toybox+mrsh) |
| make user / toybox / mrsh / sdk | userspace programs / the 200+ tool box / a POSIX shell / the musl SDK |
| make ltp | build the LTP suite (needs sdk) |
| make verify / kani / spin / miri | the four formal-verification layers |
| make config / menuconfig | view / interactively configure the kernel (Kernel.toml) |
| make debug | debug the kernel with GDB |
| make bin / info / clean | produce binaries / project info / clean |
§2Debugging commands
# symbolize a panic address
riscv64-linux-gnu-addr2line -e <kernel> -f -C <addr>
# extract guest logs offline (debugfs, on a copied image)
debugfs -R "cat /var/log/kmsg" rootfs-copy.img
# deadlock/hang capture (auto holder-annotated build + stress injection + on-site capture)
./test/hunt-wedge.sh [rounds]
# tracefs (unified tracepoints)
mount -t tracefs none /sys/kernel/tracing
echo 1 > /sys/kernel/tracing/events/sched/sched_wakeup/enable
cat /sys/kernel/tracing/trace
# the kmsg ring buffer
dmesg # inside the guest
dmesg -n 7 # reopen full console logging
§3Paths and environment
/home/william/rux-images/ # all disk images (worktrees symlink only)
/home/william/rux-agents/<name>/ # one worktree per task
docs/architecture/lock-ordering.md # required before lock nesting
docs/development/perf-gate-baseline.md # the performance gate baseline
docs/test/README.md # the test-report index
§4Operating discipline
- Shared images boot only with
-snapshot+file.locking=off. - Kill only QEMU processes you started; tests default to
-smp 2 -m 1G. - Never hand-write QEMU commands for standard flows (the parameters live in the Makefile / driver scripts).
- Commit messages in English; no temp files in the main repository root (use your worktree's run/).