theBeamBook: a source-readable reference on the Erlang runtime and BEAM

What theBeamBook documents and who it is written for

The Erlang Runtime System, ERTS, and the virtual machine that executes Erlang and Elixir code, the BEAM, are documented mostly through source code and mailing list history. theBeamBook is an attempt to put that knowledge in one place. The README states the goal plainly: a collaborative, authoritative reference on the Erlang runtime system. The author, Erik Stenman, started it in 2013 and describes twelve years of starts, stops, and rewrites before version 1.0 shipped, including two cancelled publisher deals (O'Reilly in 2015, Pragmatic in early 2017) before the project returned to its original AsciiDoc build.

The audience is narrow on purpose. If you are learning Erlang syntax, this is the wrong first book. If you are debugging scheduler behaviour, reading BEAM instructions, or trying to understand why a process behaves the way it does at the runtime level, a chapter that links to a tagged OTP source file such as erl_time.h is more useful than a blog post, because you can follow the link to the exact version the text describes.

How the book is structured: chapters, statuses and OTP tags

Everything lives in AsciiDoc. Chapters sit under chapters/ as individual .asciidoc files, code samples under code/CHAPTERNAME_chapter/src and are pulled in through ap-code_listings.asciidoc, images under images/. The root file book.asciidoc is the entry point the README points readers to for a quick start.

The status system is the part worth understanding before you trust a page. Each chapter opens with a comment marking it as Placeholder, First draft, Final draft, or Done (for OTP X). That last state carries an expiry: the README notes it holds until a newer OTP version changes things. A chapter marked Done for an older OTP release is a snapshot, not a current description, and the book does not promise to track releases automatically.

Cross-references follow fixed tag conventions (CH- for chapters, P- for parts, SEC- for sections, FIG- for figures, AP- for appendices, LISTING- for code listings), and the style guide states that AsciiDoc constructs should render first for PDF, then HTML, then direct viewing on GitHub. That ordering matters if you edit: a construct that looks fine on GitHub may break the PDF build.

Installing the toolchain and building the PDF locally

The repository ships a Makefile that builds both PDF and HTML. The default target, all, depends on pdf-a4 and html, so a bare make produces beam-book-a4.pdf in the project root and an HTML copy under site/. On Debian or Ubuntu the README lists the native dependencies first, then the Ruby gems, then the build:

sudo apt install git rsync wget curl make \
                 ruby ruby-dev default-jre \
                 asciidoctor graphviz
sudo gem install asciidoctor-pdf asciidoctor-diagram rouge
make

If you would rather not install a Ruby toolchain, the README gives a container path that builds the image and then the book inside it:

make docker-build  # build the image
make docker        # build the book inside the container

The README also mentions opening the repository in your IDE's devcontainer and running make there. One Makefile detail is worth knowing if a build fails with bundle: not found: the file resolves BUNDLE by preferring a bundle on PATH, falling back to a bundler binstub under /usr/lib/ruby/gems, and finally to plain bundle, and it documents overriding it with BUNDLE=/path/to/bundle. macOS adds its own wrinkle. The README warns that macOS 15 ships ruby 2.6+ while rouge 4.5+ requires ruby 2.7+, and that Homebrew's newer ruby is not added to PATH automatically, so the documented fix is to export it and install the gems through Bundler:

export PATH=$(brew --prefix ruby)/bin:$PATH
bundle install
make

After a successful run you should see beam-book-a4.pdf in the repository root; the HTML output lands under site/.

Where theBeamBook stops being the right tool

The book is incomplete by its own account. The README asks for contributions and states that the work is far from complete, and the four-state chapter system exists precisely because large parts of the outline are unwritten or unedited. A reader who needs an answer today about a specific runtime behaviour may find the relevant chapter is a title and an outline, with an issue tracking it.

Two further limits follow from the design. First, the text is tied to OTP versions through source links and the Done (for OTP X) status, so anything you read about a data structure or an opcode can be stale relative to the OTP release you are running. Second, the book covers ERTS and the BEAM, not the OTP libraries, so questions about GenServer semantics, supervision strategies, or application packaging are outside its scope. If your problem is at the API level, this repository will not answer it, and no amount of chapter reading will change that.

How theBeamBook differs from Learn You Some Erlang and the OTP source

Learn You Some Erlang is a tutorial: it teaches the language and the standard library by building programs, and it assumes you want to write Erlang. theBeamBook assumes you already write it and want to know what happens underneath, from the emulator's perspective. The two overlap almost not at all in practice.

The closer comparison is the OTP source tree itself. Reading erlang/otp is authoritative and always current, but it is a codebase, not an explanation; the README's own linking convention (always link to a tagged OTP version, for example the OTP-19.1 erl_time.h) shows the book's role as a guided path into that source rather than a replacement for it. A third option is the printed first edition, which the README links to on Amazon in the US, UK, DE and SE stores. The print copy is fixed at 1.0, while the repository continues to change, so the online and PDF versions will drift ahead of the printed text.

Contributing, maintenance and what the licence allows

The repository is not archived, and the last push was on 2026-09-05. Releases are tagged rather than continuous: v0.1.3 and v0.1.4 in March 2025, and v1.0 in June 2025, which the README calls the First Edition and which is also the version in print. There is no documented release cadence, and the README does not describe a rollback or deprecation policy for chapters, so treating any single build as a stable reference has limits.

The licence is CC BY 4.0, attributed to Erik Stenman. That is a content licence, not a software one, and it is the licence the README says all contributions fall under. In practical terms, attribution is the condition you have to satisfy when you reuse text or diagrams, but the repository's LICENSE file is the document that governs, and anyone redistributing the book commercially should read it rather than take this summary as sufficient.

Contributing has a documented shape. Open an issue or a pull request; for larger rewrites, check the chapter's status comment and existing issues and coordinate with active authors first. The Makefile generates chapters/contributors.txt from git shortlog, and, when the gh CLI is present, from issue and pull request authors, so contributors appear in the built book without manual editing.

Editorial conclusion

Adopt theBeamBook if you already write Erlang or Elixir and need a citable description of ERTS internals, or if you want to contribute chapters under CC BY 4.0. Do not adopt it as a language tutorial or as an OTP API reference; it documents the runtime, not the standard library. Before relying on a chapter, open its .asciidoc file and read the status comment, since the book marks each chapter as Placeholder, First draft, Final draft, or Done (for OTP X), and the README states the work is far from complete.

Frequently asked questions

Official sources

1. happi/theBeamBook on GitHub
2. Issues
3. README
4. Releases