From 21f72289eeddcdfea3378769648807ca819141b9 Mon Sep 17 00:00:00 2001 From: Philipp Oppermann Date: Sun, 21 Feb 2021 14:31:31 +0100 Subject: [PATCH] Update override docs for rust-toolchain.toml files --- doc/src/overrides.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/doc/src/overrides.md b/doc/src/overrides.md index e0e869937fc..e630a109fb1 100644 --- a/doc/src/overrides.md +++ b/doc/src/overrides.md @@ -8,14 +8,14 @@ and override which toolchain is used: +beta`. 2. The `RUSTUP_TOOLCHAIN` environment variable. 3. A [directory override], set with the `rustup override` command. -4. The [`rust-toolchain`] file. +4. The [`rust-toolchain.toml`] file. 5. The [default toolchain]. The toolchain is chosen in the order listed above, using the first one that is specified. There is one exception though: directory overrides and the -`rust-toolchain` file are also preferred by their proximity to the current +`rust-toolchain.toml` file are also preferred by their proximity to the current directory. That is, these two override methods are discovered by walking up -the directory tree toward the filesystem root, and a `rust-toolchain` file +the directory tree toward the filesystem root, and a `rust-toolchain.toml` file that is closer to the current directory will be preferred over a directory override that is further away. @@ -24,7 +24,7 @@ To verify which toolchain is active use `rustup show`. [toolchain]: concepts/toolchains.md [toolchain override shorthand]: #toolchain-override-shorthand [directory override]: #directory-overrides -[`rust-toolchain`]: #the-toolchain-file +[`rust-toolchain.toml`]: #the-toolchain-file [default toolchain]: #default-toolchain ## Toolchain override shorthand @@ -74,8 +74,11 @@ case for nightly-only software that pins to a revision from the release archives. In these cases the toolchain can be named in the project's directory in a file -called `rust-toolchain`, the content of which is either the name of a single -`rustup` toolchain, or a TOML file with the following layout: +called `rust-toolchain.toml` or `rust-toolchain`. If both files are present in +a directory, the latter is used for backwards compatibility. The files use the +[TOML] format and have the following layout: + +[TOML]: https://toml.io/ ``` toml [toolchain] @@ -85,14 +88,19 @@ targets = [ "wasm32-unknown-unknown", "thumbv2-none-eabi" ] profile = "minimal" ``` -If the TOML format is used, the `[toolchain]` section is mandatory, and at -least one property must be specified. +The `[toolchain]` section is mandatory, and at least one property must be +specified. + +For backwards compatibility, `rust-toolchain` files also support a legacy +format that only contains a toolchain name without any TOML encoding, e.g. +just `nightly-2021-01-21`. This format is not available in +`rust-toolchain.toml` files. -The `rust-toolchain` file is suitable to check in to source control. This file -has to be encoded in US-ASCII (if you are on Windows, check the encoding and -that it does not starts with a BOM). +The `rust-toolchain.toml`/`rust-toolchain` files are suitable to check in to +source control. The files have to be encoded in US-ASCII (if you are on +Windows, check the encoding and that it does not starts with a BOM). -The toolchains named in this file have a more restricted form than `rustup` +The toolchains named in these files have a more restricted form than `rustup` toolchains generally, and may only contain the names of the three release channels, 'stable', 'beta', 'nightly', Rust version numbers, like '1.0.0', and optionally an archive date, like 'nightly-2017-01-01'. They may not name