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
|
## Dependencies
|
||||||
|
|
||||||
- rustc (the Rust compiler).
|
- Nightly Rust
|
||||||
- [mdbook](https://rust-lang.github.io/mdBook/) (use `cargo install
|
- [mdbook](https://rust-lang.github.io/mdBook/)
|
||||||
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).
|
|
||||||
|
|
||||||
## 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
|
```sh
|
||||||
page](https://github.com/rust-lang/reference) or run the following
|
rustup toolchain install nightly
|
||||||
command:
|
|
||||||
|
|
||||||
```
|
|
||||||
git clone https://github.com/rust-lang/reference
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
```sh
|
||||||
cd reference
|
cd reference
|
||||||
```
|
```
|
||||||
|
|
||||||
To run the tests, you would need to set the Rust version to the nightly
|
To test all of the code examples in the Reference, run:
|
||||||
release. You can do this by executing the following command:
|
|
||||||
|
|
||||||
```shell
|
```sh
|
||||||
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
|
|
||||||
mdbook test
|
mdbook test
|
||||||
```
|
```
|
||||||
|
|
||||||
|
To build the Reference locally (in `build/`) and open it in a web
|
||||||
To generate a local instance of the book, run:
|
browser, run:
|
||||||
|
|
||||||
```sh
|
```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