# Write You a Haskell: a 25-chapter compiler book with one Rust crate per chapter

> Stephen Diehl's book builds a functional language compiler from a calculator parser to LLVM code generation and a garbage collector, with a Cargo workspace crate for chapters 2 through 24.

**sdiehl/write-you-a-haskell** — Building a modern functional compiler from first principles.

- Repository: https://github.com/sdiehl/write-you-a-haskell
- Website: http://sdiehl.github.io/write-you-a-haskell/
- Stars: 3,490 · Forks: 257
- Language: Rust
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-30 · Language: en
- Canonical page: https://hysenlabs.com/projects/sdiehl-write-you-a-haskell

## The repository is a compiler built in Rust, not Haskell source

The name suggests Haskell, but the primary language of the repository is Rust. The description reads: Building a modern functional compiler from first principles. Every chapter that has code points to a crate under crates/, and Cargo.toml lists them as workspace members with the edition set to 2024 and rust-version set to 1.99.

Chapter 7 is titled Design of Fun, and the crate for it is ch07_fun, so the language under construction has its own name. The runtime crate for chapter 24 is fun-rt-24 in the profile settings. The visible text does not say how close the finished language comes to Haskell, so read the chapters before assuming a feature exists.

The project has two licenses. The written work is under Creative Commons Attribution-ShareAlike 4.0 International, and you may reproduce and edit it with attribution. The included source is MIT, which is why the repository has both LICENSE and LICENSE-PROSE at the top level. A reuse of the code and a reuse of the prose follow different rules.

## Chapters 2 to 24 each map to a crate, and chapter 25 has none

The table of contents runs from Chapter 1, Introduction, to Chapter 25, Future Work. Chapter 1 has no code link, and neither does chapter 25. Chapters 2 through 24 each link to a folder: ch02_calc for Parsing, ch03_lambda for Lambda Calculus, ch04_stlc for Simply Typed Lambda Calculus, ch05_eval for Evaluation, and ch06_poly for Hindley-Milner Inference.

The middle of the book moves from the front end into the language itself. Chapter 8 is Layout and the Extended Parser, chapter 9 is The Renamer, chapter 10 is Typed Core and Core Lint, chapter 11 is Datatypes and Pattern Matching, chapter 12 is Records, chapter 13 is Kinds and Type Constructors, chapter 14 is Type Classes, and chapter 15 is Monads, Do Notation and IO.

Because each chapter has its own crate, you can open ch06_poly and read inference without building anything from chapters 18 to 24. The reverse does not hold. Later crates build on the earlier stages, so skipping chapters before the back end leaves you reading code whose inputs you did not see being produced.

## The back half goes from A-normal form to a precise garbage collector

Chapters 16 and 17 close out the front end of the language with Pattern-Match Compilation and The Prelude and Deriving. Then the book changes direction. Chapter 18 is A-Normal Form and Join Points, chapter 19 is Closure Conversion, and chapter 20 is Data Representation and the Runtime.

Chapter 21 is LLVM Code Generation, chapter 22 is JIT and the REPL, chapter 23 is Optimization, and chapter 24 is A Precise Garbage Collector. Chapters 20 through 24 each have a second crate named rt inside their folder, for example crates/ch20_runtime/rt and crates/ch24_gc/rt. That layout puts the runtime library next to the compiler stage that targets it.

The Cargo.toml comments show where the cost is. The tests of chapters 18 through 24 are compiled with opt-level 1 so that a ten-million-step machine regression stays practical. The fun-rt-24 runtime is set to opt-level 2 in dev and test profiles, because collecting at every allocation exercises millions of runtime calls in debug builds. If your tests feel slow, those are the settings to look at.

## Building needs Rust, just, Boehm GC and LLVM 22 before any chapter compiles

To build the chapters and the book, you install Rust, just, Boehm GC and LLVM 22. The pinned book tools are installed locally by just bootstrap. Three commands do the rest:

```bash
$ just bootstrap
$ just build
$ just book
```

bootstrap runs scripts/bootstrap.py, and the justfile puts a .tools/bin directory at the front of PATH, so the pinned tools stay inside the repository folder. build depends on a runtime recipe, which runs scripts/build_runtime.py for chapters 20, 21, 22, 23 and 24 before cargo build --workspace. That is why a plain cargo build in a fresh clone is not the documented path.

