Auto merge of #13197 - weihanglo:target-triple-rustdocflags, r=epage

feat: support `target.<triple>.rustdocflags` officially

Author: bors

src/cargo/core/compiler/build_context/target_info.rs

@@ -698,6 +698,8 @@ impl Flags {
 /// For those artifacts, _only_ `host.*.rustflags` is respected, and no other configuration
 /// sources, _regardless of the value of `target-applies-to-host`_. This is counterintuitive, but
 /// necessary to retain backwards compatibility with older versions of Cargo.
+///
+/// Rules above also applies to rustdoc. Just the key would be `rustdocflags`/`RUSTDOCFLAGS`.
 fn extra_args(
     gctx: &GlobalContext,
     requested_kinds: &[CompileKind],
@@ -800,7 +802,6 @@ fn rustflags_from_target(
                         .as_ref()
                         .map(|rustflags| (key, &rustflags.val)),
                     // `target.cfg(…).rustdocflags` is currently not supported.
-                    // In fact, neither is `target.<triple>.rustdocflags`.
                     Flags::Rustdoc => None,
                 }
             })

src/cargo/util/config/target.rs

@@ -21,12 +21,14 @@ pub struct TargetCfgConfig {
 }
 
 /// Config definition of a `[target]` table or `[host]`.
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Default)]
 pub struct TargetConfig {
     /// Process to run as a wrapper for `cargo run`, `test`, and `bench` commands.
     pub runner: OptValue<PathAndArgs>,
     /// Additional rustc flags to pass.
     pub rustflags: OptValue<StringList>,
+    /// Additional rustdoc flags to pass.
+    pub rustdocflags: OptValue<StringList>,
     /// The path of the linker for this target.
     pub linker: OptValue<ConfigRelativePath>,
     /// Build script override for the given library name.
@@ -95,12 +97,7 @@ pub(super) fn load_host_triple(gctx: &GlobalContext, triple: &str) -> CargoResul
         };
         load_config_table(gctx, &host_prefix)
     } else {
-        Ok(TargetConfig {
-            runner: None,
-            rustflags: None,
-            linker: None,
-            links_overrides: BTreeMap::new(),
-        })
+        Ok(TargetConfig::default())
     }
 }
 
@@ -116,9 +113,10 @@ fn load_config_table(gctx: &GlobalContext, prefix: &str) -> CargoResult<TargetCo
     // because it causes serde to use `deserialize_map` which means the config
     // deserializer does not know which keys to deserialize, which means
     // environment variables would not work.
