Closed
Description
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 (egignore-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
Metadata
Metadata
Assignees
Labels
Area: Cross compilationArea: Documentation tests, run by rustdocBlocker: Implemented in the nightly compiler and unstable.Category: An issue tracking the progress of sth. like the implementation of an RFCRelevant to the rustdoc team, which will review and decide on the PR/issue.This issue requires a nightly compiler in some way.
Type
Projects
Status
Done
Activity
jyn514 commentedon Nov 12, 2020
@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 commentedon Nov 29, 2021
@jyn514 The rustdoc flags are still unstable, so this is tracking the stabilization of those flags.
safinaskar commentedon Feb 2, 2022
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 thisehuss commentedon Feb 2, 2022
@safinaskar Can you provide some more information? The tests appear to be run for me with cross compiling to
x86_64-unknown-linux-musl
:As for warnings, there is a warning displayed when the verbose flag:
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 commentedon Feb 3, 2022
@ehuss
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 commentedon Dec 13, 2024
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 commentedon Feb 15, 2025
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.
Auto merge of rust-lang#137096 - ehuss:stabilize-doctest-xcompile, r=…
Auto merge of rust-lang#137096 - ehuss:stabilize-doctest-xcompile, r=…
Rollup merge of rust-lang#137096 - ehuss:stabilize-doctest-xcompile, …
Unrolled build for rust-lang#137096
kpfleming commentedon Apr 25, 2025
Should we anticipate this being included in Rust 1.88 now?
weihanglo commentedon Apr 25, 2025
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.
Rollup merge of #137096 - ehuss:stabilize-doctest-xcompile, r=fmease