docs: add documentation on platform 'triple's, example usages

[kevinushey]

Problem

Primarily related to https://doc.rust-lang.org/cargo/reference/config.html.

I believe it would be helpful if that page included:

• A brief discussion of what a platform 'triple' is, or a link to a document with such a description;
• Some instructions on how one can figure out the 'triple' for their host machine, or other potential targets.

Proposed Solution

Perhaps a small section could be added immediately after https://doc.rust-lang.org/cargo/reference/config.html#configuration-format. Here's a short draft:

Platform Triples

Platform-specific compiler and linker flags can be specified as part of [target.<triple>] configuration entries in config.toml. Here, <triple> refers to a Target Triplet. It has the form <machine>-<vendor>-<os>, and you can use:

rustc -vV

to infer your machine's platform triple, which is printed as part of the host: field.

Notes

I'm making this as an issue first just to confirm whether this feels like a worthwhile change; if so, I can make a PR.

[weihanglo]

Thanks for the report!

Target triple has its own place in the appendix. Cargo also mentions target triple in the manual of each build command, such as cargo build. And in the chapter "Specifying Dependencies" as well.

We may want to refer to the appendix, but I am not sure where to add and what is the right amount of doc to add. Maybe put a reference under [target] key? I am not sure either.

[kevinushey]

Thank you for pointing that out! I like the idea of adding a link to the target triple section in the appendix.

Maybe the simplest answer here is to add a sentence after the example configuration in https://doc.rust-lang.org/cargo/reference/config.html#configuration-format, with something like:

See Target in the glossary for more details on target triples.

[jofas]

@rustbot claim

[jofas]

cargo/src/doc/src/reference/config.md

Lines 1034 to 1039 in fc2242a

	#### `[target]`
	The `[target]` table is used for specifying settings for specific platform
	targets. It consists of a sub-table which is either a platform triple or a
	[`cfg()` expression]. The given values will be used if the target platform
	matches either the `<triple>` value or the `<cfg>` expression.

I'd suggest making <triple> a link to the target section of the glossary. We could do this for every occurrence of <triple> on this page. Do you agree that this would be enough to clarify what target triples are?

[weihanglo]

I think that is sufficient, despite that you cannot link to Target Triple directly 🥲. We could also update other pages mentioning that if possible.

(Except --target in build command manual I guess. They already got enought information).

[jofas]

cargo/src/doc/src/appendix/glossary.md

Lines 181 to 200 in fc2242a

	### Target
	The meaning of the term *target* depends on the context:
	- **Cargo Target** — Cargo [*packages*](#package) consist of *targets* which
	correspond to [*artifacts*](#artifact) that will be produced. Packages can
	have library, binary, example, test, and benchmark targets. The
	[list of targets][targets] are configured in the `Cargo.toml`
	[*manifest*](#manifest), often inferred automatically by the [directory
	layout] of the source files.
	- **Target Directory** — Cargo places all built artifacts and intermediate
	files in the *target* directory. By default this is a directory named
	`target` at the [*workspace*](#workspace) root, or the package root if not
	using a workspace. The directory may be changed with the `--target-dir`
	command-line option, the `CARGO_TARGET_DIR` [environment variable], or the
	`build.target-dir` [config option].
	- **Target Architecture** — The OS and machine architecture for the built
	artifacts are typically referred to as a *target*.
	- **Target Triple** — A triple is a specific format for specifying a target
	architecture. Triples may be referred to as a *target triple* which is the

Couldn't we convert the list in the glossary to <h4> subsections with #### in order to link to them? The depth is supported by mdbooks, as seen in the snippet I posted above:

cargo/src/doc/src/reference/config.md

Line 1034 in fc2242a

#### `[target]`

[weihanglo]

Could try that. Just list item feels more natural to me with the surrounding context.

[jofas]

True. Also the Target section in the glossary is not that long to begin with. I'll start working on a PR where I add links to occurrences of triple or host triple inside the src/doc/src/ directory (except to the --target option of the cargo build command).