docs(user-guide/cross-compilation): revamp descriptions

[rami3l]

It looks like many newcomers to Rust are still having difficulties understanding the distinction between the host platform and the compilation targets. Examples:

• You SHOULDN'T install a x86_64-unknown-linux-musl toolchain on a glibc host (like Ubuntu): Error running musl rustup on Ubuntu #3254
• You DON'T NEED TO install a x86_64-pc-windows-gnullvm toolchain on a x64 Windows host to build for that target: [MSYS2] Allow default host triple to be overridden by an environment variable #5024

This patch aims to further clarify that point.

cc @pgalbraith for review.

[Copilot]

Pull request overview

Documentation update clarifying host platforms, compilation targets, and target management.

Changes:

• Renames and restructures the cross-compilation chapter.
• Adds host/target explanations and examples.
• Documents target installation and management commands.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Summary
doc/user-guide/src/SUMMARY.md	Updates the chapter navigation label. No comments.
doc/user-guide/src/cross-compilation.md	Adds host/target guidance and examples. Moderate findings: clarify the host target installation instruction (4 votes) and spell out valid Windows toolchain alternatives (3 votes). Nits: add that and a comma after platforms (4 and 3 votes).

Suppressed comments (3)

doc/user-guide/src/cross-compilation.md:32

• host tuple of your choice suggests that any host triple can be selected, but the host is the platform on which the compiler runs and must be compatible with the current environment; for example, a glibc Linux host cannot run the musl host toolchain. Please qualify this as a host tuple compatible with the development environment so this note does not encourage the installation mistake this section is meant to prevent.

> tuple of your choice and compile to other targets as needed. For example, you
> don't need a `i686-pc-windows-msvc` host toolchain on your `x86_64` Windows

doc/user-guide/src/cross-compilation.md:71

• rustup target add and rustup target remove both require one or more target tuples, so the forms shown here fail with a missing <TARGET> argument. Include the operand in these examples, as in the --toolchain example below.

- To see a list of available targets: `rustup target list`.
- To see a list of installed targets: `rustup target list --installed`.
- To remove a previously-installed target: `rustup target remove`.

doc/user-guide/src/cross-compilation.md:34

• i686-msvc is not a complete Rust target tuple and is not the target name used elsewhere in this paragraph. Readers may try to use this shorthand as a Cargo target and get an invalid-target error; use i686-pc-windows-msvc here as well.

> stick to your existing `stable-x86_64-pc-windows-{msvc,gnu}` toolchain with

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

View changes since this review

[FranciscoTGouveia]

Thanks, this looks great!

While looking through this, I decided to test whether the completions would work for adding a new target -- which I think is very useful -- but unfortunately it was not possible.

Could it have something to do with my setup, or do we currently not support completions for target names?

View changes since this review

[rami3l]

Thanks, this looks great!

While looking through this, I decided to test whether the completions would work for adding a new target -- which I think is very useful -- but unfortunately it was not possible.

Could it have something to do with my setup, or do we currently not support completions for target names?

@FranciscoTGouveia No I don't think dynamic completions are supported, like at all. It's a relatively new clap feature and no one had the time to integrate it, probably until now. It would be nice to make an issue and, start working on it a bit if you have the time, or you can leave the implementation to me if you have other priorities :)