Mapping High Level Constructs to LLVM IR: a gitbook with a warning attached

The README opens with a caution, and that is the first thing to read

Before the title, the README leads with a CAUTION block, and it is unusually blunt about the state of the repository.

The LLVM code listing in this repository are pretty much out-of-date and do not work with recent LLVM versions. The parenthetical explains why, saying this was written before opaque pointers became a thing in LLVM. The block then invites forking and pull requests but says not to expect any major updates to the guide.

That honesty is the first useful thing about the project, because a document like this can easily be mistaken for a maintained reference. It is not one, and the author says so in the first paragraph. A reader who takes the listings as current LLVM IR will find that they do not even parse on a modern toolchain, and a reader who takes the prose as LLVM's official position on how a construct should be lowered will find the opposite: the prose is a teaching approach, and LLVM's own behaviour is one valid lowering among several.

The last push to the repository was on 2026-08-19, the project is not archived, and it publishes no GitHub releases. The homepage is the ReadTheDocs site, mapping-high-level-constructs-to-llvm-ir.readthedocs.io.

So the correct way to read this repository is as a book that is frozen in time. The chapters still teach the right things. The listings are illustrations of a dialect of LLVM IR that no longer exists.

What the book is trying to do

The About section states the goal plainly: it is a gitbook dedicated to providing a description on how LLVM-based compilers map high-level language constructs into the LLVM intermediate representation.

The audience is stated too. It targets people interested in how modern compilers work who want to learn how high-level language constructs can be implemented, and the document says it should help make the learning curve less steep for aspiring LLVM users. Contributions about other languages targeting LLVM are described as highly welcome, though currently the book focuses on C and C++.

That framing puts it in a specific gap. The official LLVM documentation is a reference, and the reference is not organised by the shape of the source language. This book is organised by the shape of the source language, which is what you want when the question you have is about the language rather than about the IR.

Two simplifications are declared up front, and they matter for reading the listings. The first is that the text works with a 32-bit target machine, so that pointers and word-sized operands are 32 bits. That choice removes a layer of noise from every example, because you are not constantly reasoning about pointer width, and it costs you the ability to copy an example directly into a 64-bit project without editing it.

The second is that names are not mangled. For readability they are given simple, easy-to-read names that reflect their purpose. The book is explicit about the cost: a production compiler for any language that supports overloading would generally need to mangle the names so as to avoid conflicts between symbols. So the listings show you a world where a function is called by a name you can read, and the mangling machinery is a chapter or an omission rather than an assumption.

The chapter structure is a map of the language

The top-level directory listing is the book's table of contents, and it is a syllabus for learning a language in terms of its implementation.

The opening chapters are a-quick-primer and basic-constructs, followed by control-structures. Then come the parts that are where a language front end earns its keep: advanced-constructs, object-oriented-constructs, exception-handling, and interoperating-with-a-runtime-library. The last two chapters are the ones most people never find explained anywhere else. interfacing-to-the-operating-system covers what happens at the boundary with the system, and an appendix-a-how-to-implement-a-string-type-in-llvm walks through a specific implementation problem end to end.

An appendix on implementing a string type is a good sign about the book's intent. It means the author was not content to describe what compilers do, but went looking for the case where the description has to be made concrete, where you have to decide how a value is laid out, how it is passed, how it is freed. That is the level at which a compiler book stops being a survey.

The chapter list also shows the coverage limits. There is nothing about generics or templates as a separate chapter, nothing about coroutines, nothing about modules or packages, and no coverage of languages other than C and C++. The advanced-constructs chapter may cover some of that ground, but the structure suggests a focus on the core of the two languages.

The chapter list is also visible on the rendered site, and the appendix on string types and the epilogue chapter are the two to sample first if you are deciding whether the depth is there. A book that includes an epilogue and a worked appendix is usually written by somebody who wanted to finish the job rather than outline it.

Building the book: Sphinx on the host or in a container

The building section gives two routes, and the host route is the quick one.

The project is cloned into a directory named llvm-ir, and on Ubuntu the dependencies are a build-essential install for Make and friends, python3-pip, python3-sphinx and python3-sphinx-rtd-theme. The build itself is make html, and the output lands in the _build/html folder, which you can then browse locally.

