Skip to content

Latest commit

 

History

History
134 lines (107 loc) · 4.82 KB

quickstart.md

File metadata and controls

134 lines (107 loc) · 4.82 KB

MiniOS Quickstart

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).

1. Prerequisites

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).

2. Fetch the sibling sources

make sources

Clones 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.

3. Build the image

make

Zero 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.

4. Boot it

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.

5. Your first in-OS program

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).

6. Verify your change

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 only

For a live-boot check without hand-rolling QEMU flags:

tools/boot_run.sh "smp" "sb16" "run cvm/w1.cvm" --timeout 80

It 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.

7. Full gate (before a commit)

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)

8. Where to read next

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.