Document and feature-gate host-config tables.

Author: jameshilliard

src/cargo/core/features.rs

@@ -600,6 +600,7 @@ unstable_cli_options!(
     namespaced_features: bool = ("Allow features with `dep:` prefix"),
     no_index_update: bool = ("Do not update the registry index even if the cache is outdated"),
     panic_abort_tests: bool = ("Enable support to run tests with -Cpanic=abort"),
+    host_config: bool = ("Enable the [host] section in the .cargo/config.toml file"),
     patch_in_config: bool = ("Allow `[patch]` sections in .cargo/config.toml files"),
     rustdoc_map: bool = ("Allow passing external documentation mappings to rustdoc"),
     separate_nightlies: bool = (HIDDEN),
@@ -787,6 +788,7 @@ impl CliUnstable {
             "panic-abort-tests" => self.panic_abort_tests = parse_empty(k, v)?,
             "jobserver-per-rustc" => self.jobserver_per_rustc = parse_empty(k, v)?,
             "configurable-env" => self.configurable_env = parse_empty(k, v)?,
+            "host-config" => self.host_config = parse_empty(k, v)?,
             "patch-in-config" => self.patch_in_config = parse_empty(k, v)?,
             "features" => {
                 // For now this is still allowed (there are still some

src/cargo/util/config/target.rs

@@ -66,12 +66,21 @@ pub(super) fn load_target_cfgs(config: &Config) -> CargoResult<Vec<(String, Targ
 
 /// Loads a single `[host]` table for the given triple.
 pub(super) fn load_host_triple(config: &Config, triple: &str) -> CargoResult<TargetConfig> {
-    let host_triple_key = ConfigKey::from_str(&format!("host.{}", triple));
-    let host_prefix = match config.get_cv(&host_triple_key)? {
-        Some(_) => format!("host.{}", triple),
-        None => "host".to_string(),
-    };
-    load_config_table(config, &host_prefix)
+    if config.cli_unstable().host_config {
+        let host_triple_key = ConfigKey::from_str(&format!("host.{}", triple));
+        let host_prefix = match config.get_cv(&host_triple_key)? {
+            Some(_) => format!("host.{}", triple),
+            None => "host".to_string(),
+        };
+        load_config_table(config, &host_prefix)
+    } else {
+        Ok(TargetConfig {
+            runner: None,
+            rustflags: None,
+            linker: None,
+            links_overrides: BTreeMap::new(),
+        })
+    }
 }
 
 /// Loads a single `[target]` table for the given triple.

src/doc/src/reference/unstable.md

@@ -641,6 +641,39 @@ cargo +nightly -Zunstable-options -Zconfig-include --config somefile.toml build
 
 CLI paths are relative to the current working directory.
 
+### host-config
+* Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322)
+* Tracking Issue: [#3349](https://github.com/rust-lang/cargo/issues/3349)
+
+The `host` key in a config file can be used pass flags to host build targets
+such as build scripts that must run on the host system instead of the target
+system when cross compiling. It supports both generic and host arch specific
+tables. Matching host arch tables take precedence over generic host tables.
+
+It requires the `-Zhost-config` command-line option.
+
+```toml
+# .cargo/config
+cargo-features = ["host-config"]
+
+[host]
+linker = "/path/to/host/linker"
+[host.x86_64-unknown-linux-gnu]
+linker = "/path/to/host/arch/linker"
+[target.x86_64-unknown-linux-gnu]
+linker = "/path/to/target/linker"
+```
+
+The generic `host` table above will be entirely ignored when building on a
+`x86_64-unknown-linux-gnu` host as the `host.x86_64-unknown-linux-gnu` table
+takes precedence.
+
+This feature requires a `--target` to be specified.
+
+```console
+cargo +nightly -Zunstable-options -Zhost-config --config somefile.toml build --target x86_64-unknown-linux-gnu
+```
+
 ### unit-graph
 * Tracking Issue: [#8002](https://github.com/rust-lang/cargo/issues/8002)
 

tests/testsuite/build_script.rs

@@ -266,17 +266,20 @@ fn custom_build_env_var_rustc_linker_bad_host() {
         .build();
 
     // build.rs should fail due to bad host linker being set
-    p.cargo("build --verbose --target")
-        .arg(&target)
-        .with_status(101)
-        .with_stderr_contains(
-            "\
+    if cargo_test_support::is_nightly() {
+        p.cargo("build -Z host-config --verbose --target")
+            .arg(&target)
+            .masquerade_as_nightly_cargo()
+            .with_status(101)
+            .with_stderr_contains(
+                "\
 [COMPILING] foo v0.0.1 ([CWD])
 [RUNNING] `rustc --crate-name build_script_build build.rs [..]--crate-type bin [..]-C linker=[..]/path/to/host/linker [..]`
 [ERROR] linker `[..]/path/to/host/linker` not found
 "
-        )
-        .run();
+            )
+            .run();
+    }
 }
 
 #[cargo_test]
@@ -311,17 +314,20 @@ fn custom_build_env_var_rustc_linker_bad_host_with_arch() {
         .build();
 
     // build.rs should fail due to bad host linker being set
-    p.cargo("build --verbose --target")
-        .arg(&target)
-        .with_status(101)
-        .with_stderr_contains(
-            "\
+    if cargo_test_support::is_nightly() {
+        p.cargo("build -Z host-config --verbose --target")
+            .arg(&target)
+            .masquerade_as_nightly_cargo()
+            .with_status(101)
+            .with_stderr_contains(
+                "\
 [COMPILING] foo v0.0.1 ([CWD])
 [RUNNING] `rustc --crate-name build_script_build build.rs [..]--crate-type bin [..]-C linker=[..]/path/to/host/arch/linker [..]`
 [ERROR] linker `[..]/path/to/host/arch/linker` not found
 "
-        )
-        .run();
+            )
+            .run();
+    }
 }
 
 #[cargo_test]
@@ -355,7 +361,12 @@ fn custom_build_env_var_rustc_linker_cross_arch_host() {
         .build();
 
     // build.rs should fail due to bad host linker being set
-    p.cargo("build --verbose --target").arg(&target).run();
+    if cargo_test_support::is_nightly() {
+        p.cargo("build -Z host-config --verbose --target")
+            .arg(&target)
+            .masquerade_as_nightly_cargo()
+            .run();
+    }
 }
 
 #[cargo_test]
@@ -391,17 +402,20 @@ fn custom_build_env_var_rustc_linker_bad_cross_arch_host() {
         .build();
 
     // build.rs should fail due to bad host linker being set
-    p.cargo("build --verbose --target")
-        .arg(&target)
-        .with_status(101)
-        .with_stderr_contains(
-            "\
+    if cargo_test_support::is_nightly() {
+        p.cargo("build -Z host-config --verbose --target")
+            .arg(&target)
+            .masquerade_as_nightly_cargo()
+            .with_status(101)
+            .with_stderr_contains(
+                "\
 [COMPILING] foo v0.0.1 ([CWD])
 [RUNNING] `rustc --crate-name build_script_build build.rs [..]--crate-type bin [..]-C linker=[..]/path/to/host/linker [..]`
 [ERROR] linker `[..]/path/to/host/linker` not found
 "
-        )
-        .run();
+            )
+            .run();
+    }
 }
 
 #[cargo_test]