# Making a programming language

Alfonso Campodonico · 2026-11-15 · https://alfonsocampodonico.com/posts/making-a-programming-language

> Text goes in, a binary comes out. Everything a compiler does in between.

## Why make one

I'm making a programming language.

Naming is hard, so until it has a name it's ████ here, and `obfuscated` in commands.

I wanted a program to compile down to what it actually needs and nothing more, and to be secure by default, not after an audit. How it does that gets its own post. This one is about the machine underneath: how text you type becomes a program that runs.

The short version: a compiler is a line of small programs, each turning one shape into the next. Text becomes tokens, tokens become a tree, the tree gets checked, and then either an interpreter runs it or it becomes a native binary. No single stage is hard. The work is in making errors useful and keeping two backends in agreement.

## How it works, in one minute

1. **Lexer.** Reads the text and cuts it into tokens: `fn`, `area`, `(`, `3.14`.
2. **Parser.** Turns the tokens into a tree that says what goes inside what.
3. **Checker.** Walks the tree and works out every type. A mistake stops here, with a code, a place and, where there is one, a fix.
4. **Interpreter.** `obfuscated run` walks the checked tree and runs it straight away, with no compile step.
5. **Native backend.** `obfuscated build` lowers the tree to a simpler form, decides where memory is freed and turns it into a binary.

It's like a kitchen line. One station preps, one cooks, one plates, and each hands the next something in the shape it expects. If the prep is wrong, it should be sent back at prep, not found on the plate.

## The deep dive

### A small program

Here's the kind of thing it runs, trimmed from one of its examples:

```obfuscated
enum Shape {
    Circle(Float),
    Rect(Float, Float),
    Point,
}

fn area(s: Shape) -> Float {
    match s {
        Circle(r) => 3.14159 * r * r,
        Rect(w, h) => w * h,
        Point => 0.0,
    }
}

fn main(root: Root) {
    let shapes = [Circle(1.0), Rect(2.0, 3.0), Point]
    let total = shapes.map(|s| area(s)).fold(0.0, |acc, a| acc + a)
    root.stdout.print("total: {total}")
}
```

Enums that carry data, a `match` the checker makes you finish, closures, and strings with `{...}` inside them. (`main` taking `root` is the part for the next post.)

### Front end: text to a checked tree

*Interactive diagram on the page: From source to a native binary.*

The lexer is about 200 lines. It interns names as it goes, so later stages compare a number instead of a string.

The parser is recursive descent: one function per kind of thing (a function, a statement, a `match`), each calling the others. Binary expressions use Pratt parsing, where each operator has a binding power and the parser keeps going while the next operator binds tighter. That's how `1 + 2 * 3` ends up as `1 + (2 * 3)` without a grammar table.

The checker is the biggest piece, about 2,300 lines. It works out every type, makes sure every `match` covers every case, and turns mistakes into diagnostics. Each one has a stable code, a span, an explanation (`obfuscated explain E0105`) and, where possible, a fix a tool can apply on its own:

```console
$ obfuscated check bad.obfuscated
error[E0105]: there is no `unwrap_or`; write `value ?? default`
  --> bad.obfuscated:2:29
   |
 2 |     let n = "4".parse_int().unwrap_or(0)
   |                             ^^^^^^^^^
  = help: write it with `??`
```

That error exists because the agents I tested it on (below) kept typing `unwrap_or`. Recognising the spelling someone will reach for and pointing at the right one costs a few lines, and it saves every person and every agent a round trip.

### Two backends

`obfuscated run` hands the checked tree to an interpreter. It starts instantly, which is how most code runs while it's being written.

`obfuscated build` goes the long way. The tree is lowered to a typed IR, where generic functions get one copy per type they're used with. A pass places reference counts. Then it's linked with the runtime into one binary.

The native build is the slow path. A 600-line program that pulls in the HTTP library takes about 3 s to build cold. So builds are cached by a digest of what was generated and the flags used, and an unchanged rebuild takes 8 ms.

### Memory without a garbage collector

There's no garbage collector and no lifetimes to write. The compiler inserts reference counts instead, and the trick is in where.

The ownership pass runs a liveness analysis backwards over each function to find the last use of every variable. A last use moves the value instead of copying the reference, and the value is freed right after it, at the start of a branch that doesn't use it, or before a `break` or `return`. Moving on the last use is what keeps most counts at 1. And a value with a count of 1 has one owner, so `xs.push(x)` or `xs[i] = v` changes it in place, with no copy.

The approach comes from Perceus, the reference counting in the Koka language, without its reuse step. It's the part of the compiler I'd least want to get wrong, which is why the tests check it on every program (below).

### The runtime

Every native program gets the same runtime: reference counting, the standard library's built-ins, a scheduler that runs tasks as small fibers across every core with work stealing, kqueue on macOS and epoll on Linux for I/O, and TLS through OpenSSL. The standard library on top, about 3,600 lines in ten modules, is written in ████ itself.

### Keeping the two honest

Two backends are two opinions about what a program means. That's a feature if you make them argue.

Every test program runs in both, and the outputs must match: integers wrap, floats round and maps iterate in the same order in each. The native builds run under AddressSanitizer and must finish with no object still alive, which is how a mistake in the ownership pass shows up as a failed test instead of a leak in production. Programs that run tasks in parallel also run under ThreadSanitizer. That's 1,080 tests today.

### Making the interpreter fast

The first interpreter was slow in ways that were easy to find once I looked. One round of profiling:

- **Names became short lists** instead of hash tables.
- **Calls remember their target**, so a function is looked up once, not on every call.
- **Numbers and map keys compare directly**.
- **A list being built changes in place.** Before, every `push` copied the whole list.

`fib(32)` went from 1.57 s to 0.36 s. Pushing 200,000 items onto a list went from 70 s to 0.047 s, which is what copying the whole list on every push will do to you.

### Can a model write it?

A language this new has no code online to learn from. So I tested whether a model could write it from the spec alone. Five fresh agents got only the spec (about 29,000 tokens) and the command line, 10 tasks each, with no access to the compiler, tests or examples. They solved 50 of 50, in both backends, graded against answers computed by separate Python code.

Their complaints were worth more than the score: no ranges or tuples yet, a bare parse error when a keyword was used as a name, `split` keeping empty pieces without saying so. Each one became a fix to the spec or the compiler.

### It serves its own book

The language's documentation is a one-page book, and the server it comes from is a ████ program. The page is compiled into the binary with `embed("dist/index.html")`, so the running server reads no files: it answers `/` with the book, `/up` with `ok`, and everything else with a 404.

## What's next

- **A name.** Naming is still hard.
- **The security model.** Why `main` takes `root`, and what a program can and can't touch. That's the next post.
- **Faster cold builds.** A precompiled standard library, so it isn't compiled into every program, and a Cranelift backend for quick debug builds.
- **A package registry.** Dependencies come from paths or git today, pinned by a lock file.

## What I learned

- **The stages are the easy part.** Each one is small. The work is in the seams: errors that point at the fix, and two backends that agree.
- **Test the thing you're scared of.** Running every program under a sanitizer, in both backends, is what made the memory pass safe to change.
