rustc-dev-guide: A Practical Map of the Rust Compiler's Internals

What the Guide Solves and Who It Serves

The rustc-dev-guide solves a specific problem: the Rust compiler is a large, complex codebase with no single official tutorial for its internals. New contributors often do not know where to start, and even experienced ones hit unfamiliar subsystems. The guide is a collaborative effort to explain how rustc works, aimed at helping new contributors get oriented and helping experienced people explore parts of the compiler they have not touched. It is not a reference manual or a spec; it is a narrative walkthrough. The README states the aim directly: to help new contributors get oriented, as well as to help more experienced folks figure out some new part of the compiler. That dual audience shapes the content, which ranges from high-level architecture to specific compiler passes. If you are a Rust user who never plans to touch compiler internals, this guide is not for you. It is for people who want to read, patch, or extend rustc itself.

How the Guide Is Built and Organized

The guide is a standard mdBook project, which means it is a static site generated from Markdown files. The repository layout is explicit: a src/SUMMARY.md table of contents links to individual pages under src/, configuration lives in book.toml, images are in src/img, and build files are in book/html. The key constraint is that any page not added to SUMMARY.md will not be shown. That is a real gotcha for contributors, because it is easy to write a page and forget to link it. The README warns about this with a note in all caps. The content is written in Markdown, and the build produces a static HTML site. The guide also links to a separate std-dev-guide for standard library development, so the two projects do not overlap. This separation is a deliberate choice: rustc internals and std internals are different enough to warrant their own documentation.

Getting It Running Locally

To build the guide locally, you need to install mdbook and two plugins: mdbook-linkcheck2 and mdbook-mermaid. The README gives the exact command: cargo install --locked mdbook mdbook-linkcheck2 mdbook-mermaid. Then you run mdbook serve --open in the repository root, which starts a local server and opens the site in your browser. For a one-off build, use mdbook build. One detail stands out: link checking is not run by default locally, even though it runs in CI. You have to set the environment variable ENABLE_LINKCHECK=1 to enable it, as in ENABLE_LINKCHECK=1 mdbook serve. That is a useful distinction because it means your local build can be fast, but you might miss broken links until CI catches them. The mermaid plugin suggests that some diagrams are rendered as Mermaid charts, which is common in technical documentation for showing data flow or compiler phases.

The Contribution Workflow and Its Low Bar

Contributing to the guide is intentionally easier than contributing to rustc itself. The README says the guide has a much lower bar for what it takes for a PR to be merged, and it points to the forge documentation for the review policy. The workflow starts with picking an issue from the tracker and posting a comment to avoid duplicate work. If you think something is missing, you open an issue. The interesting part is the guidance for people who do not know the compiler: the README says that is not a problem, and the process pairs you with someone who knows the code or wants to pair with you. That is a collaborative writing model where you learn by talking to an expert and then write up what you learned. This is a practical approach for a complex codebase, because it turns knowledge transfer into documentation. However, it also means the guide's accuracy depends on the availability of knowledgeable volunteers, which can be a bottleneck.

Maintenance Tools and the Josh Subtree Sync

The guide has a real maintenance cost, and the README is honest about it. There are several CI tools under ci/, each with a specific command. Link checking uses mdbook-linkcheck2 --standalone. Semantic line breaks are checked with cargo run --manifest-path ci/sembr/Cargo.toml src. Date-check annotations, which are likely used to flag outdated content, are triaged with cargo run --manifest-path ci/date-check/Cargo.toml . Each tool can be tested with cargo test --manifest-path ci/<tool>/Cargo.toml. The most significant maintenance aspect is that the repository is linked to rust-lang/rust as a josh subtree. That means changes can be synchronized between the two repositories using the rustc-josh-sync tool, and there is a guide on how to do it. This is a complex setup. If you are a casual contributor, you do not need to worry about it, but if you are a maintainer, you must understand josh and the sync process. The date-check tool suggests that content can become stale, which is a genuine limitation for a guide about a moving target like rustc.

Limitations and When It Is the Wrong Tool

The guide is not a substitute for reading rustc source code. It is a guide, not a reference, and the README does not claim completeness. One clear limitation is that the guide can become outdated. The date-check tool exists precisely to flag stale content, and the josh subtree sync means the guide is tied to a specific state of rustc. If you are working on a very recent compiler change, the guide may not reflect it. Another limitation is the scope: it covers rustc, not the standard library. For std development, you need the separate std-dev-guide. The guide is also not a tutorial for writing Rust code; it assumes you know Rust and want to understand the compiler. If your goal is to learn Rust itself, this is the wrong tool. The low merge bar is a double-edged sword: it makes contribution easy, but it can also lead to uneven quality across sections, since the review policy is less strict than for the compiler itself. The README acknowledges the guide is useful today but has a lot of work still to go.

Alternatives and How They Differ

The most direct alternative is the official rustc documentation, which includes the compiler's own API docs and the rustc book. The rustc book is a separate project that focuses on compiler user-facing features, like command-line flags and crate types, not on internals. The rustc-dev-guide fills a different niche: it explains how the compiler is built. Another alternative is reading the rustc source code directly, which is always the ground truth, but it lacks the narrative structure that the guide provides. The std-dev-guide is a sibling project for the standard library, but it is not an alternative for rustc internals. There is also the forge documentation, which covers the review policy for the guide but not the compiler's architecture. The key difference is approach: the rustc-dev-guide is a community-written, prose-heavy walkthrough, while the official docs are more reference-oriented. If you need a quick answer about a specific compiler function, the API docs are faster. If you need to understand a concept like the borrow checker's implementation, the guide is better.

Licence and Upgrade Path

The repository is licensed under Apache-2.0, which is a permissive open source license. That means you can reuse the guide's content in your own documentation, with attribution, and you can modify it. This is a practical advantage if you want to create a fork or integrate parts into your own project. The guide is not a software library, so the usual dependency upgrade concerns do not apply. Instead, the upgrade cost is in keeping the content current. The date-check tool and the josh sync are the mechanisms for that. The README does not describe a release process; there are no recent releases retrieved, so the guide is likely updated continuously on the main branch. That means you should always use the live site or the latest main branch, not a snapshot. If you are reading a cached copy, it may be stale. For contributors, the upgrade path is simple: pull the latest main, run the CI tools locally, and submit a PR. The maintenance burden is real but documented, and the tools are explicit commands, not vague processes.

Editorial conclusion

Adopt the rustc-dev-guide if you are a new contributor to rustc or an experienced one exploring unfamiliar compiler areas, and if you prefer a community-maintained, low-barrier entry point over official API docs. Do not use it as a replacement for reading rustc source code or for learning the standard library, which has its own guide. Before relying on a section, verify its recency by checking the date-check annotations and the last sync with rust-lang/rust, since the guide is a josh subtree and may lag behind compiler changes. The guide is Apache-2.0 licensed, so you can reuse it with attribution, but the real cost is maintenance: you must run the sembr and date-check tools and keep the josh sync working, which is a concrete commitment. If you want to contribute, start by picking an issue from the tracker and posting a comment, then write a page and add it to SUMMARY.md, or it will not be visible.

Official sources

1. Official documentation
2. Official README
3. Project repository