Tracking Issue for rustdoc --test-run-directory

[ehuss]

Summary

This is a tracking issue for the --test-run-directory flag in rustdoc. This flag changes the directory where doctests are run. This was added to support changing the directory used while running rustdoc --test in a Cargo workspace. See rust-lang/cargo#9427 for more information.

Unresolved Questions

None at this time.

Implementation history

• Add unstable option to control doctest run directory #81264 — Initial PR.

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

cc @Swatinem

[Swatinem]

Request for Stabilization

I opened #103682 with the aim to stabilize this rustdoc flag, primarily to facilitate the cargo doctest-in-workspace flag, and to eventually making it the default.

Summary

The --test-run-directory flag in combination with --test allows specifying an explicit directory in which rustdoc will run the compiled doctests. The default, without this explicit flag, is to run the resulting doctest binaries in the same current working directory as rustdoc itself.

This flag is primarily the building block for the doctest-in-workspace cargo flag (See rust-lang/cargo#9427).

With that flag, doctests are handled consistently to unit- and integration tests: They will be compiled relative to the cargo workspace root, but they are run in the crate directory.

Documentation

The flag is currently not documented as part of the unstable rustdoc features.

Tests

• src/test/rustdoc-ui/run-directory.rs -- highlights usage with cwd-sensitive std::fs functions inside doctests.
• cargo tests/testsuite/doc.rs -- shows indirect usage via the cargo doctest-in-workspace flag.

Unresolved questions

• Similar flags that allow hooking into or observing the side effects of rustdoc test compilation, such as --run-tool or --persist-doctests are not stable yet, and there does not seem to be a push to stabilization either.
• The usefulness of this flag when invoking rustdoc manually might be limited. But it is a requirement for the cargo doctest-in-workspace flag.
• ☝🏻 Is there maybe a better alternative to solve the compile/run directory inconsistency that exists in cargo workspaces today?

[Swatinem]

@ehuss over in rust-lang/cargo#9427 (comment) expressed agreement to make the doctest-in-workspace cargo flag the default, considering it rather a bugfix for the current inconsistent behavior.

However, stabilizing --test-run-directory is a requirement for that, and there does not seem to be a better alternative to it.

@GuillaumeGomez is there anything I can do to move stabilization (#103682) forward?

[GuillaumeGomez]

Next step is the FCP. I'll start on the PR.

[DXist]

cargo test runs doc tests by default and doesn't allow to specify --test-run-directory.

My project uses sqlx which tries to create target/sqlx/<crate_name>/ directory. But if fails because I run the build inside a container against immutable source.

Instead I expect that the test should stay in the workspace directory and use <workspace_root>/target which is mounted as a build cache volume.