Library / SDK
rust-lang/rustc-dev-guide avatar
rust-lang/rustc-dev-guide

The rustc dev guide keeps its own Rust tools and borrows its source files from another repository

A guide to how rustc works and how to contribute to it. This is a collaborative effort to build a guide that explains how rustc works.

1,925 stars621 forksHTMLApache-2.0

At a glance

What is it?
An mdBook of compiler internals whose local build skips the link checker CI runs, whose pages only appear once added to a table of contents, and whose files that mirror compiler sources are pulled in from the compiler repository by a subtree tool.
Who is it for?
The rustc dev guide is the right place to start if you intend to contribute to the compiler rather than only to use it, and the project is unusually honest about being unfinished, naming a low review bar and offering to pair a newcomer with someone who knows the code. Two mechanics will cost you an afternoon if you meet them late.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly HTML, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • rust-lang/rustc-dev-guide1,925 ★ · +38
Star history
Repository2026-08-022026-11-21
rust-lang/rustc-dev-guide1.9k1.9k

38 Stars in the last 111 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A page that never reaches the summary file is never published

The guide is a normal mdBook, and its organisation is the first thing to understand. A summary file in the source directory is the table of contents, it links to the individual pages beside it, the configuration sits in one file at the root, images live in one subdirectory, and the built site is written to a directory under `book`.

Buried in the layout section is a note that deserves to be a heading of its own: if you do not add a page to the summary file, it will not be shown. Not a warning about a broken link, not a lint that fails in continuous integration, but silence. A new page can be complete, correct, reviewed and merged, and still not appear on the site, because nothing links to it.

That is a strange failure mode for a documentation project whose stated purpose is to help new contributors get oriented. It is also a useful constraint to understand before writing, because it means the table of contents is a design decision rather than a listing, and a page that nobody has put in it is a page the maintainers decided does not belong at that level.

The rest of the layout is small enough to hold in your head: one summary file, one book configuration, one image directory, one output directory. The repository's own language is counted as HTML rather than Markdown, which tells you the built artifact is what the statistics see.

Your local build checks fewer links than the CI build

Building the site needs three tools, installed in one command:

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

The middle one is a link checker and the third renders diagrams. Once they are installed, the development loop is `mdbook serve --open` from the root of the repository, and `mdbook build` produces a one-off static build.

Here is the part that will waste an afternoon. Link checking is not run by default locally, though it is run in continuous integration. Turning it on locally requires an environment variable on the serve command:

code
ENABLE_LINKCHECK=1 mdbook serve

So the default local experience is a build that ignores every outbound link, and the authoritative check happens somewhere else, on a machine you are not watching. A page full of links into the compiler repository can look finished on your laptop and fail on the merge request, with the failure attributed to a URL that was written weeks earlier.

The two checks are not equivalent in cost either. The link checker is the expensive one, which is the usual reason a project puts it behind a flag, and the guidance here is simply to know that the flag exists rather than to discover it from a red build.

The guide builds and tests two Rust tools of its own

Continuous integration is not a single command here. Three tools live under a `ci` directory and each is a real program with its own manifest.

Checking links is the standalone one, run with its own standalone flag. The other two are invoked through cargo against a specific manifest path. One checks semantic line breaks across the source directory, which is a style rule about where a sentence may break, and the other triages date annotations written into pages as an HTML comment, so that the maintainers can see at a glance which pages claim to be current.

code
cargo run --manifest-path ci/sembr/Cargo.toml src
code
cargo run --manifest-path ci/date-check/Cargo.toml .

And each tool has tests of its own, run by pointing cargo at whichever manifest you care about, with the tool name as a placeholder in the path rather than a wildcard.

That arrangement is worth pausing on. A documentation repository that maintains two compiled Rust linters for its own prose has accepted that the guide is a codebase, not a wiki, and that a rule like semantic line breaks is only enforceable if something can check it. The date-check tool is the more interesting of the two, because it turns staleness from a habit into a list.

Those tools are also why the repository needs a Rust toolchain at all, next to the version file and the formatting configuration that sit at the root.

Synchronizing the guide with the compiler repository

The README states that this repository is linked to `rust-lang/rust` as a josh subtree and points maintainers to `rustc-josh-sync` for synchronization. That statement alone does not mean ordinary guide changes must first be made in the compiler repository. Follow the current contribution and synchronization instructions for the paths involved.

