From 81b8df432387a6303aa6aba9294afaa430dadd5a Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Mon, 19 Feb 2024 06:25:59 +0000 Subject: [PATCH] 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. --- README.md | 72 +++++++++++++++++++++------------------------ rust-toolchain.toml | 2 ++ 2 files changed, 36 insertions(+), 38 deletions(-) create mode 100644 rust-toolchain.toml diff --git a/README.md b/README.md index 4ba836f..c525617 100644 --- a/README.md +++ b/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. diff --git a/rust-toolchain.toml b/rust-toolchain.toml new file mode 100644 index 0000000..5d56faf --- /dev/null +++ b/rust-toolchain.toml @@ -0,0 +1,2 @@ +[toolchain] +channel = "nightly"