Implement host-target substitution

[zdivelbiss]

What does this PR try to resolve?

This PR resolves: #13051

Namely, it allows users to invoke cargo subcommands that accept a --target directive to specify the host target, which is later substituted in the command processing layer by the host's real target triple (for instance, on most Linux distributions, cargo build --target host would effectively run cargo build --target x86_64-unknown-linux-gnu).

This additionally applies to usage within config.toml, like so:

# .cargo/config.toml

[build]
target = "host"

[rustbot]

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[zdivelbiss]

In writing up this PR's explanation, I was unsure how to properly outline the following:

### How to test and review this PR?

... due to my unfamiliarity with how testing the program that tests programs would exactly work. Perhaps, simply clone the PR and try to run --target host?

Thanks.

[zdivelbiss]

I have additionally tested locally that the following host specifications do not compile:

• [target.<triple>] in .cargo/config.toml
• [target.<triple>.dependencies] in Cargo.toml

Should I somehow mirror this within the PR, rather than just ensuring locally that builds with the above conditions do not compile? I think I could write an always-fail test that does this, but I wanted to make sure that's the way we want it done.

[weihanglo]

Sorry I added more writing style suggestions then.

Also, feel free to rebase and organize your git history to make it more clearer to read and trace.

[weihanglo]

Thanks. I believe this is the last review round!

BTW, would you mind cleanup your commit history. There are some intermediate commits that may be good if we squash them for easy git diff tracing in the future.

[weihanglo]

We usually use relative paths to link to docs under the same toolchain versions.

Suggested change

	- A path to a custom target specification. See [Custom Target Lookup Path](https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path) for more information.
	- A path to a custom target specification. See [Custom Target Lookup Path](../../rustc/targets/custom.html#custom-target-lookup-path) for more information.

(Doesn't matter for man pages as they don't support relative paths beyond cargo book)

[zdivelbiss]

I wondered about that! Thank you.

[weihanglo]

I just realized manpage also support it. Nice. However, we forgot to update config.md (which is this file).

[zdivelbiss]

@weihanglo Yes, I plan to clean up the history some time today. It's been a while since I've done a rebase & squash, so I'll need to do some research to make sure I don't permanently damage something with Git.

[weihanglo]

It's been a while since I've done a rebase & squash, so I'll need to do some research to make sure I don't permanently damage something with Git.

See some resources Rust Compiler Development Guide: https://rustc-dev-guide.rust-lang.org/git.html#rebasing-and-conflicts. And I just explained why/how we maintain good Git history in Cargo in another PR 😆

[weihanglo]

I can also do the rebase for you, if you don't mind no longer being the committer of those commits. You will still be the author of those and GitHub gives contribution credits to authors AFAIK.

[zdivelbiss]

That's alright, I can do it. It's valuable knowledge, this git-fu. Thank you for the resources. I'm working on it now.

[zdivelbiss]

This commit history looks good to me. Any concerns?

[weihanglo]

I just realized manpage also support it. Nice. However, we forgot to update config.md (which is this file).

[zdivelbiss]

Thank you for catching the URL usage in the config.md changes. I didn't quite understand what the URI you suggested was relative to, but I see now that's is relative to docs.rust-lang.org.

It may be worth considering expanding the contribution guide to include more information on how documentation is written and contributed. There were many elements in this PR that were directly related to things that aren't covered in the contribution guide: syntax (e.g. that a special documentation preprocessor is used), relative pathing (confusion above), the need to run cargo build-man, general styling (may not be possible to document? thinking of my extensive paren usage, which is out-of-place in the docs). It may help cut down on documentation-based nits, though I'm obviously not sure how often this actually affects contributors' efficiency.

[weihanglo]

Thanks for working with us for this feature!

I noticed and understood the frictions when contributing to doc. To me, writing docs is never an easy task. Natural langauges, unlike programming languages, is too ambiguous and people tend to be opinioned on writing. Even among maintainers we often disagree each other's writing. You're right that there should be a clearer writing guideline. We do have one but is not really useful.

Based on your comment #15838 (comment), I've created a doc PR #15854 to improve this situation a bit. Hope it will help others. And again sorry for the frustration 😞.

[zdivelbiss]

@weihanglo No frustration at all; just thinking of how to make the process smoother for contributors in the future. Thanks for your help in getting this PR merged so quickly—it was great to receive such quick feedback.