mirror of https://github.com/rust-lang/reference
Add `rust-toolchain.toml` and revise README
We spent a lot of text in the README describing how to use the nightly Rust compiler with this project. Let's instead add a `rust-toolchain.toml` file so that the nightly compiler is used automatically, and let's redraft the README in that light. With this revision, we'll add a section on installing dependencies in which we'll describe how to ensure that the nightly compiler is installed and up to date and how to install `mdbook`. When describing how to clone the project, we'll suggest that people clone the URL ending in `.git`. This is what GitHub recommends, and it removes a level of redirection which sometimes matters. For people who want to download a ZIP file rather than using `git`, we'll provide a direct link rather than simply referencing the GitHub page. When describing how to build the book, we'll suggesting passing `--open` to `mdbook`, as this is usually what people will want, and it will save a step. Along with these changes, we include some general copyediting.
This commit is contained in:
parent
1a23297a23
commit
81b8df4323
72
README.md
72
README.md
|
@ -10,58 +10,54 @@ what we have for now.
|
|||
|
||||
## Dependencies
|
||||
|
||||
- rustc (the Rust compiler).
|
||||
- [mdbook](https://rust-lang.github.io/mdBook/) (use `cargo install
|
||||
mdbook` to install it).
|
||||
- rust nightly (you would be required to set your Rust version to the
|
||||
nightly version to make sure all tests pass).
|
||||
- Nightly Rust
|
||||
- [mdbook](https://rust-lang.github.io/mdBook/)
|
||||
|
||||
## Build steps
|
||||
## Installing dependencies
|
||||
|
||||
To build the project, follow the steps given below:
|
||||
First, ensure that you have a recent copy of the nightly Rust compiler
|
||||
installed, as this is needed in order to run the tests:
|
||||
|
||||
Clone the project by downloading the ZIP from the [GitHub
|
||||
page](https://github.com/rust-lang/reference) or run the following
|
||||
command:
|
||||
|
||||
```
|
||||
git clone https://github.com/rust-lang/reference
|
||||
```sh
|
||||
rustup toolchain install nightly
|
||||
```
|
||||
|
||||
Change the directory to the downloaded repository:
|
||||
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 run the tests, you would need to set the Rust version to the nightly
|
||||
release. You can do this by executing the following command:
|
||||
To test all of the code examples in the Reference, run:
|
||||
|
||||
```shell
|
||||
rustup override set nightly
|
||||
```
|
||||
|
||||
This will set the nightly version only for your the current project.
|
||||
|
||||
If you wish to set Rust nightly for all your projects, you can run the
|
||||
command:
|
||||
|
||||
```shell
|
||||
rustup default nightly
|
||||
```
|
||||
|
||||
Now, run the following command to test the code snippets to catch
|
||||
compilation errors:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
mdbook test
|
||||
```
|
||||
|
||||
|
||||
To generate a local instance of the book, run:
|
||||
To build the Reference locally (in `build/`) and open it in a web
|
||||
browser, run:
|
||||
|
||||
```sh
|
||||
mdbook build
|
||||
mdbook build --open
|
||||
```
|
||||
|
||||
The generated HTML will be in the `book` folder.
|
||||
|
|
|
@ -0,0 +1,2 @@
|
|||
[toolchain]
|
||||
channel = "nightly"
|
Loading…
Reference in New Issue