Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Building the Reference

Checking out the source

To build the Reference, first clone the project:

git clone https://github.com/rust-lang/reference.git
cd reference

Installing mdbook

The Reference is built using mdbook.

First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed to run the tests:

rustup toolchain install nightly
rustup override set nightly

Now, ensure you have mdbook installed, as this is needed to build the Reference:

cargo install --locked mdbook

Running mdbook

mdbook provides several commands and options to help you work on the book:

  • mdbook build --open: Builds the book and opens it in a web browser.
  • mdbook serve --open: Launches a web server on localhost. It automatically rebuilds the book whenever any file changes and reloads your web browser.

The book contents are driven by a SUMMARY.md file, and every file must be linked there. See https://rust-lang.github.io/mdBook/ for more information.

SPEC_RELATIVE

The SPEC_RELATIVE=0 environment variable makes links to the standard library go to https://doc.rust-lang.org/ instead of being relative. This is useful when viewing locally since you normally don’t have a copy of the standard library.

SPEC_RELATIVE=0 mdbook serve --open

The published site at https://doc.rust-lang.org/reference/ (or local docs using rustup doc) does not set this, which means it uses relative links. This supports offline viewing and links to the correct version (for example, links in https://doc.rust-lang.org/1.81.0/reference/ will stay within the 1.81.0 directory).

SPEC_DENY_WARNINGS

The SPEC_DENY_WARNINGS=1 environment variable turns all warnings generated by mdbook-spec into errors. This is used in CI to ensure that there aren’t any problems with the book content.

SPEC_DENY_WARNINGS=1 mdbook serve --open

SPEC_RUST_ROOT

The SPEC_RUST_ROOT environment variable can be used to point to the directory of a checkout of https://github.com/rust-lang/rust. This is used by the test-linking feature so that it can find tests linked to Reference rules. If this is not set, the tests won’t be linked.

SPEC_RUST_ROOT=/path/to/rust mdbook serve --open