README.md - rust-lang/reference - Git at Google

 # The Rust Language Reference

 This document is the primary reference for the Rust programming
 language.

 ## Dependencies

 - Nightly Rust
 - [mdbook](https://rust-lang.github.io/mdBook/)

 ## Installing dependencies

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

 ```sh
 rustup toolchain install nightly
 ```

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

 ```sh
 cargo install --locked mdbook
 ```

 ## Building

 To build the Reference, first clone the project:

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

 (Alternatively, if you don't want to use `git`, [download][] a ZIP file
 of the project, extract it using your preferred tool, and rename the
 top-level directory to `reference`.)

 [download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip

 Now change your current directory to the working directory:

 ```sh
 cd reference
 ```

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

 ```sh
 mdbook test
 ```

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

 To build the Reference locally (in `build/`) and open it in a web
 browser, run:

 ```sh
 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:

 ```sh
 SPEC_RELATIVE=0 mdbook serve --open
 ```

 ### `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, which is useful when viewing locally since you normally don't have a copy of the standard library.

 The published site at <https://doc.rust-lang.org/reference/> (or local docs using `rustup 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 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 will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content.

 ### `SPEC_RUST_ROOT`

 The `SPEC_RUST_ROOT` 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, then the tests won't be linked.
	# The Rust Language Reference

	This document is the primary reference for the Rust programming
	language.

	## Dependencies

	- Nightly Rust
	- [mdbook](https://rust-lang.github.io/mdBook/)

	## Installing dependencies

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

	```sh
	rustup toolchain install nightly
	```

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

	```sh
	cargo install --locked mdbook
	```

	## Building

	To build the Reference, first clone the project:

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

	(Alternatively, if you don't want to use `git`, [download][] a ZIP file
	of the project, extract it using your preferred tool, and rename the
	top-level directory to `reference`.)

	[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip

	Now change your current directory to the working directory:

	```sh
	cd reference
	```

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

	```sh
	mdbook test
	```

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

	To build the Reference locally (in `build/`) and open it in a web
	browser, run:

	```sh
	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:

	```sh
	SPEC_RELATIVE=0 mdbook serve --open
	```

	### `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, which is useful when viewing locally since you normally don't have a copy of the standard library.

	The published site at <https://doc.rust-lang.org/reference/> (or local docs using `rustup 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 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 will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content.

	### `SPEC_RUST_ROOT`

	The `SPEC_RUST_ROOT` 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, then the tests won't be linked.