From 1a23297a23d494901dd033908e873c534b4312aa Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Mon, 19 Feb 2024 05:56:24 +0000 Subject: [PATCH 1/2] Cleanup wrapping, whitespace, etc. in `README.md` In `README.md`, some lines were hard wrapped where others were not, there was some trailing whitespace, and some list items were terminated with a period where some were not. Let's clean these things up by hard wrapping all lines, cleaning up the whitespace, and terminating all list items with periods. --- README.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 65030a3..4ba836f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # The Rust Language Reference -This document is the primary reference for the Rust programming language. +This document is the primary reference for the Rust programming +language. This document is not normative. It may include details that are specific to `rustc` itself, and should not be taken as a specification for the @@ -10,15 +11,18 @@ 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) +- [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). ## Build steps -To build the project, follow the steps given below : +To build the project, follow the steps given below: -Clone the project by downloading the ZIP from the [GitHub page](https://github.com/rust-lang/reference) or -run the following command: +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 @@ -30,7 +34,8 @@ Change the directory to the downloaded repository: 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 run the tests, you would need to set the Rust version to the nightly +release. You can do this by executing the following command: ```shell rustup override set nightly @@ -38,13 +43,15 @@ 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: +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: +Now, run the following command to test the code snippets to catch +compilation errors: ```shell mdbook test From 81b8df432387a6303aa6aba9294afaa430dadd5a Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Mon, 19 Feb 2024 06:25:59 +0000 Subject: [PATCH 2/2] 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"