Development

This page shows you how to build and test Subverge (you need gcc and nasm, you've been warned) and where each part of it lives in the source tree.

Building

$ make                build/subverge.elf
$ make run            boot it in QEMU
$ make iso            build/subverge.iso
$ make run-iso        boot the ISO in QEMU

The Makefile links the kernel as a 64-bit ELF and converts it to ELF32, because QEMU's -kernel option only accepts ELF32. Everything in root/ is concatenated into one blob, linked into the kernel and read at boot. The ISO is made with grub-mkrescue and a generated grub.cfg that loads the kernel with multiboot.

The build needs gcc, binutils, nasm and qemu-system-x86, and the ISO additionally needs grub-mkrescue, xorriso and grub-pc-bin.

Testing

Run the tests, or you'll be debugging this shit at 3am.

$ make host           the omega interpreter as a Linux program
$ make stress         the same, with a GC pass before every word
$ make jit-test       boot QEMU and run the JIT test script

make host builds the interpreter from the same source as an ordinary Linux program. test/host.c wraps it with a fake screen and keyboard, so the screen, keyboard, disassembler and documentation can be tested without starting a VM. Lines on stdin are typed into it, and a few directives control it:

@screen      dump the screen
@keys        queue keys
@roundtrip   save a world and reload it
@dis name    dump compiled code
@docs        check help against the dictionary

printf '@docs\n' | build/host must print 0 problems. This is how the build detects a word with no help entry.

test/qdrive.c boots Subverge, types the scripts in test/*.qd through the QEMU monitor and writes the PNG screenshots used in the tour.

Source layout

Here's where everything lives, in case you want to go digging.

The directories of the source tree are listed here.

• kernel/ holds the scheduler, which is preemptive round-robin, and the VGA text driver, the PS/2 keyboard driver, the ATA driver and the memory manager.
• kernel/omega.c is the language, with its transactional lines, undo history, mark-sweep GC, and ordinals and cardinals.
• kernel/jit.c compiles any quote that has run twice, as described in JIT.
• kernel/dis.c is the x86-64 disassembler that xray uses.
• kernel/help.c holds the documentation for every word, and the build fails when a word is missing from it.
• kernel/persist.c is the installer.
• boot/ holds the MBR and stage 2 that boot an installed drive.
• root/ holds the programs that ship with Subverge, which are written in omega. They are listed in Root.
• docs/ holds this documentation.

See also

• Internals
• Installation