Repository files navigation

This document is the primary reference for the Rust programminglanguage.

This document is not normative. It may include details that are specifictorustc itself, and should not be taken as a specification for theRust language. We intend to produce such a document someday, but this iswhat we have for now.

• Nightly Rust
• mdbook

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

rustup toolchain install nightly

Now, ensure you havemdbook installed, as this is needed in order tobuild the Reference:

cargo install --locked mdbook

To build the Reference, first clone the project:

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

(Alternatively, if you don't want to usegit,download a ZIP fileof the project, extract it using your preferred tool, and rename thetop-level directory toreference.)

Now change your current directory to the working directory:

cd reference

To test all of the code examples in the Reference, run:

mdbooktest

For authors, consider using the server functionality which supports automatic reload.

To build the Reference locally (inbuild/) and open it in a webbrowser, run:

SPEC_RELATIVE=0 mdbook build --open

This will open a browser with a websocket live-link to automatically reload whenever the source is updated.

You can also use mdbook's live webserver option, which will automatically rebuild the book and reload your web browser whenever a source file is modified:

SPEC_RELATIVE=0 mdbook serve --open

TheSPEC_RELATIVE=0 environment variable makes links to the standard library go tohttps://doc.rust-lang.org/ instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library.

The published site athttps://doc.rust-lang.org/reference/ (or local docs usingrustup doc) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links inhttps://doc.rust-lang.org/1.81.0/reference/ will stay within the 1.81.0 directory).

TheSPEC_DENY_WARNINGS=1 environment variable will turn all warnings generated bymdbook-spec to errors. This is used in CI to ensure that there aren't any problems with the book content.

TheSPEC_RUST_ROOT can be used to point to the directory of a checkout ofhttps://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, then the tests won't be linked.