Build the image, boot it, write a C program inside the running system,
compile it with the on-board toolchain, run it, then verify your change
with the host test suites. Every command below runs from the repository
root on the host unless marked miniOS> (inside the guest).
Host tools: gcc, binutils (ld, objcopy, xxd), qemu-system-x86_64,
python3, git, mtools (mformat, mcopy) plus mkfs.vfat (FAT fixture
etc/fat.img for the fat builtin), sfdisk (util-linux: uefi.img and
the USB pendrive image), e2fsprogs (mkfs.ext4, etc/ext4.img for the
ext4 builtin). No absolute paths are assumed anywhere in the build;
every external checkout location is overridable (see make sources-status).
make sourcesClones the missing sibling repos next to the repo (defaults ../miniGCC,
../ld, ../cvm with cvm2 inside, ../micropython, ../cpython,
../lua, ../nuklear, ../nuked-opl3, ../FreeDom, ../raycastlib)
and Quake 2 Generic into progs/quake2generic/quake2generic. It also
fetches the pip and six wheels CPython installs offline.
Existing directories are never touched.
The full source contract: docs/spec/source.md.
makeZero warnings is required. Produces os.img (boot sectors, kernel with
embedded ramdisk, MiniFS partition, swap, FAT and ext4 fixture images).
Rebuilding after a kernel change is the same single command.
make run-headless # serial console, no GUI window
make run # with display (TCG by default)Wait for the miniOS> prompt. poweroff shuts the guest down.
Type desktop for the tiled Wayland session (server plus client
windows, desktop stop to leave); see docs/wayland.md.
Type these at the miniOS> prompt. The shell resolves bare names by
suffix (objects/ for .o, bin/ for .elf and bare commands,
cvm/ for .cvm), so run is optional but explicit here:
miniOS> edit src/p.c
edit> a
int main(void) { return 7; }
edit> x
miniOS> run objects/minigcc.o src/p.c > asm/p.s
miniOS> run objects/ld.o -f elf -o bin/p.elf asm/p.s
miniOS> run bin/p.elf
exit code: 7
What happened: edit wrote src/p.c to the ramdisk, miniGCC compiled C
to x86-64 assembly (redirected into asm/p.s), ld linked an ET_EXEC
binary, and run executed it as a ring-3 process. For a CVM module
instead: run objects/ld.o -f cvm -o cvm/p.cvm asm/p.s, then
run cvm/p.cvm.
Interpreters are also on board: bare micropython, lua or lisp
start a REPL, micropython src/script.py runs a file, lisp src/test.lisp
runs the in-OS Lisp suite, and python3 -c "..." runs a CPython one-liner
(needs the CPython checkout).
make test-host # all fast host suites (sync, vma, futex, percpu_rq,
# batch, rcu, sanitize, tick, pipe, panic, pci,
# httpd, sign, hal, driver, ktime, randmix, wm, fx,
# modifiers, notify, abi, wl, fat, ext4, lisp)
make test-tick test-hal # tick listener bus + HAL port mapping only
make test-lisp # Lisp interpreter vectors + in-OS suite head only
make test-wl # Wayland-mini wire roundtrip + fail-closed bounds onlyFor a live-boot check without hand-rolling QEMU flags:
tools/boot_run.sh "smp" "sb16" "run cvm/w1.cvm" --timeout 80It boots os.img, runs the commands, sends poweroff, and returns
nonzero on hang. GUI behaviour (cursor, drag, title buttons) must be
driven with tools/minios_gui.py, never headless; the GUI proofs live
in docs/spec/testing.md.
make
tools/boot_run.sh "sh src/test_all.sh" --timeout 120 # 112 PASS markers
./tools/test_bdd.sh
./tools/test_codecs.sh
./tools/mutate.sh
make test-tls
make test-vma
make test-futex test-percpu-rq test-batch test-rcu
make test-sanitize
make test-tick test-hal
make test-pipe test-panic test-pci test-httpd
make uefi.img # stub image boots under OVMF (scenario_uefi in test_bdd.sh)| Document | Purpose |
|---|---|
docs/cheatsheet.md |
shell, editor, make targets, key bindings, one-line lookups |
README.md |
full user and subsystem reference |
CLAUDE.md |
engineering contract (specs, invariants, gates) |
KNOWLEDGE_BASE.md |
generated architecture reference (all symbols, graphs) |
readmenator-agent/INDEX.md |
grep-friendly file-to-purpose map for agents |
readmenator-agent/GOTCHAS.md |
what not to change and why |
docs/KB_sync.md |
blocking synchronization layer notes |
Regenerate the analysis outputs after structural changes (see the
Project Knowledge Base section at the end of CLAUDE.md), then sync
docs/KNOWLEDGE_BASE.md from the root copy so both stay identical.