Principia Softwarica

Fundamental Literate System Programs

Why Principia? · Introduction · The Books · Plan 9 · Source Code · OCaml Ports · Related Work · Getting Started · FAQ

Principia Softwarica is a series of books explaining how things work in a computer by describing with full details all the source code of all the essential programs used by a programmer. All the programs come from Plan 9 from Bell Labs, an operating system designed as the successor to Unix whose code is remarkably elegant and small.

Among those essential programs are the kernel, the shell, the windowing system, the compiler, the linker, the editor, and the debugger. Each program is covered by a separate book (see the full list).

The books not only describe the implementations of essential programs — they are the implementations. Each program comes from a literate program, a document containing both source code and documentation where the code is organized and presented to facilitate comprehension. The actual code and the book are both derived automatically from this literate program. (See more about literate programming.)

Why Principia?

The Education Gap

What happens when you type ls in a terminal window? Keith Adams — a colleague at Facebook, later Chief Architect at Slack — used this as his interview question. It is a simple question, but the answer involves the shell, the C library, the kernel, the graphics stack, and the windowing system. Most engineers cannot answer it fully. (See The Journey of ls for the complete trace.)

Today, "full stack" usually means React + Node + cloud. But the real full stack is the compiler, the linker, the kernel, and the system calls underneath. There are excellent textbooks that explain the concepts behind these programs, but almost none that show the actual source code. Principia fills that gap.

The AI Era Makes This More Important

AI is changing how we write code. Tools like Claude Code generate programs, but who evaluates the output? Who debugs the segfault? Who understands the linker error?

AI coding tools use the very programs that Principia explains. They run grep, sed, diff, awk, gcc, ld hundreds of times a day. If writing code is 20% of the job and understanding is 80%, AI is handling the 20%. The 80% — understanding what the code actually does, all the way down to the hardware — becomes everything. Machines recently went through deep learning. It is time for humans to do so too.

Introduction to the Series

• Principia Softwarica (v9) — overview of the series: motivations, Plan 9, literate programming, and a tour of all the books
• IWP9 paper — a shorter academic paper introducing the project
• IWP9 presentation slides

The Books

LOC = lines of code; LOE = lines of explanation; Pages = typeset pages.

The LOE/LOC column shows the ratio of lines of explanation to lines of code. The goal is to reach a ratio of 1.0 for every book, meaning each line of code is matched by a line of explanation. Green means the book is close to that goal, yellow means it is getting there, and red means more writing is needed.

Plan 9

Plan 9 was chosen because you can realistically understand the entire operating system. The code is written in a clean, consistent C style, and the system design follows a few powerful ideas (everything is a file, per-process namespaces, network transparency) applied uniformly.

It is not as fancy as macOS or Windows, but in essence Plan 9 provides the same core services: a kernel managing processes and memory, a windowing system, a shell, a compiler, networking, and graphical applications. Here it is running under QEMU:

How small is Plan 9? The treemap below compares the size of Linux programs (in red) with their Plan 9 equivalents (in green). The entire Plan 9 system — kernel, compiler, shell, windowing system, and all the rest — fits in 183K lines of code, almost 2x smaller than just vim (350K). This is what makes it possible to explain every line in a book series.

Learn Here, Apply Everywhere

You do not need to use Plan 9. Understanding one small elegant OS gives deep intuition about Linux, macOS, and even Windows. Many Plan 9 ideas are already everywhere: UTF-8 was invented by Thompson and Pike for Plan 9, /proc comes from Plan 9, Linux namespaces (the basis of Docker and containers) come from Plan 9, the Go language was created by Pike and Thompson with goroutines inspired by Plan 9's libthread, and the 9P protocol is used in WSL2.

The programs Principia explains — grep, sed, awk, diff, gcc, ld — are the same tools every programmer uses daily. Same concepts, expressed 100x more clearly in Plan 9. And you can use them for real: plan9port brings the Plan 9 userland (acme, sam, rc) to Linux and macOS, and goken9cc lets you use the Plan 9 C toolchain from Linux, macOS, or Windows to produce native binaries for those platforms.

Software Architecture

The diagram below shows how the different components of Plan 9 are organized, from applications at the top to hardware at the bottom. Each colored box corresponds to a book in the series.

See The Journey of ls for a trace of a simple command through every layer of the system, showing how the books connect together.

Source Code

The source code for the Plan 9 fork used in Principia Softwarica is available on GitHub:

• github.com/aryx/principia-softwarica — the Plan 9 code and literate programs

See Getting Started for instructions on how to build and run Plan 9 using Docker or from source.

OCaml Ports

Some Plan 9 programs have been rewritten in OCaml, with their own literate programming books. The OCaml ports live in xix, efuns, and mmm.

Supporting Tools

• syncweb — literate programming tool (Noweb) used to produce all the books
• goken9cc — cross-compiler to build Plan 9 from Linux/macOS/Windows

Related Work

Principia Softwarica complements three classic books:

	Project Oberon (Wirth & Gutknecht) is the closest in spirit to Principia: it presents an entire operating system with full source code, including a compiler and a windowing system. However, Oberon can only run Oberon programs — like Smalltalk, it is a beautiful self-contained world, but an isolated one. Plan 9 (and Unix) are universal: they can compile and run programs written in any language. Oberon also lacks networking and runs on custom hardware. Principia covers a wider range of programs (compiler, linker, shell, debugger, graphics, networking) on a real-world OS.
	The Elements of Computing Systems (Nisan & Schocken), also known as Nand2Tetris, builds a computer from NAND gates all the way up to Tetris. It is a wonderful pedagogical achievement, but the hardware and software are purpose-built for the course — a toy CPU, a toy OS, a toy language. Principia takes the opposite approach: it explains a real operating system with real code that runs on real hardware.
	Computer Systems: A Programmer's Perspective (Bryant & O'Hallaron), known as CS:APP, is an excellent textbook that explains the concepts behind systems programming: memory layout, linking, virtual memory, concurrency. But it stops at concepts — it does not show the source code of a real kernel, a real linker, or a real compiler. Principia complements CS:APP by showing exactly that source code, explained line by line.

About

Principia Softwarica is written by Yoann Padioleau, with code from Ken Thompson, Rob Pike, Dave Presotto, Phil Winterbottom, Tom Duff, Andrew Hume, Russ Cox, Xavier Leroy, Fabrice Le Fessant, and Francois Rouaix.

Contact: yoann.padioleau@gmail.com

Similar to Principia Mathematica, which covers the foundations of mathematics, the goal of Principia Softwarica is to cover the fundamental programs.