| commit | aca918d191c862771882d945bbde20b4a44b98b8 | [log] [tgz] |
|---|---|---|
| author | Travis Cross <tc@traviscross.com> | Wed Apr 16 22:42:32 2025 +0000 |
| committer | Travis Cross <tc@traviscross.com> | Wed Apr 30 16:20:45 2025 +0000 |
| tree | 23ff7d675d5618bdbbea37cbe5ada859441a603d | |
| parent | 3340922df189bddcbaad17dc3927d51a76bcd5ed [diff] |
Remove apologies about the Reference Right now the Reference, in its README and introduction, contains a number of warnings and caveats that amount to apologies about the document. These have outlived their usefulness and should be removed. The Reference is the reference on Rust. It's the product of an enormous amount of careful work by many people. It's a good document, and we don't need to apologize about it. In particular, these apologies don't need to be the very first things we say about the document. We don't need to warn people off from it. Given how we frame it at the moment, a reader could reasonably think, "well, if that's all its own authors think of this document, why should I waste my time with it?", and anecdotally, this is something that I've observed people reflecting back to us. Let's stop this negative cueing. Does the Reference have bugs or omissions? Sure. It always will. So does and will our compiler. We can simply point people to our issue tracker in a note; we don't need for this to be a warning, and we don't need to elaborate. Do we need to say the Reference is non-normative? No. We treat it with all the care and respect that we would any normative document, and we have for many years. We author it in normative language, and we take care to ensure that the substance of this normative language accords with normative lang team decisions. The lang team directly FCPs changes to the Reference when those changes affect the guarantees that are made by the language. Do we need to say that our descriptions of the language are "informal"? No, not in general. We work to describe things as precisely and correctly as we can. While such statements might not be "formal" ones, neither are they "informal". Do we need to say that it's not a specification? No. What is a specification anyway? We'd have to answer that before saying that it's not one. The Reference is the Reference. That's all we need to say. The text speaks for itself. Let's remove those things that have outlived their usefulness to us.
This document is the primary reference for the Rust programming language.
First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests:
rustup toolchain install nightly
Now, ensure you have mdbook installed, as this is needed in order to build 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 use git, download a ZIP file of the project, extract it using your preferred tool, and rename the top-level directory to reference.)
Now change your current directory to the working directory:
cd reference
To test all of the code examples in the Reference, run:
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:
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
SPEC_RELATIVEThe 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_WARNINGSThe 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_ROOTThe 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.