Implement host-target substitution (#15838)

### 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:

```toml
# .cargo/config.toml

[build]
target = "host"
```

Author: weihanglo

src/cargo/core/compiler/compile_kind.rs

@@ -84,15 +84,27 @@ impl CompileKind {
         fallback: CompileKindFallback,
     ) -> CargoResult<Vec<CompileKind>> {
         let dedup = |targets: &[String]| {
-            Ok(targets
+            let deduplicated_targets = targets
                 .iter()
-                .map(|value| Ok(CompileKind::Target(CompileTarget::new(value)?)))
+                .map(|value| {
+                    // This neatly substitutes the manually-specified `host` target directive
+                    // with the compiling machine's target triple.
+
+                    if value.as_str() == "host" {
+                        let host_triple = env!("RUST_HOST_TARGET");
+                        Ok(CompileKind::Target(CompileTarget::new(host_triple)?))
+                    } else {
+                        Ok(CompileKind::Target(CompileTarget::new(value.as_str())?))
+                    }
+                })
                 // First collect into a set to deduplicate any `--target` passed
                 // more than once...
                 .collect::<CargoResult<BTreeSet<_>>>()?
                 // ... then generate a flat list for everything else to use.
                 .into_iter()
-                .collect())
+                .collect();
+
+            Ok(deduplicated_targets)
         };
 
         if !targets.is_empty() {

src/cargo/util/command_prelude.rs

@@ -1257,6 +1257,11 @@ fn get_target_triples() -> Vec<clap_complete::CompletionCandidate> {
         }
     }
 
+    // Allow tab-completion for `host` as the desired target.
+    candidates.push(clap_complete::CompletionCandidate::new("host").help(Some(
+        concat!("alias for: ", env!("RUST_HOST_TARGET")).into(),
+    )));
+
     candidates
 }
 

src/doc/man/generated_txt/cargo-bench.txt

@@ -220,11 +220,24 @@ OPTIONS
 
    Compilation Options
        --target triple
-           Benchmark for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Benchmark for the specified target architecture. Flag may be
+           specified multiple times. The default is the host architecture. The
+           general format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-build.txt

@@ -137,11 +137,24 @@ OPTIONS
 
    Compilation Options
        --target triple
-           Build for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Build for the specified target architecture. Flag may be specified
+           multiple times. The default is the host architecture. The general
+           format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-check.txt

@@ -134,11 +134,24 @@ OPTIONS
 
    Compilation Options
        --target triple
-           Check for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Check for the specified target architecture. Flag may be specified
+           multiple times. The default is the host architecture. The general
+           format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-clean.txt

@@ -45,11 +45,24 @@ OPTIONS
            target in the root of the workspace.
 
        --target triple
-           Clean for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Clean for the specified target architecture. Flag may be specified
+           multiple times. The default is the host architecture. The general
+           format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-doc.txt

@@ -116,11 +116,24 @@ OPTIONS
 
    Compilation Options
        --target triple
-           Document for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Document for the specified target architecture. Flag may be
+           specified multiple times. The default is the host architecture. The
+           general format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-fetch.txt

@@ -25,11 +25,24 @@ DESCRIPTION
 OPTIONS
    Fetch options
        --target triple
-           Fetch for the given architecture. The default is all architectures.
-           The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Fetch for the specified target architecture. Flag may be specified
+           multiple times. The default is all architectures. The general format
+           of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-fix.txt

@@ -208,11 +208,24 @@ OPTIONS
 
    Compilation Options
        --target triple
-           Fix for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets. This flag may be specified multiple
-           times.
+           Fix for the specified target architecture. Flag may be specified
+           multiple times. The default is the host architecture. The general
+           format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.

src/doc/man/generated_txt/cargo-install.txt

@@ -186,10 +186,24 @@ OPTIONS
 
    Compilation Options
        --target triple
-           Install for the given architecture. The default is the host
-           architecture. The general format of the triple is
-           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
-           a list of supported targets.
+           Install for the specified target architecture. The default is the
+           host architecture. The general format of the triple is
+           <arch><sub>-<vendor>-<sys>-<abi>.
+
+           Possible values:
+
+           o  Any supported target in rustc --print target-list.
+
+           o  "host", which will internally be substituted by the host’s
+              target. This can be particularly useful if you’re
+              cross-compiling some crates, and don’t want to specify your
+              host’s machine as a target (for instance, an xtask in a shared
+              project that may be worked on by many hosts).
+
+           o  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.
 
            This may also be specified with the build.target config value
            <https://doc.rust-lang.org/cargo/reference/config.html>.