Skip to content

Tracking Issue for Cross Compiling Doctests #64245

Closed
@Goirad

Description

@Goirad
Contributor

This is an issue to track the functionality added by PR#60387, and also by extension this PR in cargo.

PR#60387 adds three options to rustdoc:

  • --enable-per-target-ignores which adds a compiletest-like mechanism for ignoring platform on a substring basis (eg ignore-foo)
  • --runtool and --runtool-arg for specifying an external program and its arguments, to which the compiled doctest binary will be passed as the final argument

The companion PR adds a flag to cargo for enabling this feature as well as cross-compiling doctests and parsing runtool tokens from a .cargo/config.

Eventually another PR for x.py can either enable this unconditionally or add a flag for testing the extensive documentation in the standard library on other platforms.

This solves cargo issue #6460

Activity

added
C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFC
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
B-unstableBlocker: Implemented in the nightly compiler and unstable.
requires-nightlyThis issue requires a nightly compiler in some way.
on Sep 7, 2019
added
A-doctestsArea: Documentation tests, run by rustdoc
on Aug 27, 2020
jyn514

jyn514 commented on Nov 12, 2020

@jyn514
Member

@Goirad I don't quite understand - what is this tracking? It sounds like all the functionality is already implemented in rustdoc, what's left to do?

ehuss

ehuss commented on Nov 29, 2021

@ehuss
Contributor

@jyn514 The rustdoc flags are still unstable, so this is tracking the stabilization of those flags.

safinaskar

safinaskar commented on Feb 2, 2022

@safinaskar
Contributor

My host is x86_64-unknown-linux-gnu. I'm building for x86_64-unknown-linux-musl. Resulting binaries can be run on this host without any problems. But cargo test --target=x86_64-unknown-linux-musl -Zdoctest-xcompile simply compiles test instead of running them. Moreover, this command doesn't even warn that doctests was merely compiled instead of run! I want tests to run. And I don't want some kind of Cargo.toml configuring for this.

Moreover, if I don't add -Zdoctest-xcompile, doctests are not compiled at all, and there is no any warning about this

ehuss

ehuss commented on Feb 2, 2022

@ehuss
Contributor

@safinaskar Can you provide some more information? The tests appear to be run for me with cross compiling to x86_64-unknown-linux-musl:

~/Temp/foo> cargo test --target x86_64-unknown-linux-musl -Zdoctest-xcompile
    Finished test [unoptimized + debuginfo] target(s) in 0.00s
     Running unittests (target/x86_64-unknown-linux-musl/debug/deps/foo-65396ef18f7af6ca)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests foo

running 1 test
test src/lib.rs - abc (line 1) ... FAILED

failures:

---- src/lib.rs - abc (line 1) stdout ----
Test executable failed (exit code 101).

stderr:
thread 'main' panicked at 'assertion failed: `(left == right)`
  left: `1`,
 right: `2`', src/lib.rs:3:1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

As for warnings, there is a warning displayed when the verbose flag:

~/Temp/foo> cargo test --target x86_64-unknown-linux-musl --doc -v
       Fresh foo v0.1.0 (/home/eric/Temp/foo)
    Finished test [unoptimized + debuginfo] target(s) in 0.00s
note: skipping doctests for foo v0.1.0 (/home/eric/Temp/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.

The reason it is only displayed with -v is that otherwise it would be displayed 100% of the time when cross-compiling, and there is no workaround other than using nightly. We felt that would be an over-agressive warning for now.

We definitely recognize that can cause people to not know that tests are not being run. Hopefully most of the time that is evident by the absence of any doc-test display.

I would like to see this feature move towards stabilization to help prevent that oversight, so any experience reports would be helpful if you get it to work.

safinaskar

safinaskar commented on Feb 3, 2022

@safinaskar
Contributor

@ehuss

Can you provide some more information?

I am unable to reproduce. I. e. now everything works. It seems there was no problem in the first place, sorry

18 remaining items

weihanglo

weihanglo commented on Dec 13, 2024

@weihanglo
Member

Instead of stabilizing these rustdoc flags, if Cargo could take over the test execution (which is prposed in rust-lang/testing-devex-team#5), it is more nature to use. And rustdoc may not need to maintain those flags?
(If rustdoc team is happy to stabilize these flags, I am okay as well)

That said, it doesn't resolve doctest failures ehuss mentioned :(

ehuss

ehuss commented on Feb 15, 2025

@ehuss
Contributor

I have posted a PR at #137096 to recommend stabilizing these.

In regards to @weihanglo's suggestion about offloading the responsibility to cargo, I think that sounds like a good long-term plan. However, my expectation is that it will take a while for that to come to fruition. Once cargo and rustdoc are able to support that, then I would expect cargo to just stop using the flags, but that doesn't necessarily mean that flags are not useful since other tools could find a use for them.

added 2 commits that reference this issue on Apr 2, 2025

Auto merge of rust-lang#137096 - ehuss:stabilize-doctest-xcompile, r=…

Auto merge of rust-lang#137096 - ehuss:stabilize-doctest-xcompile, r=…

added a commit that references this issue on Apr 24, 2025

Rollup merge of rust-lang#137096 - ehuss:stabilize-doctest-xcompile, …

610ed82
added a commit that references this issue on Apr 25, 2025
kpfleming

kpfleming commented on Apr 25, 2025

@kpfleming

Should we anticipate this being included in Rust 1.88 now?

weihanglo

weihanglo commented on Apr 25, 2025

@weihanglo
Member

No. This only stabilizes rustdoc part. The cargo part needs to be updated and adjusted, and might or might not need another FCP on the Cargo team.

Also, Cargo depends on stable toolchains generally. It means that not until 1.88 is out Cargo will not able to use these flags on stable. I'll look at 1.90 as the earliest possible release including it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-crossArea: Cross compilationA-doctestsArea: Documentation tests, run by rustdocB-unstableBlocker: Implemented in the nightly compiler and unstable.C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCT-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.requires-nightlyThis issue requires a nightly compiler in some way.

    Type

    No type

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

      Development

      Participants

      @ehuss@sanxiyn@kpfleming@Centril@safinaskar

      Issue actions

        Tracking Issue for Cross Compiling Doctests · Issue #64245 · rust-lang/rust