Both Boehm GC and LLVM 22 come from outside Cargo, so the book's one hard prerequisite is a system that can supply them. The repository also has a flake.nix and flake.lock at the top level, which the visible text does not describe. A rust-toolchain.toml file is present too.

## just book fails the build on any warning or error in the mdbook log

The book recipe does more than run mdBook. It runs cargo xtask syntax --check, then python3 scripts/check_book.py, then builds with mdbook build book and writes the output to build/mdbook.log. If mdBook exits with an error, the log is printed and the recipe stops. After a successful build, the recipe runs a search for the words warn or error in that log, case-insensitive, and fails if it finds one.

That gate means a stray warning in a chapter breaks the book build, so a contributor fixing a typo can find the build red because of an unrelated warning. It also means the published text has passed a syntax check of its code samples, which is a stronger guarantee than most tutorials give.

The check recipe is the matching gate for the code. It runs cargo fmt --all -- --check, then cargo clippy --workspace --all-targets -- -D warnings, then cargo test --workspace, and finally python3 scripts/check_runtime_abi.py. The workspace lints set unsafe_code to forbid and clippy all to warn, with -D warnings turning those into errors on the command line.

## The PDF path adds pandoc, Typst and four Lua filters

Reading online is the easy path, with an HTML version and a PDF both linked from the top of the page. To generate the PDF yourself:

```bash
$ just pdf
```

The pdf recipe depends on book. It runs cargo xtask pdf-collect, then pandoc converts build/pdf/book.md from markdown with tex_math_dollars and raw_attribute into Typst, using four Lua filters named links, callouts, parts and code under pdf/filters. A final step runs typst compile with the font path pdf/fonts and system fonts ignored, which makes the output independent of whatever fonts your machine has.

The recipe also fails if the pandoc log contains the text Could not convert TeX math, WARNING or ERROR. The consequence for a contributor is that pandoc and typst must be installed in addition to the Rust and LLVM requirements, and the visible instructions do not say whether bootstrap supplies them. If just pdf fails on a missing command, check those two tools first.

## Two releases in October 2026 and a contribution model built on corrections

The project has two releases listed. The release named v2.0 is dated 2026-10-12, and a rolling release named latest, described as the latest build, is dated 2026-10-28. The last push was on 2026-10-18, and the repository is not archived. A version number of 2.0 for a book means a second edition rather than an API, so the chapter list may differ from older copies you find.

The repository carries a CHANGELOG.md, a CONTRIBUTORS.md and a BUILDING.md next to the source, plus a pre-commit configuration and a dprint.json formatter config. The contributing section invites all contributions and says the author relies on the goodwill of other compiler nerds to correct grammar, clarify and fix errors. A link goes to .github/CONTRIBUTING.md.

The practical reading is that the text is still being corrected in public, so errors you find are in scope for a pull request. The latest release moves with the main branch, so pin v2.0 if you want a stable copy to follow while you type along.

## Conclusion

Read this book if you want to follow a functional compiler from parser to garbage collector in Rust with runnable code at each step, and you are willing to install LLVM 22 and Boehm GC first. Skip it if you expected a Haskell tutorial or Haskell source in the crates, because the implementation language is Rust. Before committing a weekend, run just bootstrap and just build once to see that the toolchain works on your machine.

## FAQ

### Is Write You a Haskell written in Haskell?

No. The primary language of the repository is Rust, and chapters 2 through 24 each have a Rust crate under crates/. The book builds a functional compiler, and its chapter 7 is titled Design of Fun.

### What do I need installed to build Write You a Haskell?

Rust, just, Boehm GC and LLVM 22. The pinned book tools are installed locally by just bootstrap, then just build and just book build the chapters and the book.

### What license covers the Write You a Haskell book and code?

The written work is under Creative Commons Attribution-ShareAlike 4.0 International. The included source is released under the MIT License.

## Sources

- [License: MIT](https://github.com/sdiehl/write-you-a-haskell/blob/main/LICENSE)
- [Project website](http://sdiehl.github.io/write-you-a-haskell/)
- [README](https://github.com/sdiehl/write-you-a-haskell/blob/main/README.md)
- [Releases](https://github.com/sdiehl/write-you-a-haskell/releases)
- [sdiehl/write-you-a-haskell on GitHub](https://github.com/sdiehl/write-you-a-haskell)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sdiehl-write-you-a-haskell