Command reference

The common commands — the root Makefile is authoritative

§1make targets

TargetMeaning
make buildbuild the kernel (riscv64 default; PLATFORM=x86_64 / aarch64 to switch)
make runboot the minimal rootfs in QEMU (mrsh, /bin/sh)
make ubuntu-runbuild + 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 testthe in-kernel test suite (PLATFORM= switches architecture)
make rootfsbuild the minimal rootfs image (needs user+toybox+mrsh)
make user / toybox / mrsh / sdkuserspace programs / the 200+ tool box / a POSIX shell / the musl SDK
make ltpbuild the LTP suite (needs sdk)
make verify / kani / spin / mirithe four formal-verification layers
make config / menuconfigview / interactively configure the kernel (Kernel.toml)
make debugdebug the kernel with GDB
make bin / info / cleanproduce 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/).