Installation

This page gets you from nothing to a running Subverge in QEMU, and then to an installed virtual disk if you want one. Subverge has only been run in QEMU (real hardware is untested, so if you try it and it works, good for you).

Requirements

You need qemu-system-x86_64 and 256 MB of RAM for the virtual machine. To build from source you also need gcc, binutils, nasm and qemu-system-x86, and to build the ISO you need grub-mkrescue, xorriso and grub-pc-bin as well.

You should already know how to program, because learn and the rest of the documentation assume it (if you don't, this is going to be a fucking rough time).

Obtaining Subverge

Each release on the releases page has the ISO attached. If you would rather build it yourself, clone the repository and run make iso, which writes build/subverge.iso (grab a drink while it builds).

$ git clone https://github.com/texivi/Subverge
$ cd Subverge
$ make iso

Development lists the other make targets.

Running the live ISO

$ qemu-system-x86_64 -cdrom build/subverge.iso -m 256M

The ISO is a live CD, so your definitions, root edits and everything else are gone when the virtual machine stops (yes, really, that's what live means). It is booted by GRUB, which is the only code in the system that was not written for Subverge (the one thing we didn't write ourselves, don't tell anyone).

Note

Subverge is a Multiboot kernel, so from a GRUB prompt you can also load it directly with multiboot /boot/subverge.elf.

Installing to a disk

An installed disk keeps your work between boots and is booted by Subverge's own bootloader instead of GRUB. Boot the ISO with a blank disk attached, run install, and pick the drive from the list it prints (dont mess this shit up mario).

$ truncate -s 64M disk.img
$ qemu-system-x86_64 -cdrom build/subverge.iso -boot d -hda disk.img -m 256M
... install
$ qemu-system-x86_64 -hda disk.img -m 256M

Warning

install erases the drive you give it. It names the drive and waits for you to type yes before writing, so never choose a disk that holds data. Read the drive name twice. If you pick your real disk you are about to have a very fucking bad evening.

The installer writes an MBR, a second stage loader, the kernel and a state area divided into fixed 1 MiB slots, one for root and one for each of the four tabs (that's a lot going onto one disk, so yeah, be careful). See Internals for the exact layout.

After the install, every successful line saves the tab that ran it and every root edit saves root, so you never need to save by hand (nice, right). Root and each tab get a 1 MiB slot.

The tour has screenshots of the whole procedure.

See also