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 80785891b..18771c3d2 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 3dce146e6..49792d6be 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 1ca72d577..9108d6165 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 3f4ed6072..9e26f8aae 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 e7e9b36fb..df0101be5 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 2967d7381..24fcc70ff 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 b95902c4e..44ff593fd 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 85260b067..1ee2f7672 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.