From af0fbf4277395c31c7a68eaf61cb22823d1ce0ea Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Fri, 3 Jun 2022 19:47:11 +0800 Subject: [PATCH] doc: mention `cargo test` runs test targets serially --- src/doc/man/cargo-bench.md | 9 +++++---- src/doc/man/cargo-test.md | 15 +++++++++------ src/doc/man/generated_txt/cargo-bench.txt | 9 +++++---- src/doc/man/generated_txt/cargo-test.txt | 15 +++++++++------ src/doc/src/commands/cargo-bench.md | 9 +++++---- src/doc/src/commands/cargo-test.md | 15 +++++++++------ src/etc/man/cargo-bench.1 | 9 +++++---- src/etc/man/cargo-test.1 | 15 +++++++++------ 8 files changed, 56 insertions(+), 40 deletions(-) diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md index 05bba472c..8efa69396 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 `#[test]` 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` diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md index 6665f5563..cba8d2ebf 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,11 +27,14 @@ 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` diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt index 8ca39bca8..52935dbec 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 #[test] 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 diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt index c2606bbb8..ec6f435aa 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,11 +23,14 @@ 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 diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index 5fe7ebed3..51df36648 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 `#[test]` 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` diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 10c7d6ba1..3fb608681 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,11 +27,14 @@ 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` diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index f3cb0f8b3..ecc5f2e19 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#[test]\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 diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 6c5180194..8a5c0f34b 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,11 +27,14 @@ 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