Command to create rust-toolchain.toml in the current directory

[ian-h-chamberlain]

Apologies if this has already been requested, but I couldn't seem to find any issues describing something like it, nor any feature already built-in to rustup to do this. If there is, please feel free to close this issue.

Describe the problem you are trying to solve

Frequently, when I create a new binary project, I want to pin a specific toolchain immediately after initializing the project, e.g.

cargo new --bin some-project
cat >some-project/rust-toolchain.toml <<EOF
[toolchain]
channel = "stable"
EOF

However, I frequently forget the precise format of the toolchain file, and I have to search in rustup documentation to find an example and copy-paste that into my project. It would be nice if there was a simple way to generate a file with reasonable defaults that I could then customize, similar to the generated Cargo.toml created by cargo new or cargo init.

Describe the solution you'd like

Add one more more new rustup commands to create a rust-toolchain.toml in the current directory. I think this could work similarly to rustup override set (take a toolchain argument), or just use the default / currently-set toolchain. The generated file could also include comments that briefly describe some of the fields and link to the documentation.

Notes

Example of one possible workflow:

cargo new --bin some-project
cd some-project
rustup init nightly . # or whatever the syntax of the command looks like

After which the contents of some-project/rust-toolchain.toml would look like this:

# See more keys and their definitions at https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file
[toolchain]
channel = "nightly"
components = []
targets = []
profile = "default"

Some possible command names:

• rustup new (for parity with cargo new)
• rustup init (possibly confusing with rustup-init)
• rustup generate-toolchain-file or similar (very wordy)
• rustup pin
• A subcommand or flag to pass to rustup override set ?

[0xPoe]

@rustbot claim

[tombh]

I got here from googling "rustup create rust-toolchain file". Surprised there isn't a command for this. Ever since I lost some time with an outdated rustc version I've religiously copy and pasted the rust-toolchain file. So agreed, I'd personally expect cargo init to do it. But equally wouldn't be surprised if the responsibility fell on rustup override set or similar.

[SuperKenVery]

I would personally prefer that cargo locks the rust toolchain. Even if that's not OK, a rustup lock or something similar would be great. The current approach is quite some drawback on reproducibility, I think.

[flipchan]

any update on this? Shouldn't be super hard to do

[bn-c]

+1

[rami3l]

Based on the Zulip thread https://rust-lang.zulipchat.com/#narrow/channel/490103-t-rustup/topic/rust-toolchain.2Etoml.20init.20command/with/619666950, for this feature I propose the following implementation:

1. A new subcommand: rustup pin, which pins the active toolchain as a rust-toolchain.toml that is put in the CWD.
2. Take the active toolchain in either qualified or unqualified form (the latter by default, the former with an extra flag), and write it to rust-toolchain.toml along with the target/component list detected for that toolchain. The idea is that the user can call it like rustup +nightly pin for example.
3. If the file exists, rustup bails out with an error.

If @rust-lang/rustup is okay with that I'd love to claim this.

---

For further extension, the hope is to use the first parameter as the output file, which defaults to rust-toolchain.toml.

That being considered, this actually plays very well with my previous proposal #5025, in that if you want a specific file for CI scenarios, you will be able to do:

> rustup +nightly pin rust-toolchain-ci.toml

To pin to a different TOML file, and when you want to use it, you will just need to run:

> cargo +file=rust-toolchain-ci.toml --version

[integeresting]

As discussed in Zulip, I'd love to see this coming to rustup and I think this proposal plays nicely into the override hierarchy. Thanks to @rami3l for helping out here.

[djc]

rustup pin sounds good to me.