# 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
```