Change:
This is a tracking issue for the flag in rustdoc. This flag changes the directory where doctests are run. This was to support changing the directory used while running in a Cargo workspace. See for more information. None at this time. — Initial PR. 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
I opened with the aim to stabilize this rustdoc flag, primarily to facilitate the cargo flag, and to eventually making it the default. The flag in combination with 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 cargo flag (See ). 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. The flag is currently not documented as part of the . -- highlights usage with cwd-sensitive functions inside doctests. -- shows indirect usage via the cargo flag.Similar flags that allow hooking into or observing the side effects of rustdoc test compilation, such as are not stable yet, and there does not seem to be a push to stabilization either. The usefulness of this flag when invoking manually might be limited. But it is a requirement for the cargo flag. Is there maybe a better alternative to solve the compile/run directory inconsistency that exists in cargo workspaces today?
over in expressed agreement to make the cargo flag the default, considering it rather a bugfix for the current inconsistent behavior. However, stabilizing is a requirement for that, and there does not seem to be a better alternative to it. is there anything I can do to move stabilization () forward?
Next step is the FCP. I'll start on the PR.
cargo test runs doc tests by default and doesn't allow to specify . My project uses sqlx which tries to create 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 which is mounted as a build cache volume.

Discussion:
This flag will run your code examples as tests. For more, see [the chapter on documentation tests](write-documentation/documentation-tests.md). <del> See also `--test-args`. </del> <ins> See also `--test-args` and `--test-run-directory`. </ins> ## `--test-args`: pass options to test runner

See also `--test`. <ins> ## `--test-run-directory`: run code examples in a specific directory Using this flag looks like this: ```bash $ rustdoc src/lib.rs --test --test-run-directory=/path/to/working/directory ``` This flag will run your code examples in the specified working directory. For more, see [the chapter on documentation tests](write-documentation/documentation-tests.md). See also `--test`. </ins> ## `--target`: generate documentation for the specified target triple Using this flag looks like this:

This will include your README as documentation on the hidden struct `ReadmeDoctests`, which will then be tested alongside the rest of your doctests. <ins> ## Controlling the compilation and run directories By default, `rustdoc --test` will compile and run documentation test examples from the same working directory. The compilation directory is being used for compiler diagnostics, the `file!()` macro and the output of `rustdoc` test runner itself, whereas the run directory has an influence on file-system operations within documentation test examples, such as `std::fs::read_to_string`. The `--test-run-directory` flag allows controlling the run directory separately from the compilation directory. This is particularly useful in workspaces, where compiler invocations and thus diagnostics should be relative to the workspace directory, but documentation test examples should run relative to the crate directory. </ins>

stable("test-args", |o| { o.optmulti("", "test-args", "arguments to pass to the test runner", "ARGS") }), <del> unstable("test-run-directory", |o| { </del> <ins> stable("test-run-directory", |o| { </ins> o.optopt( "", "test-run-directory",

// revisions: correct incorrect // check-pass <del> // [correct]compile-flags:--test --test-run-directory={{src-base}} -Zunstable-options // [incorrect]compile-flags:--test --test-run-directory={{src-base}}/coverage -Zunstable-options </del> <ins> // [correct]compile-flags:--test --test-run-directory={{src-base}} // [incorrect]compile-flags:--test --test-run-directory={{src-base}}/coverage </ins> // normalize-stdout-test: "tests/rustdoc-ui" -> "$$DIR" // normalize-stdout-test "finished in d+.d+s" -> "finished in $$TIME"