The Docker route exists for people who would rather not install Sphinx. The Makefile has a docker-build target that creates an image named llvm-ir, and a docker-make target that runs make inside the container with the current directory bind-mounted, so the output still appears in _build/html on the host.

The Dockerfile is where the care shows. It starts from ubuntu:rolling, takes the native UID and GID as build arguments, and recreates the container's user and group to match your host user. The comment explains why, to avoid getting output files owned by root, and the Makefile repeats the instruction that the command requires sudo, or alternatively that you add yourself to the docker group, which it marks as insecure.

The image also installs the LLVM toolchain itself. The Dockerfile runs the llvm.sh script from apt.llvm.org, which is the standard way to add the LLVM apt repository and install the toolchain. The set of packages is small and deliberate: make, python3-sphinx and python3-sphinx-rtd-theme, with no recommends.

The Makefile itself is described in its own comment as a minimal makefile for Sphinx documentation, and it works by routing everything to sphinx-build's make mode. The O variable is a shortcut for Sphinx options, which is why the container target is invoked as docker-make O=html and why the help target works with a bare make.

Reading it: ReadTheDocs first, and the external links

The recommended way to read the book is online at ReadTheDocs, and that is what the README says before it says anything about building. The local build exists for people who want to read it offline or work on it, not as the primary path.

The book also has a section of external resources on LLVM IR, which is short and curated. There is the LLVM getting started and tutorials page, A Gentle Introduction to LLVM IR, and a post on mapping Python to LLVM IR. The section closes by inviting readers to open an issue or submit a pull request to add links.

Those three links tell you what the book is and is not. It is not a replacement for the LLVM tutorial, which is about using the tools. It is not the only introduction to IR, since the gentle introduction exists. And the Python link is there because the book's own scope is C and C++, and a reader who wants to see the same concepts applied to another language has a pointer. That is also why contributions about other languages are welcomed, since the book itself is the multi-language comparison once they arrive.

The contributing section is brief: all contributions are welcome, and if you find an error you file an issue or create a pull request. Combined with the caution block, the picture is consistent: a well-organised teaching document that its author has frozen and handed over, with the invitation to fork it rather than to expect it to be modernised.

What to use instead, and what this is still good for

The honest alternative to a dated listing is the current LLVM documentation, and the book itself points at it. The language reference for LLVM IR and the LangRef in particular are where the current rules live, including how opaque pointers changed the picture that broke the listings in this repository.

The difference in kind is what matters. LangRef is normative and organised around the IR itself, and it changes. This book is pedagogical and organised around the source language, and it does not change. A reader asking what does a for loop compile to has a different question from a reader asking what is the exact semantics of getelementptr, and the two documents answer different ones.

There is also a real gap that neither fills. The book explains the mapping decisions, including the compromises: what a virtual call costs, what a closure needs, how an exception unwinds through frames the compiler does not control. Reference documentation states the rules and stops there. A learner who has never seen a language front end needs the reasoning before the rules make sense, and that is the space this book occupies.

For a current project, the sensible combination is to read the chapters for the concepts, then check each construct against the current LLVM documentation and against the IR your own toolchain emits, which you can do by compiling a small example and inspecting the output. The 32-bit assumption and the unmangled names mean the listings will not match a real build in two visible ways even where the structure is still right, and the opaque pointer change means the pointer types will not match either. The concepts survive the transition. The text does not get updated for you.

Editorial conclusion

Read the gitbook if you are trying to understand how a language feature becomes LLVM IR and want a readable chapter-per-topic walkthrough rather than a reference manual, and if you are willing to hold the listing in your head as a sketch rather than as working code. Do not rely on the IR listings themselves, because the README states plainly that they are out of date, do not work with recent LLVM versions, and were written before opaque pointers became a thing, and the same note says not to expect major updates. Before you rely on it for anything current, read the caution block at the top of the README, check a listing against the LLVM documentation for your version, and treat the online ReadTheDocs build as the canonical version of the text.

Frequently asked questions

Official sources

1. f0rki/mapping-high-level-constructs-to-llvm-ir on GitHub
2. Issues
3. Project website
4. README