Getting Started

There are two ways to build and run the Plan 9 fork used in Principia Softwarica: using Docker (quickest), or building from source (more educational).

Option 1: Docker (quickest)

This builds everything in a container and extracts a bootable disk image:

git clone https://github.com/aryx/principia-softwarica
cd principia-softwarica
docker build -t principia .
docker run -u $(id -u):$(id -g) --rm -v "$PWD:/out" principia \
  sh -c "cp kernel/COMPILE/9/pc/9qemu /out && cp dosdisk.img /out"

Then run Plan 9 under QEMU:

qemu-system-i386 -smp 4 -m 512 -kernel ./9qemu -hda ./dosdisk.img

Option 2: Build from source

This is the more educational path. You will use the Plan 9 C toolchain itself to compile the entire operating system.

Step 1: Install goken9cc

Because Plan 9 uses a special dialect of C and non-standard assembly, you cannot use gcc or clang directly. You first need goken9cc, a fork of Ken Thompson's C compilers that can cross-compile Plan 9 from Linux, macOS, or Windows.

git clone https://github.com/aryx/goken9cc
cd goken9cc
./configure
. ./env
mk
mk install

This installs 8a, 8c, 8l (the cross assembler, compiler, and linker) as well as Plan 9 utilities like mk and rc.

Step 2: Build Plan 9

git clone https://github.com/aryx/principia-softwarica
cd principia-softwarica
# edit mkconfig and env.sh for your configuration
. ./env.sh
mk
mk kernel
mk install

This compiles all Plan 9 programs and installs the binaries in ROOT/386/bin or ROOT/arm/bin depending on the target architecture.

Step 3: Build a disk image

You need the dosfstools and mtools packages installed. Then:

mk disk

Step 4: Run under QEMU

Install qemu-system-x86, then:

mk run

This boots Plan 9 in a QEMU window. You will see the rio windowing system with a shell where you can compile programs, browse the filesystem, and explore the code described in the books.

Running on a Raspberry Pi

Plan 9 can also run on a physical Raspberry Pi. Use mkconfig.pi instead of mkconfig.pc when building, and write the resulting image to an SD card.

Requirements for reading the books

The Principia books are not introductions to programming or computer science. They assume you already have a rough idea of how a kernel works, how a compiler works, etc. You should be familiar with the C programming language and comfortable with Unix-like systems. The books cover the practice — the actual source code — not the theory.

Back to Principia Softwarica