From 6f35ccb9c9f631efbf425ba167ffd63a36298b45 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Tue, 26 Dec 2017 20:50:56 -0800 Subject: [PATCH] Document nightly compatibility issues. Closes #519. --- README.md | 6 +++++- site/guide/getting-started.md | 34 ++++++++++++++++++++++------------ 2 files changed, 27 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index dd91e4fc..6b5622d5 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,11 @@ guide. Rocket requires a nightly version of Rust as it makes heavy use of syntax extensions. This means that the first two unwieldly lines in the introductory -example above are required. +example above are required. Due to an issue in a Rocket dependency (see +[#513]), you must currently build Rocket with a nightly between +`nightly-2017-12-18` and `nightly-2017-12-21`. + +[#513]: https://github.com/SergioBenitez/Rocket/issues/513 ### Core, Codegen, and Contrib diff --git a/site/guide/getting-started.md b/site/guide/getting-started.md index 35d90013..13821445 100644 --- a/site/guide/getting-started.md +++ b/site/guide/getting-started.md @@ -7,17 +7,16 @@ and then run the application. ## Installing Rust Rocket makes abundant use of Rust's syntax extensions and other advanced, -unstable features. Because of this, we'll need to use a nightly version of Rust. -If you already have a working installation of the latest Rust nightly, feel free -to skip to the next section. +unstable features. Because of this, we'll need to use a supported _nightly_ +version of Rust. -To install a nightly version of Rust, we recommend using `rustup`. Install -`rustup` by following the instructions on [its website](https://rustup.rs/). -Once `rustup` is installed, configure Rust nightly as your default toolchain by -running the command: +To install such a version, we recommend using `rustup`. Install `rustup` by +following the instructions on [its website](https://rustup.rs/). Once `rustup` +is installed, configure Rust nightly as your default toolchain by running the +command: ```sh -rustup default nightly +rustup default nightly-2017-12-21 ``` If you prefer, once we setup a project directory in the following section, you @@ -25,19 +24,30 @@ can use per-directory overrides to use the nightly version _only_ for your Rocket project by running the following command in the directory: ```sh -rustup override set nightly +rustup override set nightly-2017-12-21 ``` ### Minimum Nightly -Rocket always requires the _latest_ version of Rust nightly. If your Rocket -application suddently stops building, ensure you're using the latest version of -Rust nightly and Rocket by updating your toolchain and dependencies with: +Rocket generally requires the _latest_ version of Rust nightly. At present, +however, a Rocket dependency fails to build on the latest nightlies, temporarily +grounding Rocket (see [#513] for details). As a result, you'll need to use the +last known working nightly release while the issue is resolved. The commands +above already take this into account by installing the `2017-12-21` nightly. + +Once the external issue has been resolved, you can upgrade to the latest nightly +with `rustup default nightly` or `rustup override set nightly`. If your Rocket +application suddenly stops building, it's likely that this issue has been +resolved. If Rocket fails to compile in the future, you should also ensure +you're using the latest version of Rust nightly and Rocket by updating your +toolchain and dependencies with: ```sh rustup update && cargo update ``` +[#513]: https://github.com/SergioBenitez/Rocket/issues/513 + ## Hello, world! Let's write our first Rocket application! Start by creating a new binary-based