Add more docs on CARGO_BIN_EXE_.

Author: ehuss

src/doc/man/cargo-test.adoc

@@ -74,6 +74,14 @@ 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_<name>`
+linkcargo:reference/environment-variables.html#environment-variables-cargo-sets-for-crates[environment variable]
+is set when the integration test is built so that it can use the
+link:https://doc.rust-lang.org/std/macro.env.html[`env` macro] to locate the
+executable.
+
 include::options-targets.adoc[]
 
 *--doc*::

src/doc/man/generated/cargo-test.html

@@ -154,6 +154,15 @@ <h3 id="cargo_test_target_selection">Target Selection</h3>
 library in the manifest.</p>
 </div>
 <div class="paragraph">
+<p>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 <code>CARGO_BIN_EXE_&lt;name&gt;</code>
+<a href="../reference/environment-variables.html#environment-variables-cargo-sets-for-crates">environment variable</a>
+is set when the integration test is built so that it can use the
+<a href="https://doc.rust-lang.org/std/macro.env.html"><code>env</code> macro</a> to locate the
+executable.</p>
+</div>
+<div class="paragraph">
 <p>Passing target selection flags will test only the
 specified targets.</p>
 </div>

src/doc/src/reference/cargo-targets.md

@@ -123,6 +123,15 @@ modules. The libtest harness will automatically find all of the `#[test]`
 annotated functions and run them in parallel. You can pass module names to
 [`cargo test`] to only run the tests within that module.
 
+Binary targets are automatically built if there is an integration test. This
+allows an integration test to execute the binary to exercise and test its
+behavior. The `CARGO_BIN_EXE_<name>` [environment variable] is set when the
+integration test is built so that it can use the [`env` macro] to locate the
+executable.
+
+[environment variable]: environment-variables.md#environment-variables-cargo-sets-for-crates
+[`env` macro]: ../../std/macro.env.html
+
 ### Benchmarks
 
 Benchmarks provide a way to test the performance of your code using the

src/doc/src/reference/environment-variables.md

@@ -195,7 +195,7 @@ let version = env!("CARGO_PKG_VERSION");
   Binaries are automatically built when the test is built, unless the binary
   has required features that are not enabled.
 
-[integration test]: manifest.md#integration-tests
+[integration test]: cargo-targets.md#integration-tests
 [`env` macro]: ../../std/macro.env.html
 
 #### Dynamic library paths

src/etc/man/cargo-test.1

@@ -2,12 +2,12 @@
 .\"     Title: cargo-test
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 2.0.10
-.\"      Date: 2020-01-18
+.\"      Date: 2020-02-06
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "CARGO\-TEST" "1" "2020-01-18" "\ \&" "\ \&"
+.TH "CARGO\-TEST" "1" "2020-02-06" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -206,6 +206,16 @@ ignore the \fBtest\fP flag and will always test the given target.
 Doc tests for libraries may be disabled by setting \fBdoctest = false\fP 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_<name>\fP
+\c
+.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates" "environment variable"
+is set when the integration test is built so that it can use the
+.URL "https://doc.rust\-lang.org/std/macro.env.html" "\fBenv\fP macro" " "
+to locate the
+executable.
+.sp
 Passing target selection flags will test only the
 specified targets.
 .sp