Auto merge of #7565 - ehuss:expand-build-script-docs, r=alexcrichton

Expand documentation on build scripts.

This restructures and adds some more documentation for writing build scripts. An overview:

- Move examples to a separate chapter.
    - Add some links to common build dependencies.
    - Rewrote the example of linking to system libraries.
    - Rewrote some of the `links` and `-sys` examples.
    - Added a "conditional compilation" example.
- De-emphasize setting `build = "build.rs"`.
- Explain how build scripts run.
- Give each `cargo:` instruction a separate section with more detail.
- More detail on how `rerun-if` stuff works. Also, try to emphasize best practices, especially in examples.
- Try to clarify `links` and go into more detail.
- Document the jobserver.
- Expand on environment variables.
    - Document dylib search path behavior.

I have explicitly skipped trying to document rpath issues, as it seems to be a mess, and I can't really sort it out.

I'd be happy to have any feedback for things to add or change.

Closes #1251
Closes #2236
Closes #2888
Closes #3304
Closes #3968
Closes #5499
Closes #7338

Author: bors

src/doc/src/SUMMARY.md

@@ -24,6 +24,7 @@
     * [Configuration](reference/config.md)
     * [Environment Variables](reference/environment-variables.md)
     * [Build Scripts](reference/build-scripts.md)
+        * [Build Script Examples](reference/build-script-examples.md)
     * [Publishing on crates.io](reference/publishing.md)
     * [Package ID Specifications](reference/pkgid-spec.md)
     * [Source Replacement](reference/source-replacement.md)