| # 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 |
| rustup override set 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 |
| ``` |
