Document "cargo +toolchain" syntax in cargo book?

[RalfJung]

Describe the problem you are trying to solve

We got some feedback that the cargo +toolchain syntax is hard to find.

Describe the solution you'd like

It might be a good idea to mention this syntax somewhere more prominently in the cargo book.

Notes

I am aware it is a rustup feature, but that is not where people will expect it. OTOH I am not sure how the cargo team feels about having this in their docs.

Cc @ssomers

[ehuss]

Seems like a good idea to at least mention it. Is there any particular location in the documentation that you think would be a good place? A new chapter or an existing one?

Maybe Cargo could detect it is running under rustup, and include it in the help output?

[ssomers]

I looked for it with "cargo --help", in the online documentation listing options, which on closer look copies the man page. I can understand the syntax doesn't belong in that static documentation, but surely the program able to handle the syntax is able to advertise it in its help (regardless of what "running under rustup" actually means)?

[RalfJung]

but surely the program able to handle the syntax is able to advertise it in its help (regardless of what "running under rustup" actually means)?

And it does, but that program is rustup. That's why the help appears in rustup run --help.

Your cargo binary is just a symlink to rustup. rustup then figures out the current toolchain, parsing +toolchain, and then invokes that toolchain's cargo (with +toolchain stripped).

[ssomers]

Good to know. But when disguising as cargo, and getting a --help request, rustup doesn't announce itself and doesn't squeeze in its extra option. Browsing through rustup's issues, the latest issue is clearly also about help, and the only other thing I find is another name for the syntax: toolchain keyword. So who's going to file an issue there? Meanwhile I'm looking into the help code.