Stabilize doctest-xcompile (#15462)

This stabilizes the doctest-xcompile feature by unconditionally enabling
it.

Closes #7040
Closes #12118

## What is being stabilized?

This changes it so that cargo will run doctests when using the
`--target` flag for a target that is not the host. Previously, cargo
would ignore doctests (and show a note if passing `--verbose`).

A wrapper for running the doctest can be specified with the
[`target.*.runner`](https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner)
configuration option (which is powered by the `--test-runtool` rustdoc
flag). This would typically be something like qemu to run under
emulation. It is my understanding that this should work just like
running other kinds of tests.

Additionally, the
[`target.*.linker`](https://doc.rust-lang.org/cargo/reference/config.html#targettriplelinker)
config option is honored for using a custom linker.

Already stabilized in rustdoc is the ability to [ignore tests
per-target](https://doc.rust-lang.org/nightly/rustdoc/write-documentation/documentation-tests.html#ignoring-targets).

## Motivation

The lack of doctest cross-compile support has always been simply due to
the lack of functionality in rustdoc to support this. Rustdoc gained the
ability to cross-compile doctests some time ago, but there were
additional flags like the test runner that were not stabilized until
just recently.

This is intended to ensure that projects have full test coverage even
when doing cross-compilation. It can be
[surprising](#12118) to some
that this was not happening, particularly since cargo is silent about
it.

## Risks

The cargo team had several conversations about how to roll out this
feature. Ultimately we decided to enable it unconditionally with the
understanding that most projects will probably want to have their
doctests covered, and that any breakage will be a local concern that can
be resolved by either fixing the test or ignoring the target.

Tests in rust-lang/rust run into this issue, [particularly on
android](rust-lang/rust#119147 (comment)),
and those will need to be fixed before this reaches beta. This is
something I am looking into.

Some cross-compiling scenarios may need codegen flags that are not
supported. It's not clear how common this will be, or if ignoring will
be a solution, or how difficult it would be to update rustdoc and cargo
to support these. Additionally, the split between RUSTFLAGS and
RUSTDOCFLAGS can be cumbersome.

## Implementation history

- rust-lang/rust#60387 -- Support added to
rustdoc to support the `--target` flag and runtool and
per-target-ignores.
- #6892 -- Initial support in
cargo.
- #7391 -- Added unstable
documentation.
- #8094 -- Fix target for doc
test cross compilation
- #8358 -- Fixed regression with
`--target=HOST` not working on stable.
- #10132 -- Added note about
doctests not running (under `--verbose`).
- rust-lang/rust#112751 -- Fixed
`--test-run-directory` interaction with `--test-runtool`.
- rust-lang/rust#137096 -- Stabilization (and
rename) of the rustdoc `--test-runtool` and `--test-runtool-arg` CLI
args, and drops `--enable-per-target-ignores` unconditionally enabling
it.

## Test coverage

Cargo tests:
-
[artifact_dep::cross_doctests_works_with_artifacts](https://github.com/ehuss/cargo/blob/56c08f84e28d3653ae0c842f331a226738108188/tests/testsuite/artifact_dep.rs#L1248-L1326)
-- Checks that doctest has access to the artifact dependencies.
-
[build_script::duplicate_script_with_extra_env](https://github.com/ehuss/cargo/blob/56c08f84e28d3653ae0c842f331a226738108188/tests/testsuite/build_script.rs#L5514-L5614)
-- Checks that build-script env and cfg values are correctly handled on
host versus target when cross running doctests.
-
[cross_compile::cross_tests](https://github.com/ehuss/cargo/blob/56c08f84e28d3653ae0c842f331a226738108188/tests/testsuite/cross_compile.rs#L416-L502)
-- Basic test that cross-compiled tests work.
-
[cross_compile::doctest_xcompile_linker](https://github.com/ehuss/cargo/blob/56c08f84e28d3653ae0c842f331a226738108188/tests/testsuite/cross_compile.rs#L1139-L1182)
-- Checks that the linker config argument works.
-
[custom_target::custom_target_minimal](https://github.com/ehuss/cargo/blob/56c08f84e28d3653ae0c842f331a226738108188/tests/testsuite/custom_target.rs#L39-L71)
-- Checks that `.json` targets work with rustdoc cross tests.
-
[test::cargo_test_doctest_xcompile_ignores](https://github.com/ehuss/cargo/blob/56c08f84e28d3653ae0c842f331a226738108188/tests/testsuite/test.rs#L4743-L4777)
-- Checks the `ignore-*` syntax works.
-
[test::cargo_test_doctest_xcompile_runner](https://github.com/ehuss/cargo/blob/2603268cda3e32565ac27ee642f2b755fa590bac/tests/testsuite/test.rs#L4783-L4863)
-- Checks runner with cross doctests.
-
[test::cargo_test_doctest_xcompile_no_runner](https://github.com/ehuss/cargo/blob/2603268cda3e32565ac27ee642f2b755fa590bac/tests/testsuite/test.rs#L4869-L4907)
-- Checks cross doctests without a runner.

Rustdoc tests:
-
[run-make/doctest-runtool](https://github.com/rust-lang/rust/tree/25cdf1f67463c9365d8d83778c933ec7480e940b/tests/run-make/doctests-runtool)
-- Tests behavior of `--test-run-directory` with relative paths of the
runner.
-
[rustdoc/doctest/doctest-runtool](https://github.com/rust-lang/rust/blob/25cdf1f67463c9365d8d83778c933ec7480e940b/tests/rustdoc/doctest/doctest-runtool.rs)
-- Tests for `--test-runtool` and `--test-runtool-arg`.

## Future concerns

There have been some discussions
(rust-lang/testing-devex-team#5) about
changing how doctests are driven. My understanding is that stabilizing
this should not affect those plans, since if cargo becomes the driver,
it will simply need to build things with `--target` and use the
appropriate runner.

## Change notes

This PR changed tests a little:
- artifact_dep::no_cross_doctests_works_with_artifacts was changed now
that doctests actually work.
- cross_compile::cross_tests was changed to properly check doctests.
- cross_compile::no_cross_doctests dropped since it is no longer
relevant.
- standard_lib::doctest didn't need `-Zdoctest-xcompile` since
`-Zbuild-std` no longer uses a target.
- test::cargo_test_doctest_xcompile was removed since it is a duplicate
of cross_compile::cross_tests

I think this should probably wait until the next release cutoff, moving
this to 1.89 (will update the PR accordingly if that happens).

Author: ehuss

src/cargo/core/features.rs

@@ -769,7 +769,6 @@ unstable_cli_options!(
     codegen_backend: bool = ("Enable the `codegen-backend` option in profiles in .cargo/config.toml file"),
     config_include: bool = ("Enable the `include` key in config files"),
     direct_minimal_versions: bool = ("Resolve minimal dependency versions instead of maximum (direct dependencies only)"),
-    doctest_xcompile: bool = ("Compile and run doctests for non-host target using runner config"),
     dual_proc_macros: bool = ("Build proc-macros for both the host and the target"),
     feature_unification: bool = ("Enable new feature unification modes in workspaces"),
     features: Option<Vec<String>>,
@@ -879,6 +878,8 @@ const STABILIZED_LINTS: &str = "The `[lints]` table is now always available.";
 const STABILIZED_CHECK_CFG: &str =
     "Compile-time checking of conditional (a.k.a. `-Zcheck-cfg`) is now always enabled.";
 
+const STABILIZED_DOCTEST_XCOMPILE: &str = "Doctest cross-compiling is now always enabled.";
+
 fn deserialize_comma_separated_list<'de, D>(
     deserializer: D,
 ) -> Result<Option<Vec<String>>, D::Error>
@@ -1275,7 +1276,7 @@ impl CliUnstable {
             "codegen-backend" => self.codegen_backend = parse_empty(k, v)?,
             "config-include" => self.config_include = parse_empty(k, v)?,
             "direct-minimal-versions" => self.direct_minimal_versions = parse_empty(k, v)?,
-            "doctest-xcompile" => self.doctest_xcompile = parse_empty(k, v)?,
+            "doctest-xcompile" => stabilized_warn(k, "1.89", STABILIZED_DOCTEST_XCOMPILE),
             "dual-proc-macros" => self.dual_proc_macros = parse_empty(k, v)?,
             "feature-unification" => self.feature_unification = parse_empty(k, v)?,
             "gc" => self.gc = parse_empty(k, v)?,

src/cargo/ops/cargo_test.rs

@@ -176,7 +176,6 @@ fn run_doc_tests(
 ) -> Result<Vec<UnitTestError>, CliError> {
     let gctx = ws.gctx();
     let mut errors = Vec::new();
-    let doctest_xcompile = gctx.cli_unstable().doctest_xcompile;
     let color = gctx.shell().color_choice();
 
     for doctest_info in &compilation.to_doc_test {
@@ -189,28 +188,6 @@ fn run_doc_tests(
             env,
         } = doctest_info;
 
-        if !doctest_xcompile {
-            match unit.kind {
-                CompileKind::Host => {}
-                CompileKind::Target(target) => {
-                    if target.short_name() != compilation.host {
-                        // Skip doctests, -Zdoctest-xcompile not enabled.
-                        gctx.shell().verbose(|shell| {
-                            shell.note(format!(
-                                "skipping doctests for {} ({}), \
-                                 cross-compilation doctests are not yet supported\n\
-                                 See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#doctest-xcompile \
-                                 for more information.",
-                                unit.pkg,
-                                unit.target.description_named()
-                            ))
-                        })?;
-                        continue;
-                    }
-                }
-            }
-        }
-
         gctx.shell().status("Doc-tests", unit.target.name())?;
         let mut p = compilation.rustdoc_process(unit, *script_meta)?;
 
@@ -237,19 +214,17 @@ fn run_doc_tests(
             p.arg("--target").arg(target.rustc_target());
         }
 
-        if doctest_xcompile {
-            if let Some((runtool, runtool_args)) = compilation.target_runner(unit.kind) {
-                p.arg("--test-runtool").arg(runtool);
-                for arg in runtool_args {
-                    p.arg("--test-runtool-arg").arg(arg);
-                }
-            }
-            if let Some(linker) = linker {
-                let mut joined = OsString::from("linker=");
-                joined.push(linker);
-                p.arg("-C").arg(joined);
+        if let Some((runtool, runtool_args)) = compilation.target_runner(unit.kind) {
+            p.arg("--test-runtool").arg(runtool);
+            for arg in runtool_args {
+                p.arg("--test-runtool-arg").arg(arg);
             }
         }
+        if let Some(linker) = linker {
+            let mut joined = OsString::from("linker=");
+            joined.push(linker);
+            p.arg("-C").arg(joined);
+        }
 
         if unit.profile.panic != PanicStrategy::Unwind {
             p.arg("-C").arg(format!("panic={}", unit.profile.panic));

src/doc/src/reference/unstable.md

@@ -84,7 +84,6 @@ Each new feature described below should explain how to use it.
     * [root-dir](#root-dir) --- Controls the root directory relative to which paths are printed
 * Compile behavior
     * [mtime-on-use](#mtime-on-use) --- Updates the last-modified timestamp on every dependency every time it is used, to provide a mechanism to delete unused artifacts.
-    * [doctest-xcompile](#doctest-xcompile) --- Supports running doctests with the `--target` flag.
     * [build-std](#build-std) --- Builds the standard library instead of using pre-built binaries.
     * [build-std-features](#build-std-features) --- Sets features to use with the standard library.
     * [binary-dep-depinfo](#binary-dep-depinfo) --- Causes the dep-info file to track binary dependencies.
@@ -278,21 +277,6 @@ Available template variables:
 The `-Zroot-dir` flag sets the root directory relative to which paths are printed.
 This affects both diagnostics and paths emitted by the `file!()` macro.
 
-## doctest-xcompile
-* Tracking Issue: [#7040](https://github.com/rust-lang/cargo/issues/7040)
-* Tracking Rustc Issue: [#64245](https://github.com/rust-lang/rust/issues/64245)
-
-This flag changes `cargo test`'s behavior when handling doctests when
-a target is passed. Currently, if a target is passed that is different
-from the host cargo will simply skip testing doctests. If this flag is
-present, cargo will continue as normal, passing the tests to doctest,
-while also passing it a `--target` option, as well as passing along
-information from `.cargo/config.toml`. See the rustc issue for more information.
-
-```sh
-cargo test --target foo -Zdoctest-xcompile
-```
-
 ## Build-plan
 * Tracking Issue: [#5579](https://github.com/rust-lang/cargo/issues/5579)
 
@@ -2171,3 +2155,7 @@ See [`cargo fix --edition`](../commands/cargo-fix.md) and [The Edition Guide](..
 
 Support for automatically deleting old files was stabilized in Rust 1.88.
 More information can be found in the [config chapter](config.md#cache).
+
+## doctest-xcompile
+
+Doctest cross-compiling is now unconditionally enabled starting in Rust 1.89. Running doctests with `cargo test` will now honor the `--target` flag.

tests/testsuite/artifact_dep.rs

@@ -1246,7 +1246,7 @@ fn non_build_script_deps_adopt_specified_target_unconditionally() {
 }
 
 #[cargo_test]
-fn no_cross_doctests_works_with_artifacts() {
+fn cross_doctests_works_with_artifacts() {
     if cross_compile::disabled() {
         return;
     }
@@ -1302,40 +1302,24 @@ fn no_cross_doctests_works_with_artifacts() {
     println!("c");
     let target = cross_compile::alternate();
 
-    // This will build the library, but does not build or run doc tests.
-    // This should probably be a warning or error.
-    p.cargo("test -Z bindeps -v --doc --target")
-        .arg(&target)
-        .masquerade_as_nightly_cargo(&["bindeps"])
-        .with_stderr_data(str![[r#"
-[COMPILING] bar v0.5.0 ([ROOT]/foo/bar)
-[RUNNING] `rustc --crate-name bar --edition=2015 bar/src/lib.rs [..]--target [ALT_TARGET] [..]
-[RUNNING] `rustc --crate-name bar --edition=2015 bar/src/main.rs [..]--target [ALT_TARGET] [..]
-[COMPILING] foo v0.0.1 ([ROOT]/foo)
-[RUNNING] `rustc --crate-name foo [..]`
-[FINISHED] `test` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
-[NOTE] skipping doctests for foo v0.0.1 ([ROOT]/foo) (lib), cross-compilation doctests are not yet supported
-See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#doctest-xcompile for more information.
-
-"#]])
-        .run();
-
     if !cross_compile::can_run_on_host() {
         return;
     }
 
-    // This tests the library, but does not run the doc tests.
     p.cargo("test -Z bindeps -v --target")
         .arg(&target)
         .masquerade_as_nightly_cargo(&["bindeps"])
         .with_stderr_data(str![[r#"
-[FRESH] bar v0.5.0 ([ROOT]/foo/bar)
+[COMPILING] bar v0.5.0 ([ROOT]/foo/bar)
+[RUNNING] `rustc --crate-name bar --edition=2015 bar/src/lib.rs [..]--target [ALT_TARGET] [..]
+[RUNNING] `rustc --crate-name bar --edition=2015 bar/src/main.rs [..]--target [ALT_TARGET] [..]
 [COMPILING] foo v0.0.1 ([ROOT]/foo)
-[RUNNING] `rustc --crate-name foo [..]--test[..]
+[RUNNING] `rustc --crate-name foo [..]
+[RUNNING] `rustc --crate-name foo [..]
 [FINISHED] `test` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
 [RUNNING] `[ROOT]/foo/target/[ALT_TARGET]/debug/deps/foo-[HASH][EXE]`
-[NOTE] skipping doctests for foo v0.0.1 ([ROOT]/foo) (lib), cross-compilation doctests are not yet supported
-See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#doctest-xcompile for more information.
+[DOCTEST] foo
+[RUNNING] `rustdoc [..]--test src/lib.rs --test-run-directory [ROOT]/foo --target [ALT_TARGET] [..]
 
 "#]])
         .run();

tests/testsuite/build_script.rs

@@ -5600,10 +5600,10 @@ test check_target ... ok
 "#]])
         .run();
 
+    // Remove check once 1.88 is stable
     if cargo_test_support::is_nightly() {
-        p.cargo("test --workspace -Z doctest-xcompile --doc --target")
+        p.cargo("test --workspace --doc --target")
             .arg(&target)
-            .masquerade_as_nightly_cargo(&["doctest-xcompile"])
             .with_stdout_data(str![[r#"
 ...
 test foo/src/lib.rs - (line 2) ... ok