From 03a5d8f4a7489a05a5eec3b6eef4c1f42f274c52 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 24 Apr 2023 20:19:15 -0700 Subject: [PATCH] Clarify documentation around test target setting. There was some confusion about the wording in this section regarding what happens with an example's `main` function. This tries to be more explicit to clarify what happens when an example is marked as a test. This also adds a few other clarifications and a link to the reference documentation. Closes #11528 --- src/doc/man/cargo-bench.md | 12 +++++++++--- src/doc/man/cargo-test.md | 11 +++++++++-- src/doc/man/generated_txt/cargo-bench.txt | 15 +++++++++++---- src/doc/man/generated_txt/cargo-test.txt | 17 +++++++++++++---- src/doc/src/commands/cargo-bench.md | 12 +++++++++--- src/doc/src/commands/cargo-test.md | 11 +++++++++-- src/etc/man/cargo-bench.1 | 12 +++++++++--- src/etc/man/cargo-test.1 | 11 +++++++++-- 8 files changed, 78 insertions(+), 23 deletions(-) diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md index 80785891b5b..18771c3d21e 100644 --- a/src/doc/man/cargo-bench.md +++ b/src/doc/man/cargo-bench.md @@ -86,11 +86,17 @@ following targets of the selected packages: The default behavior can be changed by setting the `bench` flag for the target in the manifest settings. Setting examples to `bench = true` will build and -run the example as a benchmark. Setting targets to `bench = false` will stop -them from being benchmarked by default. Target selection options that take a -target by name ignore the `bench` flag and will always benchmark the given +run the example as a benchmark, replacing the example's `main` function with +the libtest harness. + +Setting targets to `bench = false` will stop them from being bencharmked by +default. Target selection options that take a target by name (such as +`--example foo`) ignore the `bench` flag and will always benchmark the given target. +See [Configuring a target](../reference/cargo-targets.html#configuring-a-target) +for more information on per-target settings. + {{> options-targets-bin-auto-built }} {{> options-targets }} diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md index 3dce146e60d..49792d6bec2 100644 --- a/src/doc/man/cargo-test.md +++ b/src/doc/man/cargo-test.md @@ -89,13 +89,20 @@ following targets of the selected packages: The default behavior can be changed by setting the `test` flag for the target in the manifest settings. Setting examples to `test = true` will build and run -the example as a test. Setting targets to `test = false` will stop them from -being tested by default. Target selection options that take a target by name +the example as a test, replacing the example's `main` function with the +libtest harness. If you don't want the `main` function replaced, also include +`harness = false`, in which case the example will be built and executed as-is. + +Setting targets to `test = false` will stop them from being tested by default. +Target selection options that take a target by name (such as `--example foo`) ignore the `test` flag and will always test the given target. Doc tests for libraries may be disabled by setting `doctest = false` for the library in the manifest. +See [Configuring a target](../reference/cargo-targets.html#configuring-a-target) +for more information on per-target settings. + {{> options-targets-bin-auto-built }} {{> options-targets }} diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index 1ca72d577af..9108d6165b3 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -120,10 +120,17 @@ OPTIONS The default behavior can be changed by setting the bench flag for the target in the manifest settings. Setting examples to bench = true will - build and run the example as a benchmark. Setting targets to bench = - false will stop them from being benchmarked by default. Target selection - options that take a target by name ignore the bench flag and will always - benchmark the given target. + build and run the example as a benchmark, replacing the example’s main + function with the libtest harness. + + Setting targets to bench = false will stop them from being bencharmked + by default. Target selection options that take a target by name (such as + --example foo) ignore the bench flag and will always benchmark the given + target. + + See Configuring a target + + for more information on per-target settings. Binary targets are automatically built if there is an integration test or benchmark being selected to benchmark. This allows an integration diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index 3f4ed607235..9e26f8aaeb9 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -128,14 +128,23 @@ OPTIONS The default behavior can be changed by setting the test flag for the target in the manifest settings. Setting examples to test = true will - build and run the example as a test. Setting targets to test = false - will stop them from being tested by default. Target selection options - that take a target by name ignore the test flag and will always test the - given target. + build and run the example as a test, replacing the example’s main + function with the libtest harness. If you don’t want the main function + replaced, also include harness = false, in which case the example will + be built and executed as-is. + + Setting targets to test = false will stop them from being tested by + default. Target selection options that take a target by name (such as + --example foo) ignore the test flag and will always test the given + target. Doc tests for libraries may be disabled by setting doctest = false for the library in the manifest. + See Configuring a target + + for more information on per-target settings. + Binary targets are automatically built if there is an integration test or benchmark being selected to test. This allows an integration test to execute the binary to exercise and test its behavior. The diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index e7e9b36fb8f..df0101be5cf 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -143,11 +143,17 @@ following targets of the selected packages: The default behavior can be changed by setting the `bench` flag for the target in the manifest settings. Setting examples to `bench = true` will build and -run the example as a benchmark. Setting targets to `bench = false` will stop -them from being benchmarked by default. Target selection options that take a -target by name ignore the `bench` flag and will always benchmark the given +run the example as a benchmark, replacing the example's `main` function with +the libtest harness. + +Setting targets to `bench = false` will stop them from being bencharmked by +default. Target selection options that take a target by name (such as +`--example foo`) ignore the `bench` flag and will always benchmark the given target. +See [Configuring a target](../reference/cargo-targets.html#configuring-a-target) +for more information on per-target settings. + Binary targets are automatically built if there is an integration test or benchmark being selected to benchmark. This allows an integration test to execute the binary to exercise and test its behavior. diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 2967d7381e9..24fcc70ffa7 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -146,13 +146,20 @@ following targets of the selected packages: The default behavior can be changed by setting the `test` flag for the target in the manifest settings. Setting examples to `test = true` will build and run -the example as a test. Setting targets to `test = false` will stop them from -being tested by default. Target selection options that take a target by name +the example as a test, replacing the example's `main` function with the +libtest harness. If you don't want the `main` function replaced, also include +`harness = false`, in which case the example will be built and executed as-is. + +Setting targets to `test = false` will stop them from being tested by default. +Target selection options that take a target by name (such as `--example foo`) ignore the `test` flag and will always test the given target. Doc tests for libraries may be disabled by setting `doctest = false` for the library in the manifest. +See [Configuring a target](../reference/cargo-targets.html#configuring-a-target) +for more information on per-target settings. + Binary targets are automatically built if there is an integration test or benchmark being selected to test. This allows an integration test to execute the binary to exercise and test its behavior. diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index b95902c4ecf..44ff593fdd8 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -145,11 +145,17 @@ available) .sp The default behavior can be changed by setting the \fBbench\fR flag for the target in the manifest settings. Setting examples to \fBbench = true\fR will build and -run the example as a benchmark. Setting targets to \fBbench = false\fR will stop -them from being benchmarked by default. Target selection options that take a -target by name ignore the \fBbench\fR flag and will always benchmark the given +run the example as a benchmark, replacing the example\[cq]s \fBmain\fR function with +the libtest harness. +.sp +Setting targets to \fBbench = false\fR will stop them from being bencharmked by +default. Target selection options that take a target by name (such as +\fB\-\-example foo\fR) ignore the \fBbench\fR flag and will always benchmark the given target. .sp +See \fIConfiguring a target\fR +for more information on per\-target settings. +.sp Binary targets are automatically built if there is an integration test or benchmark being selected to benchmark. This allows an integration test to execute the binary to exercise and test its behavior. diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 85260b067b0..1ee2f76727f 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -149,13 +149,20 @@ available) .sp The default behavior can be changed by setting the \fBtest\fR flag for the target in the manifest settings. Setting examples to \fBtest = true\fR will build and run -the example as a test. Setting targets to \fBtest = false\fR will stop them from -being tested by default. Target selection options that take a target by name +the example as a test, replacing the example\[cq]s \fBmain\fR function with the +libtest harness. If you don\[cq]t want the \fBmain\fR function replaced, also include +\fBharness = false\fR, in which case the example will be built and executed as\-is. +.sp +Setting targets to \fBtest = false\fR will stop them from being tested by default. +Target selection options that take a target by name (such as \fB\-\-example foo\fR) ignore the \fBtest\fR flag and will always test the given target. .sp Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the library in the manifest. .sp +See \fIConfiguring a target\fR +for more information on per\-target settings. +.sp Binary targets are automatically built if there is an integration test or benchmark being selected to test. This allows an integration test to execute the binary to exercise and test its behavior.