Add some warnings/disclaimers about build-dependencies.

Also add `autocfg` to the list.

Author: ehuss

src/doc/src/reference/build-script-examples.md

@@ -5,18 +5,22 @@ The following sections illustrate some examples of writing build scripts.
 Some common build script functionality can be found via crates on [crates.io].
 Check out the [`build-dependencies`
 keyword](https://crates.io/keywords/build-dependencies) to see what is
-available. Some popular crates are:
+available. The following is a sample of some popular crates[^†]:
 
 * [`bindgen`](https://crates.io/crates/bindgen) — Automatically generate Rust
   FFI bindings to C libraries.
 * [`cc`](https://crates.io/crates/cc) — Compiles C/C++/assembly.
 * [`pkg-config`](https://crates.io/crates/pkg-config) — Detect system
   libraries using the `pkg-config` utility.
 * [`cmake`](https://crates.io/crates/cmake) — Runs the `cmake` build tool to build a native library.
-* [`rustc_version`](https://crates.io/crates/rustc_version),
+* [`autocfg`](https://crates.io/crates/autocfg),
+  [`rustc_version`](https://crates.io/crates/rustc_version),
   [`version_check`](https://crates.io/crates/version_check) — These crates
   provide ways to implement conditional compilation based on the current
-  version of `rustc`.
+  `rustc` such as the version of the compiler.
+
+[^†]: This list is not an endorsement. Evaluate your dependencies to see which
+is right for your project.
 
 ### Code generation
 

src/doc/src/reference/build-scripts.md

@@ -230,6 +230,12 @@ The build script **does not** have access to the dependencies listed in the
 build dependencies are not available to the package itself unless also
 explicitly added in the `[dependencies]` table.
 
+It is recommended to carefully consider each dependency you add, weighing
+against the impact on compile time, licensing, maintenance, etc. Cargo will
+attempt to reuse a dependency if it is shared between build dependencies and
+normal dependencies. However, this is not always possible, for example when
+cross-compiling, so keep that in consideration of the impact on compile time.
+
 ### Change Detection
 
 When rebuilding a package, Cargo does not necessarily know if the build script