Rollup merge of #114651 - tmfink:rustdoc-rustc-wrapper, r=GuillaumeGomez

rustdoc: add `--test-builder-wrapper` arg to support wrappers such as RUSTC_WRAPPER when building doctests

Currently, `rustdoc` builds test crates with `rustc` directly instead of using [`RUSTC_WRAPPER`](https://doc.rust-lang.org/cargo/reference/config.html#buildrustc-wrapper) (if any is set).

This causes build issues in build systems that use `cargo` but tweak linking flags by setting the `RUSTC_WRAPPER` environment variable.

This change is not meant to be final--it's only a minimal proof of concept.
Please advise on the best way to proceed.

Open questions:
- [x] Does supporting the `rustc` wrappers make sense?
    - yes, `cargo-miri` for example needs a "hack" to workaround the issue
- [X] What environment variable(s) should be read for the rustc wrapper? Should `rustdoc` [use the same names as `cargo`](https://doc.rust-lang.org/cargo/reference/config.html#buildrustc-wrapper)?
    - None, since `rustdoc` takes arguments
- [X] What name should be used for a `rustdoc` CLI option?
    - `--test-builder-wrapper`
- [X] Should a separate workspace wrapper (like `RUSTC_WORKSPACE_WRAPPER`) be supported?
    - `--test-builder-wrapper` can be passed multiple times to get multiple wrappers passed
- [X] How/where should this be documented? It's not obvious to all users that `cargo doc` actually causes `rustdoc` to compile tests with rust
    - Added doc to `src/doc/rustdoc/src/command-line-arguments.md` per `@GuillaumeGomez`

Author: GuillaumeGomez

src/doc/rustdoc/src/command-line-arguments.md

@@ -427,3 +427,32 @@ This flag is **deprecated** and **has no effect**.
 Rustdoc only supports Rust source code and Markdown input formats. If the
 file ends in `.md` or `.markdown`, `rustdoc` treats it as a Markdown file.
 Otherwise, it assumes that the input file is Rust.
+
+## `--test-builder`: `rustc`-like program to build tests
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc --test-builder /path/to/rustc src/lib.rs
+```
+
+Rustdoc will use the provided program to compile tests instead of the default `rustc` program from
+the sysroot.
+
+## `--test-builder-wrapper`: wrap calls to the test builder
+
+Using this flag looks like this:
+
+```bash
+$ rustdoc --test-builder-wrapper /path/to/rustc-wrapper src/lib.rs
+$ rustdoc \
+    --test-builder-wrapper rustc-wrapper1 \
+    --test-builder-wrapper rustc-wrapper2 \
+    --test-builder rustc \
+    src/lib.rs
+```
+
+Similar to cargo `build.rustc-wrapper` option, this flag takes a `rustc` wrapper program.
+The first argument to the program will be the test builder program.
+
+This flag can be passed multiple times to nest wrappers.

src/librustdoc/config.rs

@@ -130,6 +130,9 @@ pub(crate) struct Options {
     /// default to loading from `$sysroot/bin/rustc`.
     pub(crate) test_builder: Option<PathBuf>,
 
+    /// Run these wrapper instead of rustc directly
+    pub(crate) test_builder_wrappers: Vec<PathBuf>,
+
     // Options that affect the documentation process
     /// Whether to run the `calculate-doc-coverage` pass, which counts the number of public items
     /// with and without documentation.
@@ -204,6 +207,7 @@ impl fmt::Debug for Options {
             .field("enable-per-target-ignores", &self.enable_per_target_ignores)
             .field("run_check", &self.run_check)
             .field("no_run", &self.no_run)
+            .field("test_builder_wrappers", &self.test_builder_wrappers)
             .field("nocapture", &self.nocapture)
             .field("scrape_examples_options", &self.scrape_examples_options)
             .field("unstable_features", &self.unstable_features)
@@ -521,6 +525,8 @@ impl Options {
             dcx.fatal("the `--test` flag must be passed to enable `--no-run`");
         }
 
+        let test_builder_wrappers =
+            matches.opt_strs("test-builder-wrapper").iter().map(PathBuf::from).collect();
         let out_dir = matches.opt_str("out-dir").map(|s| PathBuf::from(&s));
         let output = matches.opt_str("output").map(|s| PathBuf::from(&s));
         let output = match (out_dir, output) {
@@ -727,6 +733,7 @@ impl Options {
             test_builder,
             run_check,
             no_run,
+            test_builder_wrappers,
             nocapture,
             crate_name,
             output_format,

src/librustdoc/doctest.rs

@@ -25,7 +25,7 @@ use tempfile::Builder as TempFileBuilder;
 use std::env;
 use std::io::{self, Write};
 use std::panic;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::process::{self, Command, Stdio};
 use std::str;
 use std::sync::atomic::{AtomicUsize, Ordering};
@@ -306,6 +306,18 @@ fn add_exe_suffix(input: String, target: &TargetTriple) -> String {
     input + &exe_suffix
 }
 
+fn wrapped_rustc_command(rustc_wrappers: &[PathBuf], rustc_binary: &Path) -> Command {
+    let mut args = rustc_wrappers.iter().map(PathBuf::as_path).chain([rustc_binary].into_iter());
+
+    let exe = args.next().expect("unable to create rustc command");
+    let mut command = Command::new(exe);
+    for arg in args {
+        command.arg(arg);
+    }
+
+    command
+}
+
 fn run_test(
     test: &str,
     crate_name: &str,
@@ -334,7 +346,7 @@ fn run_test(
         .test_builder
         .as_deref()
         .unwrap_or_else(|| rustc_interface::util::rustc_path().expect("found rustc"));
-    let mut compiler = Command::new(&rustc_binary);
+    let mut compiler = wrapped_rustc_command(&rustdoc_options.test_builder_wrappers, rustc_binary);
     compiler.arg("--crate-type").arg("bin");
     for cfg in &rustdoc_options.cfgs {
         compiler.arg("--cfg").arg(&cfg);

src/librustdoc/lib.rs

@@ -530,6 +530,14 @@ fn opts() -> Vec<RustcOptGroup> {
         unstable("test-builder", |o| {
             o.optopt("", "test-builder", "The rustc-like binary to use as the test builder", "PATH")
         }),
+        unstable("test-builder-wrapper", |o| {
+            o.optmulti(
+                "",
+                "test-builder-wrapper",
+                "Wrapper program to pass test-builder and arguments",
+                "PATH",
+            )
+        }),
         unstable("check", |o| o.optflagmulti("", "check", "Run rustdoc checks")),
         unstable("generate-redirect-map", |o| {
             o.optflagmulti(

tests/run-make/issue-88756-default-output/output-default.stdout

@@ -147,6 +147,8 @@ Options:
 
         --test-builder PATH
                         The rustc-like binary to use as the test builder
+        --test-builder-wrapper PATH
+                        Wrapper program to pass test-builder and arguments
         --check         Run rustdoc checks
         --generate-redirect-map 
                         Generate JSON file at the top level instead of