Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: some tweaks around cargo test #12288

Merged
merged 3 commits into from
Jun 19, 2023
+19 −37
Merged

docs: some tweaks around cargo test #12288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c4312a4
docs(cargo-test): missing apostrophe for possessive nouns
weihanglo Jun 17, 2023
b630ac1
docs(cargo-test): clarify the cwd is for running tests
weihanglo Jun 17, 2023
1320573
docs(unstable): remove tracking for `-Zdoctest-in-workspace`
weihanglo Jun 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/doc/man/cargo-test.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,17 +59,17 @@ on writing doc tests.

### Working directory of tests

The working directory of every test is set to the root directory of the package
the test belongs to.
Setting the working directory of tests to the package's root directory makes it
The working directory when running each unit and integration test is set to the
root directory of the package the test belongs to.
Setting the working directory of tests to the package's root directory makes it
possible for tests to reliably access the package's files using relative paths,
regardless from where `cargo test` was executed from.

For documentation tests, the working directory when invoking `rustdoc` is set to
the workspace root directory, and is also the directory `rustdoc` uses as the
compilation directory of each documentation test.
The working directory when running each documentation test is set to the root
directory of the package the test belongs to, and is controlled via `rustdoc`s
directory of the package the test belongs to, and is controlled via `rustdoc`'s
`--test-run-directory` option.

## OPTIONS
Expand Down
12 changes: 6 additions & 6 deletions src/doc/man/generated_txt/cargo-test.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,18 @@ DESCRIPTION
information on writing doc tests.

Working directory of tests
The working directory of every test is set to the root directory of the
package the test belongs to. Setting the working directory of tests to
the package’s root directory makes it possible for tests to reliably
access the package’s files using relative paths, regardless from where
cargo test was executed from.
The working directory when running each unit and integration test is set
to the root directory of the package the test belongs to. Setting the
working directory of tests to the package’s root directory makes it
possible for tests to reliably access the package’s files using
relative paths, regardless from where cargo test was executed from.

For documentation tests, the working directory when invoking rustdoc is
set to the workspace root directory, and is also the directory rustdoc
uses as the compilation directory of each documentation test. The
working directory when running each documentation test is set to the
root directory of the package the test belongs to, and is controlled via
rustdocs --test-run-directory option.
rustdoc’s --test-run-directory option.

OPTIONS
Test Options
Expand Down
8 changes: 4 additions & 4 deletions src/doc/src/commands/cargo-test.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,17 +59,17 @@ on writing doc tests.

### Working directory of tests

The working directory of every test is set to the root directory of the package
the test belongs to.
Setting the working directory of tests to the package's root directory makes it
The working directory when running each unit and integration test is set to the
root directory of the package the test belongs to.
Setting the working directory of tests to the package's root directory makes it
possible for tests to reliably access the package's files using relative paths,
regardless from where `cargo test` was executed from.

For documentation tests, the working directory when invoking `rustdoc` is set to
the workspace root directory, and is also the directory `rustdoc` uses as the
compilation directory of each documentation test.
The working directory when running each documentation test is set to the root
directory of the package the test belongs to, and is controlled via `rustdoc`s
directory of the package the test belongs to, and is controlled via `rustdoc`'s
`--test-run-directory` option.

## OPTIONS
Expand Down
20 changes: 1 addition & 19 deletions src/doc/src/reference/unstable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1185,24 +1185,6 @@ cargo +nightly -Zunstable-options config get build.rustflags
If no config value is included, it will display all config values. See the
`--help` output for more options available.

### `doctest-in-workspace`

* Tracking Issue: [#9427](https://github.com/rust-lang/cargo/issues/9427)

The `-Z doctest-in-workspace` flag changes the behavior of the current working
directory used when running doctests. Historically, Cargo has run `rustdoc
--test` relative to the root of the package, with paths relative from that
root. However, this is inconsistent with how `rustc` and `rustdoc` are
normally run in a workspace, where they are run relative to the workspace
root. This inconsistency causes problems in various ways, such as when passing
RUSTDOCFLAGS with relative paths, or dealing with diagnostic output.

The `-Z doctest-in-workspace` flag causes cargo to switch to running `rustdoc`
from the root of the workspace. It also passes the `--test-run-directory` to
`rustdoc` so that when *running* the tests, they are run from the root of the
package. This preserves backwards compatibility and is consistent with how
normal unittests are run.

### rustc `--print`

* Tracking Issue: [#9357](https://github.com/rust-lang/cargo/issues/9357)
Expand Down Expand Up @@ -1799,4 +1781,4 @@ The [`cargo logout`] command has been stabilized in the 1.70 release.
The `-Z doctest-in-workspace` option for `cargo test` has been stabilized and
enabled by default in the 1.72 release. See the
[`cargo test` documentation](../commands/cargo-test.md#working-directory-of-tests)
for more information about the working directory for compiling and running tests.
for more information about the working directory for compiling and running tests.
8 changes: 4 additions & 4 deletions src/etc/man/cargo-test.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,17 +54,17 @@ and may change in the future; beware of depending on it.
See the \fIrustdoc book\fR <https://doc.rust\-lang.org/rustdoc/> for more information
on writing doc tests.
.SS "Working directory of tests"
The working directory of every test is set to the root directory of the package
the test belongs to.
Setting the working directory of tests to the package\[cq]s root directory makes it
The working directory when running each unit and integration test is set to the
root directory of the package the test belongs to.
Setting the working directory of tests to the package\[cq]s root directory makes it
possible for tests to reliably access the package\[cq]s files using relative paths,
regardless from where \fBcargo test\fR was executed from.
.sp
For documentation tests, the working directory when invoking \fBrustdoc\fR is set to
the workspace root directory, and is also the directory \fBrustdoc\fR uses as the
compilation directory of each documentation test.
The working directory when running each documentation test is set to the root
directory of the package the test belongs to, and is controlled via \fBrustdoc\fRs
directory of the package the test belongs to, and is controlled via \fBrustdoc\fR\[cq]s
\fB\-\-test\-run\-directory\fR option.
.SH "OPTIONS"
.SS "Test Options"
Expand Down