diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md index 4b07049fd07..f43e5b24f86 100644 --- a/src/doc/man/cargo-bench.md +++ b/src/doc/man/cargo-bench.md @@ -28,10 +28,11 @@ similarly named benchmarks like `foobar`): cargo bench -- foo --exact -Benchmarks are built with the `--test` option to `rustc` which creates an -executable with a `main` function that automatically runs all functions -annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to -the test harness to tell it to run only benchmarks. +Benchmarks are built with the `--test` option to `rustc` which creates a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the `#[bench]` attribute. +Cargo passes the `--bench` flag to the test harness to tell it to run +only benchmarks. The libtest harness may be disabled by setting `harness = false` in the target manifest settings, in which case your code will need to provide its own `main` @@ -81,6 +82,8 @@ 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. +{{> options-targets-bin-auto-built }} + {{> options-targets }} {{> section-features }} diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md index 2d56a2806d5..e4dc63f5b28 100644 --- a/src/doc/man/cargo-build.md +++ b/src/doc/man/cargo-build.md @@ -23,6 +23,8 @@ When no target selection options are given, `cargo build` will build all binary and library targets of the selected packages. Binaries are skipped if they have `required-features` that are missing. +{{> options-targets-bin-auto-built }} + {{> options-targets }} {{> section-features }} diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md index e9839c92ded..32d3b0e5be7 100644 --- a/src/doc/man/cargo-rustc.md +++ b/src/doc/man/cargo-rustc.md @@ -35,6 +35,8 @@ To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` When no target selection options are given, `cargo rustc` will build all binary and library targets of the selected package. +{{> options-targets-bin-auto-built }} + {{> options-targets }} {{> section-features }} diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md index 6c1ea88fa96..b948d91c24c 100644 --- a/src/doc/man/cargo-test.md +++ b/src/doc/man/cargo-test.md @@ -12,7 +12,7 @@ cargo-test - Execute unit and integration tests of a package ## DESCRIPTION -Compile and execute unit and integration tests. +Compile and execute unit, integration, and documentation tests. The test filtering argument `TESTNAME` and all the arguments following the two dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's @@ -27,20 +27,34 @@ on 3 threads in parallel: cargo test foo -- --test-threads 3 -Tests are built with the `--test` option to `rustc` which creates an -executable with a `main` function that automatically runs all functions -annotated with the `#[test]` attribute in multiple threads. `#[bench]` -annotated functions will also be run with one iteration to verify that they -are functional. +Tests are built with the `--test` option to `rustc` which creates a special +executable by linking your code with libtest. The executable automatically +runs all functions annotated with the `#[test]` attribute in multiple threads. +`#[bench]` annotated functions will also be run with one iteration to verify +that they are functional. + +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. The libtest harness may be disabled by setting `harness = false` in the target manifest settings, in which case your code will need to provide its own `main` function to handle running tests. +### Documentation tests + Documentation tests are also run by default, which is handled by `rustdoc`. It -extracts code samples from documentation comments and executes them. See the -[rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information on -writing doc tests. +extracts code samples from documentation comments of the library target, and +then executes them. + +Different from normal test targets, each code block compiles to a doctest +executable on the fly with `rustc`. These executables run in parallel in +separate processes. The compilation of a code block is in fact a part of test +function controlled by libtest, so some options such as `--jobs` might not +take effect. Note that this execution model of doctests is not guaranteed +and may change in the future; beware of depending on it. + +See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information +on writing doc tests. ## OPTIONS @@ -73,13 +87,7 @@ 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. -Binary targets are automatically built if there is an integration test or -benchmark. This allows an integration test to execute the binary to exercise -and test its behavior. The `CARGO_BIN_EXE_` -[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) -is set when the integration test is built so that it can use the -[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the -executable. +{{> 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 f3b46f6981c..972bed35332 100644 --- a/src/doc/man/generated_txt/cargo-bench.txt +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -23,10 +23,11 @@ DESCRIPTION cargo bench -- foo --exact - Benchmarks are built with the --test option to rustc which creates an - executable with a main function that automatically runs all functions - annotated with the #[bench] attribute. Cargo passes the --bench flag to - the test harness to tell it to run only benchmarks. + Benchmarks are built with the --test option to rustc which creates a + special executable by linking your code with libtest. The executable + automatically runs all functions annotated with the #[bench] attribute. + Cargo passes the --bench flag to the test harness to tell it to run only + benchmarks. The libtest harness may be disabled by setting harness = false in the target manifest settings, in which case your code will need to provide @@ -117,6 +118,15 @@ OPTIONS options that take a target by name ignore the bench flag and will always benchmark the given target. + 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. The + CARGO_BIN_EXE_ environment variable + + is set when the integration test is built so that it can use the env + macro to locate the + executable. + Passing target selection flags will benchmark only the specified targets. diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt index db0497dd8e2..818dee1d92d 100644 --- a/src/doc/man/generated_txt/cargo-build.txt +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -51,6 +51,15 @@ OPTIONS binary and library targets of the selected packages. Binaries are skipped if they have required-features that are missing. + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_ environment variable + + is set when the integration test is built so that it can use the env + macro to locate the + executable. + Passing target selection flags will build only the specified targets. Note that --bin, --example, --test and --bench flags also support common diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt index 2ab3f93faf4..aab1921bf59 100644 --- a/src/doc/man/generated_txt/cargo-rustc.txt +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -42,6 +42,15 @@ OPTIONS When no target selection options are given, cargo rustc will build all binary and library targets of the selected package. + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_ environment variable + + is set when the integration test is built so that it can use the env + macro to locate the + executable. + Passing target selection flags will build only the specified targets. Note that --bin, --example, --test and --bench flags also support common diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index 56e3641b1d6..0c66532da73 100644 --- a/src/doc/man/generated_txt/cargo-test.txt +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -7,7 +7,7 @@ SYNOPSIS cargo test [options] [testname] [-- test-options] DESCRIPTION - Compile and execute unit and integration tests. + Compile and execute unit, integration, and documentation tests. The test filtering argument TESTNAME and all the arguments following the two dashes (--) are passed to the test binaries and thus to libtest @@ -23,20 +23,34 @@ DESCRIPTION cargo test foo -- --test-threads 3 - Tests are built with the --test option to rustc which creates an - executable with a main function that automatically runs all functions - annotated with the #[test] attribute in multiple threads. #[bench] - annotated functions will also be run with one iteration to verify that - they are functional. + Tests are built with the --test option to rustc which creates a special + executable by linking your code with libtest. The executable + automatically runs all functions annotated with the #[test] attribute in + multiple threads. #[bench] annotated functions will also be run with one + iteration to verify that they are functional. + + If the package contains multiple test targets, each target compiles to a + special executable as aforementioned, and then is run serially. The libtest harness may be disabled by setting harness = false in the target manifest settings, in which case your code will need to provide its own main function to handle running tests. + Documentation tests Documentation tests are also run by default, which is handled by - rustdoc. It extracts code samples from documentation comments and - executes them. See the rustdoc book - for more information on writing doc tests. + rustdoc. It extracts code samples from documentation comments of the + library target, and then executes them. + + Different from normal test targets, each code block compiles to a + doctest executable on the fly with rustc. These executables run in + parallel in separate processes. The compilation of a code block is in + fact a part of test function controlled by libtest, so some options such + as --jobs might not take effect. Note that this execution model of + doctests is not guaranteed and may change in the future; beware of + depending on it. + + See the rustdoc book for more + information on writing doc tests. OPTIONS Test Options @@ -116,9 +130,9 @@ OPTIONS the library in the manifest. Binary targets are automatically built if there is an integration test - or benchmark. This allows an integration test to execute the binary to - exercise and test its behavior. The CARGO_BIN_EXE_ environment - variable + or benchmark being selected to test. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_ environment variable is set when the integration test is built so that it can use the env macro to locate the diff --git a/src/doc/man/includes/options-targets-bin-auto-built.md b/src/doc/man/includes/options-targets-bin-auto-built.md new file mode 100644 index 00000000000..c2234ab79f9 --- /dev/null +++ b/src/doc/man/includes/options-targets-bin-auto-built.md @@ -0,0 +1,8 @@ +Binary targets are automatically built if there is an integration test or +benchmark being selected to {{lower actionverb}}. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index a7fdebc5e42..1e60016b39f 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -28,10 +28,11 @@ similarly named benchmarks like `foobar`): cargo bench -- foo --exact -Benchmarks are built with the `--test` option to `rustc` which creates an -executable with a `main` function that automatically runs all functions -annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to -the test harness to tell it to run only benchmarks. +Benchmarks are built with the `--test` option to `rustc` which creates a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the `#[bench]` attribute. +Cargo passes the `--bench` flag to the test harness to tell it to run +only benchmarks. The libtest harness may be disabled by setting `harness = false` in the target manifest settings, in which case your code will need to provide its own `main` @@ -138,6 +139,16 @@ 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. +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. +The `CARGO_BIN_EXE_` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + Passing target selection flags will benchmark only the specified targets. diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index 7ba043b1a07..7f6a16a6536 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -66,6 +66,16 @@ When no target selection options are given, `cargo build` will build all binary and library targets of the selected packages. Binaries are skipped if they have `required-features` that are missing. +Binary targets are automatically built if there is an integration test or +benchmark being selected to build. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + Passing target selection flags will build only the specified targets. diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index 6101bf343a6..6fd56810021 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -53,6 +53,16 @@ format. When no target selection options are given, `cargo rustc` will build all binary and library targets of the selected package. +Binary targets are automatically built if there is an integration test or +benchmark being selected to build. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + + Passing target selection flags will build only the specified targets. diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 203fee22979..a940ff24d56 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -12,7 +12,7 @@ cargo-test - Execute unit and integration tests of a package ## DESCRIPTION -Compile and execute unit and integration tests. +Compile and execute unit, integration, and documentation tests. The test filtering argument `TESTNAME` and all the arguments following the two dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's @@ -27,20 +27,34 @@ on 3 threads in parallel: cargo test foo -- --test-threads 3 -Tests are built with the `--test` option to `rustc` which creates an -executable with a `main` function that automatically runs all functions -annotated with the `#[test]` attribute in multiple threads. `#[bench]` -annotated functions will also be run with one iteration to verify that they -are functional. +Tests are built with the `--test` option to `rustc` which creates a special +executable by linking your code with libtest. The executable automatically +runs all functions annotated with the `#[test]` attribute in multiple threads. +`#[bench]` annotated functions will also be run with one iteration to verify +that they are functional. + +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. The libtest harness may be disabled by setting `harness = false` in the target manifest settings, in which case your code will need to provide its own `main` function to handle running tests. +### Documentation tests + Documentation tests are also run by default, which is handled by `rustdoc`. It -extracts code samples from documentation comments and executes them. See the -[rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information on -writing doc tests. +extracts code samples from documentation comments of the library target, and +then executes them. + +Different from normal test targets, each code block compiles to a doctest +executable on the fly with `rustc`. These executables run in parallel in +separate processes. The compilation of a code block is in fact a part of test +function controlled by libtest, so some options such as `--jobs` might not +take effect. Note that this execution model of doctests is not guaranteed +and may change in the future; beware of depending on it. + +See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information +on writing doc tests. ## OPTIONS @@ -131,13 +145,15 @@ Doc tests for libraries may be disabled by setting `doctest = false` for the library in the manifest. Binary targets are automatically built if there is an integration test or -benchmark. This allows an integration test to execute the binary to exercise -and test its behavior. The `CARGO_BIN_EXE_` +benchmark being selected to test. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_` [environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) is set when the integration test is built so that it can use the [`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the executable. + Passing target selection flags will test only the specified targets. diff --git a/src/doc/src/guide/tests.md b/src/doc/src/guide/tests.md index 50ee6ddb000..40cbe9f92e0 100644 --- a/src/doc/src/guide/tests.md +++ b/src/doc/src/guide/tests.md @@ -2,9 +2,9 @@ Cargo can run your tests with the `cargo test` command. Cargo looks for tests to run in two places: in each of your `src` files and any tests in `tests/`. -Tests in your `src` files should be unit tests, and tests in `tests/` should be -integration-style tests. As such, you’ll need to import your crates into -the files in `tests`. +Tests in your `src` files should be unit tests and [documentation tests]. +Tests in `tests/` should be integration-style tests. As such, you’ll need to +import your crates into the files in `tests`. Here's an example of running `cargo test` in our [package][def-package], which currently has no tests: @@ -31,10 +31,14 @@ $ cargo test foo This will run any test with `foo` in its name. -`cargo test` runs additional checks as well. It will compile any -examples you’ve included and will also test the examples in your -documentation. Please see the [testing guide][testing] in the Rust -documentation for more details. +`cargo test` runs additional checks as well. It will compile any examples +you’ve included to ensure they are still compiles. It also run documentation +tests to ensure your code samples from documentation comments compiles. +Please see the [testing guide][testing] in the Rust documentation for a general +view of writing and organizing tests. See [Cargo Targets: Tests] to learn more +about different styles of tests in Cargo. +[documentation tests]: ../../rustdoc/write-documentation/documentation-tests.html [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' [testing]: ../../book/ch11-00-testing.html +[Cargo Targets: Tests]: ../reference/cargo-targets.html#tests diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md index 04ca854efa5..7aea15109f2 100644 --- a/src/doc/src/reference/cargo-targets.md +++ b/src/doc/src/reference/cargo-targets.md @@ -100,7 +100,13 @@ parallel, reporting the success and failure of each test. See [the `harness` field](#the-harness-field) if you want to use a different harness or test strategy. +> **Note**: There is another special style of test in Cargo: +> [documentation tests][documentation examples]. +> They are handled by `rustdoc` and have a slightly different execution model. +> For more information, please see [`cargo test`][cargo-test-documentation-tests]. + [libtest harness]: ../../rustc/tests/index.html +[cargo-test-documentation-tests]: ../commands/cargo-test.md#documentation-tests #### Integration tests diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 45be2c2de13..230290583c2 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -28,10 +28,11 @@ cargo bench \-\- foo \-\-exact .fi .RE .sp -Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an -executable with a \fBmain\fR function that automatically runs all functions -annotated with the \fB#[bench]\fR attribute. Cargo passes the \fB\-\-bench\fR flag to -the test harness to tell it to run only benchmarks. +Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the \fB#[bench]\fR attribute. +Cargo passes the \fB\-\-bench\fR flag to the test harness to tell it to run +only benchmarks. .sp The libtest harness may be disabled by setting \fBharness = false\fR in the target manifest settings, in which case your code will need to provide its own \fBmain\fR @@ -143,6 +144,15 @@ 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 target. .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. +The \fBCARGO_BIN_EXE_\fR +\fIenvironment variable\fR +is set when the integration test is built so that it can use the +\fI\f(BIenv\fI macro\fR to locate the +executable. +.sp Passing target selection flags will benchmark only the specified targets. .sp diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index f77c71a89e1..179446ed634 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -55,6 +55,15 @@ When no target selection options are given, \fBcargo build\fR will build all binary and library targets of the selected packages. Binaries are skipped if they have \fBrequired\-features\fR that are missing. .sp +Binary targets are automatically built if there is an integration test or +benchmark being selected to build. This allows an integration +test to execute the binary to exercise and test its behavior. +The \fBCARGO_BIN_EXE_\fR +\fIenvironment variable\fR +is set when the integration test is built so that it can use the +\fI\f(BIenv\fI macro\fR to locate the +executable. +.sp Passing target selection flags will build only the specified targets. .sp diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index 10567f2c53c..a2f8fd95f98 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -41,6 +41,15 @@ format. When no target selection options are given, \fBcargo rustc\fR will build all binary and library targets of the selected package. .sp +Binary targets are automatically built if there is an integration test or +benchmark being selected to build. This allows an integration +test to execute the binary to exercise and test its behavior. +The \fBCARGO_BIN_EXE_\fR +\fIenvironment variable\fR +is set when the integration test is built so that it can use the +\fI\f(BIenv\fI macro\fR to locate the +executable. +.sp Passing target selection flags will build only the specified targets. .sp diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index a1e32a405c4..ba3fa8944fe 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -8,7 +8,7 @@ cargo\-test \- Execute unit and integration tests of a package .SH "SYNOPSIS" \fBcargo test\fR [\fIoptions\fR] [\fItestname\fR] [\fB\-\-\fR \fItest\-options\fR] .SH "DESCRIPTION" -Compile and execute unit and integration tests. +Compile and execute unit, integration, and documentation tests. .sp The test filtering argument \fBTESTNAME\fR and all the arguments following the two dashes (\fB\-\-\fR) are passed to the test binaries and thus to \fIlibtest\fR (rustc's @@ -27,20 +27,32 @@ cargo test foo \-\- \-\-test\-threads 3 .fi .RE .sp -Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an -executable with a \fBmain\fR function that automatically runs all functions -annotated with the \fB#[test]\fR attribute in multiple threads. \fB#[bench]\fR -annotated functions will also be run with one iteration to verify that they -are functional. +Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a special +executable by linking your code with libtest. The executable automatically +runs all functions annotated with the \fB#[test]\fR attribute in multiple threads. +\fB#[bench]\fR annotated functions will also be run with one iteration to verify +that they are functional. +.sp +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. .sp The libtest harness may be disabled by setting \fBharness = false\fR in the target manifest settings, in which case your code will need to provide its own \fBmain\fR function to handle running tests. -.sp +.SS "Documentation tests" Documentation tests are also run by default, which is handled by \fBrustdoc\fR\&. It -extracts code samples from documentation comments and executes them. See the -\fIrustdoc book\fR for more information on -writing doc tests. +extracts code samples from documentation comments of the library target, and +then executes them. +.sp +Different from normal test targets, each code block compiles to a doctest +executable on the fly with \fBrustc\fR\&. These executables run in parallel in +separate processes. The compilation of a code block is in fact a part of test +function controlled by libtest, so some options such as \fB\-\-jobs\fR might not +take effect. Note that this execution model of doctests is not guaranteed +and may change in the future; beware of depending on it. +.sp +See the \fIrustdoc book\fR for more information +on writing doc tests. .SH "OPTIONS" .SS "Test Options" .sp @@ -139,8 +151,9 @@ Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the library in the manifest. .sp Binary targets are automatically built if there is an integration test or -benchmark. This allows an integration test to execute the binary to exercise -and test its behavior. The \fBCARGO_BIN_EXE_\fR +benchmark being selected to test. This allows an integration +test to execute the binary to exercise and test its behavior. +The \fBCARGO_BIN_EXE_\fR \fIenvironment variable\fR is set when the integration test is built so that it can use the \fI\f(BIenv\fI macro\fR to locate the