Two vendored scripts and a custom domain sit at the root

The root of a documentation repository is where its leftovers accumulate, and this one has a few. Two JavaScript files related to diagram rendering sit at the top level rather than in the source directory, one of them a minified build. The rendering support is not vendored by accident: the install command installs a diagram renderer as one of its three tools, and the configuration for the book lives in the root file.

There is also a file containing the custom domain for the site, so the published address is configured in the repository rather than in the hosting configuration, and a mail map file for contributors, an editor configuration, a formatting configuration, a Rust version file, a configuration for the issue triage bot, and a citation file for anyone who wants to cite the guide.

There are no releases. The repository publishes continuously and has no tags to fetch, so the deployed site is the artifact and the commit history is its history. A reader who wants to know when a page changed reads the page itself and the blame view.

The examples directory is the other surprise in a book about the compiler: four example programs and a readme, named for the driver and the interface, including one that interacts with the syntax tree and one that gets diagnostics out of a compilation.

Two licence files at the root and one licence on record

The repository includes Apache-2.0 and MIT licence files. Check the repository's stated dual-licensing terms and file-specific notices for the material you intend to reuse; an automated hosting classification alone does not establish a conflict. The citation file provides metadata for citing the guide.

The first contribution is a comment, and the review bar is low

The contributing section is unusually direct about the state of the work, saying the guide is useful today but has a lot of work still to go, and that the barrier to getting a change merged is much lower than it is elsewhere. The review policy is not in this repository at all; it is a page on the project's forge, linked from the readme.

The process it describes is three steps and the first one is social. Find an issue on the tracker, post a comment on the one you want to work on so nobody duplicates you, and then open the pull request. If something is missing from the guide, the same tracker is where that goes, and the readme asks for it rather than assuming the list is complete.

The where to start section answers the question a newcomer actually has, which is what to do when you do not understand the compiler yet. The answer is that it is not a problem: the project will schedule time for you to talk with someone who does know the code, or to pair, and your job afterwards is to write up what you learned. That is a documentation contribution path disguised as a mentoring offer.

The boundary with the standard library is a link rather than a chapter. Documentation for developing the standard library lives in a separate guide with its own site, which keeps this repository about the compiler.

Editorial conclusion

The rustc dev guide is the right place to start if you intend to contribute to the compiler rather than only to use it, and the project is unusually honest about being unfinished, naming a low review bar and offering to pair a newcomer with someone who knows the code. Two mechanics will cost you an afternoon if you meet them late. A page that never reaches the summary file is never published, so a finished document that nobody can read is the most likely first mistake. The guide is linked to the compiler repository through a josh subtree; follow the current synchronization instructions for changes that cross that boundary. Before your first pull request, comment on the issue so two people do not write the same page, build with link checking on, and check whether the file you are editing is subtree managed.

Frequently asked questions

How do I build the rustc-dev-guide locally?

Install mdbook, mdbook-linkcheck2 and mdbook-mermaid with a single locked cargo install command, then run mdbook serve --open from the root of the repository. For a one-off static build, use mdbook build.

Why is my new page not showing on the site?

Because it is not in the table of contents. The summary file in the source directory links to every published page, and the readme notes explicitly that a page added without an entry there will not be shown.

How do I check links before pushing to the rustc-dev-guide?

Set ENABLE_LINKCHECK=1 when running mdbook serve. Link checking is not enabled locally by default even though it runs in continuous integration, so a plain local build will not catch a bad URL.

What are the sembr and date-check tools used for?

They are Rust programs kept in the repository's ci directory. One checks semantic line breaks across the source, the other triages date annotations embedded in pages, and each is run through cargo with its own manifest path and has its own tests.

Can I edit files in the rustc-dev-guide that came from the compiler repository?

Not durably. The repository is linked to the compiler repository as a subtree and synchronised with a separate tool, so edits to those copies are replaced on the next sync. The change has to be made in the compiler repository.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/rust-lang-rustc-dev-guide.svg)](https://hysenlabs.com/projects/rust-lang-rustc-dev-guide)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/rust-lang-rustc-dev-guide.svg)](https://hysenlabs.com/projects/rust-lang-rustc-dev-guide)

Was this useful?