Add info about `build-dependencies` to the specifying deps page

diff --git a/src/doc/specifying-dependencies.md b/src/doc/specifying-dependencies.md
index ac121c7141f5983f74a338af44543c6eddbf2a9e..0177e361d36aaaf4ba70ea8ab5c71b7f60adfcc4 100644 (file)
--- a/src/doc/specifying-dependencies.md
+++ b/src/doc/specifying-dependencies.md
@@ -310,3 +310,19 @@ mio = "0.0.1"
 ```
 
 [crates.io]: https://crates.io/
+
+# Build dependencies
+
+You can depend on other Cargo-based crates for use in your build scripts.
+Dependencies are declared through the `build-dependencies` section of the
+manifest:
+
+```toml
+[build-dependencies]
+gcc = "0.3"
+```
+
+The build script **does not** have access to the dependencies listed in the
+`dependencies` or `dev-dependencies` section (they’re not built yet!). All build
+dependencies will also not be available to the package itself unless listed
+under the `dependencies` section as well.