| # Building the Reference | |
| ## Checking out the source | |
| To build the Reference, first clone the project: | |
| ```sh | |
| 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: | |
| ```sh | |
| rustup toolchain install nightly | |
| ``` | |
| Now, ensure you have `mdbook` installed, as this is needed to build the Reference: | |
| ```sh | |
| cargo install --locked mdbook | |
| ``` | |
| [mdbook]: https://rust-lang.github.io/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. | |
| ```sh | |
| 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. | |
| ```sh | |
| 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. | |
| ```sh | |
| SPEC_RUST_ROOT=/path/to/rust mdbook serve --open | |
| ``` |