rustc-dev-guide: the map of the Rust compiler, and how to add to it

The gap the rustc-dev-guide fills, and the readers it assumes

Reading rustc source cold is a bad first experience. The compiler is organized around phases and intermediate representations, and nothing in the source tree tells a newcomer which directory to open first. The guide's stated aim is orientation: it is a collaborative effort to explain how rustc works, written for people who are new to the compiler as well as for experienced contributors who need to figure out a part they have not worked on before. That second audience matters more than it sounds. Most people who open the guide already write Rust; what they lack is a mental model of the compiler's pipeline.

It is worth being precise about what this project is not. It is not a book about the Rust language, and it is not a reference for the standard library: the README points readers to std-dev-guide for that. The repository is predominantly HTML, because the pages are Markdown rendered into a static site by mdBook. So the deliverable is documentation, and the code in the repository exists to build and check that documentation, not to compile programs.

How the mdBook is put together and where a page has to be registered

The layout follows mdBook conventions. A src/SUMMARY.md file is the table of contents and links to the individual pages under src/. Images live in src/img. Configuration lives in book.toml, and the built output is written to book/html. The README carries a warning that is easy to miss and expensive to discover late: if you do not add a page to SUMMARY.md, it will not be shown. A contributor can write a perfectly good chapter and still ship a site that never links to it.

Three small tools under ci/ enforce consistency. Link checking is handled by mdbook-linkcheck2, semantic line breaks by a binary built from ci/sembr, and stale-content annotations marked with date-check comments by a binary built from ci/date-check. Each tool has its own Cargo manifest and its own tests, runnable with cargo test --manifest-path ci/<tool>/Cargo.toml. There is also a josh subtree link between this repository and rust-lang/rust, with synchronization performed through the rustc-josh-sync tool and documented under src/external-repos.md. That coupling is the structural reason the guide has to track compiler changes rather than being written once.

Installing mdBook and serving the guide locally

The README gives one install command, pinned with --locked, for mdBook plus the two plugins the build expects:

cargo install --locked mdbook mdbook-linkcheck2 mdbook-mermaid

From the repository root, the development server builds the site and opens a browser:

mdbook serve --open

For a one-off build that writes into book/html without serving, the README names mdbook build. Link checking is deliberately off in local builds and on in CI. To turn it on locally, set the environment variable exactly as the README shows:

ENABLE_LINKCHECK=1 mdbook serve

A first real use is a small documentation fix rather than a compiler change. Find the page under src/, edit the Markdown, confirm it is referenced from src/SUMMARY.md, and re-run mdbook serve. If the page does not appear in the navigation, the SUMMARY.md entry is the reason.

The review bar is lower than rustc's, and that is the point

The README states that the guide has a much lower bar for what it takes for a PR to be merged than the compiler repository does, and links to the forge documentation for the review policy. That asymmetry is deliberate and it shapes how you should use the project. You do not need to understand the compiler to contribute. The README addresses this directly: if you do not know how the compiler works, the project will schedule time for you to talk with someone who does, or to pair with you on figuring it out, and then you write up what you learned. The contribution path is therefore social before it is technical, which is unusual for a repository in the rust-lang organization and worth knowing before you open a pull request.

The practical consequence is that the guide's accuracy depends on contributors who had access to someone who knew the code. Where that pairing did not happen, or where the compiler moved afterwards, a page can read as authoritative while describing an older design. The date-check tooling exists because the maintainers know this.

Where the rustc-dev-guide is the wrong tool

If you want to compile Rust code, this is the wrong repository. Nothing here is a compiler, and the README's build instructions produce a static HTML site, not a toolchain. For language questions, the guide is also the wrong place: it assumes you already write Rust and are asking about the compiler's internals.

The harder limitation is coverage. The README says the guide is useful today but has a lot of work still to go, and that sentence is not boilerplate. Sections of the compiler are documented thinly or not at all, and the project treats missing content as an issue to file rather than a hidden gap. There are no releases in the repository record, so there is no versioned snapshot of the guide to pin against a specific compiler revision; the site tracks the main branch. If you need a stable, citable description of a rustc pass at a fixed version, this project does not offer one, and the josh subtree synchronization means content can shift under you.

How it differs from the standard library guide

The obvious sibling project is std-dev-guide, which the README names as the place to go for documentation on developing the standard library. The split is by subject rather than by format: both are contributor-facing guides, but rustc-dev-guide covers the compiler while std-dev-guide covers the library. Choosing between them is not a matter of preference, it is a matter of which part of the toolchain you intend to change. If your patch touches core, alloc or std, the compiler guide will not help you, and the README says so in one line rather than duplicating the material.

That division has a cost for anyone working across the boundary, since a change that adds a library feature may require reading both. It also means the compiler guide can stay focused on phases, IRs and driver interfaces, which is the material the examples/ directory illustrates with files such as rustc-driver-example.rs and rustc-interface-getting-diagnostics.rs.

Maintenance, synchronization and licence

The repository record does not give a last push date, so there is no basis for describing the repository as actively maintained; what can be said is that it is not archived. The maintenance work that is visible is tooling: link checking with mdbook-linkcheck2 in CI, semantic line break enforcement, and date-check triage of stale annotations. The josh subtree relationship with rust-lang/rust is the ongoing cost, because compiler changes have to be reflected back into prose through the rustc-josh-sync tool. Upgrading the guide itself is not a versioned operation; you re-clone or pull and rebuild with the same mdbook command.

On licensing, the repository ships both LICENSE-APACHE and LICENSE-MIT and the project is listed as Apache-2.0, which is the usual dual-licence arrangement for Rust project repositories. If you intend to reuse substantial portions of the text elsewhere, read both files and the CITATION.cff rather than assuming a single licence applies to every file. That is a factual observation about what is in the tree, not legal advice.

Editorial conclusion

Adopt it if you are preparing a first patch to rustc, or if you keep needing to look up a compiler phase you have never touched; the guide exists exactly for that orientation problem, and its lower review bar means small corrections are welcome. Do not adopt it as a reference for writing Rust programs, and do not expect complete coverage of every pass: the README states plainly that the guide has a lot of work still to go. Before relying on a page, check that it is linked from src/SUMMARY.md, since the README warns that an unlinked page will not be shown, and run the date-check tool over the repository to see which sections carry stale annotations.

Frequently asked questions

Official sources

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