-    let runner: OptValue<PathAndArgs> = gctx.get(&format!("{}.runner", prefix))?;
-    let rustflags: OptValue<StringList> = gctx.get(&format!("{}.rustflags", prefix))?;
-    let linker: OptValue<ConfigRelativePath> = gctx.get(&format!("{}.linker", prefix))?;
+    let runner: OptValue<PathAndArgs> = gctx.get(&format!("{prefix}.runner"))?;
+    let rustflags: OptValue<StringList> = gctx.get(&format!("{prefix}.rustflags"))?;
+    let rustdocflags: OptValue<StringList> = gctx.get(&format!("{prefix}.rustdocflags"))?;
+    let linker: OptValue<ConfigRelativePath> = gctx.get(&format!("{prefix}.linker"))?;
     // Links do not support environment variables.
     let target_key = ConfigKey::from_str(prefix);
     let links_overrides = match gctx.get_table(&target_key)? {
@@ -128,6 +126,7 @@ fn load_config_table(gctx: &GlobalContext, prefix: &str) -> CargoResult<TargetCo
     Ok(TargetConfig {
         runner,
         rustflags,
+        rustdocflags,
         linker,
         links_overrides,
     })
@@ -144,7 +143,7 @@ fn parse_links_overrides(
         // Skip these keys, it shares the namespace with `TargetConfig`.
         match lib_name.as_str() {
             // `ar` is a historical thing.
-            "ar" | "linker" | "runner" | "rustflags" => continue,
+            "ar" | "linker" | "runner" | "rustflags" | "rustdocflags" => continue,
             _ => {}
         }
         let mut output = BuildOutput::default();

src/doc/src/reference/config.md

@@ -158,9 +158,10 @@ tag = "…"            # tag name for the git repository
 rev = "…"            # revision for the git repository
 
 [target.<triple>]
-linker = "…"            # linker to use
-runner = "…"            # wrapper to run executables
-rustflags = ["…", "…"]  # custom flags for `rustc`
+linker = "…"              # linker to use
+runner = "…"              # wrapper to run executables
+rustflags = ["…", "…"]    # custom flags for `rustc`
+rustdocflags = ["…", "…"] # custom flags for `rustdoc`
 
 [target.<cfg>]
 runner = "…"            # wrapper to run executables
@@ -500,15 +501,22 @@ appropriate profile setting.
 Extra command-line flags to pass to `rustdoc`. The value may be an array of
 strings or a space-separated string.
 
-There are three mutually exclusive sources of extra flags. They are checked in
+There are four mutually exclusive sources of extra flags. They are checked in
 order, with the first one being used:
 
 1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable.
 2. `RUSTDOCFLAGS` environment variable.
-3. `build.rustdocflags` config value.
+3. All matching `target.<triple>.rustdocflags` config entries joined together.
+4. `build.rustdocflags` config value.
 
 Additional flags may also be passed with the [`cargo rustdoc`] command.
 
+> **Caution**: Due to the low-level nature of passing flags directly to the
+> compiler, this may cause a conflict with future versions of Cargo which may
+> issue the same or similar flags on its own which may interfere with the
+> flags you specify. This is an area where Cargo may not always be backwards
+> compatible.
+
 #### `build.incremental`
 * Type: bool
 * Default: from profile
@@ -1216,6 +1224,17 @@ This is similar to the [target rustflags](#targettriplerustflags), but
 using a [`cfg()` expression]. If several `<cfg>` and [`<triple>`] entries
 match the current target, the flags are joined together.
 
+#### `target.<triple>.rustdocflags`
+* Type: string or array of strings
+* Default: none
+* Environment: `CARGO_TARGET_<triple>_RUSTDOCFLAGS`
+
+Passes a set of custom flags to the compiler for this [`<triple>`].
+The value may be an array of strings or a space-separated string.
+
+See [`build.rustdocflags`](#buildrustdocflags) for more details on the different
+ways to specific extra flags.
+
 #### `target.<triple>.<links>`
 
 The links sub-table provides a way to [override a build script]. When

tests/testsuite/rustdocflags.rs

@@ -1,6 +1,8 @@
 //! Tests for setting custom rustdoc flags.
 
 use cargo_test_support::project;
+use cargo_test_support::rustc_host;
+use cargo_test_support::rustc_host_env;
 
 #[cargo_test]
 fn parses_env() {
@@ -159,3 +161,72 @@ fn not_affected_by_target_rustflags() {
         .with_stderr_contains("[RUNNING] `rustdoc [..] --cfg foo[..]`")
         .run();
 }
+
+#[cargo_test]
+fn target_triple_rustdocflags_works() {
+    let host = rustc_host();
+    let host_env = rustc_host_env();
+    let p = project().file("src/lib.rs", "").build();
+
+    // target.triple.rustdocflags in env works
+    p.cargo("doc -v")
+        .env(
+            &format!("CARGO_TARGET_{host_env}_RUSTDOCFLAGS"),
+            "--cfg=foo",
+        )
+        .with_stderr_contains("[RUNNING] `rustdoc[..]--cfg[..]foo[..]`")
+        .run();
+
+    // target.triple.rustdocflags in config works
+    p.cargo("doc -v")
+        .arg("--config")
+        .arg(format!("target.{host}.rustdocflags=['--cfg', 'foo']"))
+        .with_stderr_contains("[RUNNING] `rustdoc[..]--cfg[..]foo[..]`")
+        .run();
+}
+
+#[cargo_test]
+fn target_triple_rustdocflags_works_through_cargo_test() {
+    let host = rustc_host();
+    let host_env = rustc_host_env();
+    let p = project()
+        .file(
+            "src/lib.rs",
+            r#"
+                //! ```
+                //! assert!(cfg!(foo));
+                //! ```
+            "#,
+        )
+        .build();
+
+    // target.triple.rustdocflags in env works
+    p.cargo("test --doc -v")
+        .env(
+            &format!("CARGO_TARGET_{host_env}_RUSTDOCFLAGS"),
+            "--cfg=foo",
+        )
+        .with_stderr_contains("[RUNNING] `rustdoc[..]--test[..]--cfg[..]foo[..]`")
+        .with_stdout_contains(
+            "\
+running 1 test
+test src/lib.rs - (line 2) ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out[..]",
+        )
+        .run();
+
+    // target.triple.rustdocflags in config works
+    p.cargo("test --doc -v")
+        .arg("--config")
+        .arg(format!("target.{host}.rustdocflags=['--cfg', 'foo']"))
+        .with_stderr_contains("[RUNNING] `rustdoc[..]--test[..]--cfg[..]foo[..]`")
+        .with_stdout_contains(
+            "\
+running 1 test
+test src/lib.rs - (line 2) ... ok
+
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out[..]",
+        )
+        .run();
+}