docs: Move Cache topic from Guide to Reference

It doesn't "guide" people through a topic but explains in a more
top-down fashion what caches exist and is not particularly a common
topic people need to know.

src/doc/book.toml

@@ -7,3 +7,6 @@ smart-punctuation = true # Enable smart-punctuation feature for more than quotes
 git-repository-url = "https://github.com/rust-lang/cargo/tree/master/src/doc/src"
 edit-url-template = "https://github.com/rust-lang/cargo/edit/master/src/doc/{path}"
 search.use-boolean-and = true
+
+[output.html.redirect]
+"/guide/build-cache.html" = "../reference/build-cache.html"

src/doc/man/generated_txt/cargo-bench.txt

@@ -232,7 +232,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        --profile name

src/doc/man/generated_txt/cargo-build.txt

@@ -149,7 +149,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-check.txt

@@ -146,7 +146,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-clean.txt

@@ -57,7 +57,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
    Display Options

src/doc/man/generated_txt/cargo-doc.txt

@@ -124,7 +124,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-fetch.txt

@@ -37,7 +37,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
    Display Options

src/doc/man/generated_txt/cargo-fix.txt

@@ -219,7 +219,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-install.txt

@@ -197,7 +197,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        --target-dir directory

src/doc/man/generated_txt/cargo-package.txt

@@ -144,7 +144,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        --target-dir directory

src/doc/man/generated_txt/cargo-publish.txt

@@ -92,7 +92,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        --target-dir directory

src/doc/man/generated_txt/cargo-run.txt

@@ -72,7 +72,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-rustc.txt

@@ -140,7 +140,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-rustdoc.txt

@@ -140,7 +140,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/generated_txt/cargo-test.txt

@@ -254,7 +254,7 @@ OPTIONS
            Note that specifying this flag makes Cargo run in a different mode
            where the target artifacts are placed in a separate directory. See
            the build cache
-           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
+           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
            documentation for more details.
 
        -r, --release

src/doc/man/includes/options-target-triple.md

@@ -12,5 +12,5 @@ This may also be specified with the `build.target`
 
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-[build cache](../guide/build-cache.html) documentation for more details.
+[build cache](../reference/build-cache.html) documentation for more details.
 {{/option}}

src/doc/src/SUMMARY.md

@@ -17,7 +17,6 @@
     * [Continuous Integration](guide/continuous-integration.md)
     * [Publishing on crates.io](reference/publishing.md)
     * [Cargo Home](guide/cargo-home.md)
-    * [Build Cache](guide/build-cache.md)
 
 * [Cargo Reference](reference/index.md)
     * [Specifying Dependencies](reference/specifying-dependencies.md)
@@ -32,6 +31,7 @@
     * [Environment Variables](reference/environment-variables.md)
     * [Build Scripts](reference/build-scripts.md)
         * [Build Script Examples](reference/build-script-examples.md)
+    * [Build Cache](reference/build-cache.md)
     * [Package ID Specifications](reference/pkgid-spec.md)
     * [Source Replacement](reference/source-replacement.md)
     * [External Tools](reference/external-tools.md)

src/doc/src/commands/cargo-bench.md

@@ -263,7 +263,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-bench---profile"><a class="option-anchor" href="#option-cargo-bench---profile"></a><code>--profile</code> <em>name</em></dt>

src/doc/src/commands/cargo-build.md

@@ -178,7 +178,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-build--r"><a class="option-anchor" href="#option-cargo-build--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-check.md

@@ -174,7 +174,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-check--r"><a class="option-anchor" href="#option-cargo-check--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-clean.md

@@ -66,7 +66,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 </dl>

src/doc/src/commands/cargo-doc.md

@@ -153,7 +153,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-doc--r"><a class="option-anchor" href="#option-cargo-doc--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-fetch.md

@@ -36,7 +36,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 </dl>
 

src/doc/src/commands/cargo-fix.md

@@ -254,7 +254,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-fix--r"><a class="option-anchor" href="#option-cargo-fix--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-install.md

@@ -219,7 +219,7 @@ list of supported targets.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-install---target-dir"><a class="option-anchor" href="#option-cargo-install---target-dir"></a><code>--target-dir</code> <em>directory</em></dt>

src/doc/src/commands/cargo-package.md

@@ -155,7 +155,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-package---target-dir"><a class="option-anchor" href="#option-cargo-package---target-dir"></a><code>--target-dir</code> <em>directory</em></dt>

src/doc/src/commands/cargo-publish.md

@@ -102,7 +102,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-publish---target-dir"><a class="option-anchor" href="#option-cargo-publish---target-dir"></a><code>--target-dir</code> <em>directory</em></dt>

src/doc/src/commands/cargo-run.md

@@ -95,7 +95,7 @@ list of supported targets.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-run--r"><a class="option-anchor" href="#option-cargo-run--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-rustc.md

@@ -167,7 +167,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-rustc--r"><a class="option-anchor" href="#option-cargo-rustc--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-rustdoc.md

@@ -173,7 +173,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-rustdoc--r"><a class="option-anchor" href="#option-cargo-rustdoc--r"></a><code>-r</code></dt>

src/doc/src/commands/cargo-test.md

@@ -285,7 +285,7 @@ list of supported targets. This flag may be specified multiple times.</p>
 <a href="../reference/config.html">config value</a>.</p>
 <p>Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-<a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd>
+<a href="../reference/build-cache.html">build cache</a> documentation for more details.</dd>
 
 
 <dt class="option-term" id="option-cargo-test--r"><a class="option-anchor" href="#option-cargo-test--r"></a><code>-r</code></dt>

src/doc/src/guide/build-cache.md

@@ -1,108 +1 @@
-# Build cache
+# Build Cache
-
-Cargo stores the output of a build into the "target" directory. By default,
-this is the directory named `target` in the root of your
-[*workspace*][def-workspace]. To change the location, you can set the
-`CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config
-value, or the `--target-dir` command-line flag.
-
-The directory layout depends on whether or not you are using the `--target`
-flag to build for a specific platform. If `--target` is not specified, Cargo
-runs in a mode where it builds for the host architecture. The output goes into
-the root of the target directory, with each [profile] stored in a separate
-subdirectory:
-
-Directory | Description
-----------|------------
-<code style="white-space: nowrap">target/debug/</code> | Contains output for the `dev` profile.
-<code style="white-space: nowrap">target/release/</code> | Contains output for the `release` profile (with the `--release` option).
-<code style="white-space: nowrap">target/foo/</code> | Contains build output for the `foo` profile (with the `--profile=foo` option).
-
-For historical reasons, the `dev` and `test` profiles are stored in the
-`debug` directory, and the `release` and `bench` profiles are stored in the
-`release` directory. User-defined profiles are stored in a directory with the
-same name as the profile.
-
-When building for another target with `--target`, the output is placed in a
-directory with the name of the [target]:
-
-Directory | Example
-----------|--------
-<code style="white-space: nowrap">target/&lt;triple&gt;/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code>
-<code style="white-space: nowrap">target/&lt;triple&gt;/release/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/release/</code>
-
-> **Note**: When not using `--target`, this has a consequence that Cargo will
-> share your dependencies with build scripts and proc macros. [`RUSTFLAGS`]
-> will be shared with every `rustc` invocation. With the `--target` flag,
-> build scripts and proc macros are built separately (for the host
-> architecture), and do not share `RUSTFLAGS`.
-
-Within the profile directory (such as `debug` or `release`), artifacts are
-placed into the following directories:
-
-Directory | Description
-----------|------------
-<code style="white-space: nowrap">target/debug/</code> | Contains the output of the package being built (the [binary executables] and [library targets]).
-<code style="white-space: nowrap">target/debug/examples/</code> | Contains [example targets].
-
-Some commands place their output in dedicated directories in the top level of
-the `target` directory:
-
-Directory | Description
-----------|------------
-<code style="white-space: nowrap">target/doc/</code> | Contains rustdoc documentation ([`cargo doc`]).
-<code style="white-space: nowrap">target/package/</code> | Contains the output of the [`cargo package`] and [`cargo publish`] commands.
-
-Cargo also creates several other directories and files needed for the build
-process. Their layout is considered internal to Cargo, and is subject to
-change. Some of these directories are:
-
-Directory | Description
-----------|------------
-<code style="white-space: nowrap">target/debug/deps/</code> | Dependencies and other artifacts.
-<code style="white-space: nowrap">target/debug/incremental/</code> | `rustc` [incremental output], a cache used to speed up subsequent builds.
-<code style="white-space: nowrap">target/debug/build/</code> | Output from [build scripts].
-
-## Dep-info files
-
-Next to each compiled artifact is a file called a "dep info" file with a `.d`
-suffix. This file is a Makefile-like syntax that indicates all of the file
-dependencies required to rebuild the artifact. These are intended to be used
-with external build systems so that they can detect if Cargo needs to be
-re-executed. The paths in the file are absolute by default. See the
-[`build.dep-info-basedir`] config option to use relative paths.
-
-```Makefile
-# Example dep-info file found in target/debug/foo.d
-/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs
-```
-
-## Shared cache
-
-A third party tool, [sccache], can be used to share built dependencies across
-different workspaces.
-
-To setup `sccache`, install it with `cargo install sccache` and set
-`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If
-you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to
-`.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo
-configuration][config]. Refer to sccache documentation for more details.
-
-[`RUSTFLAGS`]: ../reference/config.md#buildrustflags
-[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir
-[`build.rustc-wrapper`]: ../reference/config.md#buildrustc-wrapper
-[`build.target-dir`]: ../reference/config.md#buildtarget-dir
-[`cargo doc`]: ../commands/cargo-doc.md
-[`cargo package`]: ../commands/cargo-package.md
-[`cargo publish`]: ../commands/cargo-publish.md
-[build scripts]: ../reference/build-scripts.md
-[config]: ../reference/config.md
-[def-workspace]:  ../appendix/glossary.md#workspace  '"workspace" (glossary entry)'
-[target]: ../appendix/glossary.md#target '"target" (glossary entry)'
-[environment variable]: ../reference/environment-variables.md
-[incremental output]: ../reference/profiles.md#incremental
-[sccache]: https://github.com/mozilla/sccache
-[profile]: ../reference/profiles.md
-[binary executables]: ../reference/cargo-targets.md#binaries
-[library targets]: ../reference/cargo-targets.md#library
-[example targets]: ../reference/cargo-targets.md#examples

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

@@ -0,0 +1,108 @@
+# Build cache
+
+Cargo stores the output of a build into the "target" directory. By default,
+this is the directory named `target` in the root of your
+[*workspace*][def-workspace]. To change the location, you can set the
+`CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config
+value, or the `--target-dir` command-line flag.
+
+The directory layout depends on whether or not you are using the `--target`
+flag to build for a specific platform. If `--target` is not specified, Cargo
+runs in a mode where it builds for the host architecture. The output goes into
+the root of the target directory, with each [profile] stored in a separate
+subdirectory:
+
+Directory | Description
+----------|------------
+<code style="white-space: nowrap">target/debug/</code> | Contains output for the `dev` profile.
+<code style="white-space: nowrap">target/release/</code> | Contains output for the `release` profile (with the `--release` option).
+<code style="white-space: nowrap">target/foo/</code> | Contains build output for the `foo` profile (with the `--profile=foo` option).
+
+For historical reasons, the `dev` and `test` profiles are stored in the
+`debug` directory, and the `release` and `bench` profiles are stored in the
+`release` directory. User-defined profiles are stored in a directory with the
+same name as the profile.
+
+When building for another target with `--target`, the output is placed in a
+directory with the name of the [target]:
+
+Directory | Example
+----------|--------
+<code style="white-space: nowrap">target/&lt;triple&gt;/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code>
+<code style="white-space: nowrap">target/&lt;triple&gt;/release/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/release/</code>
+
+> **Note**: When not using `--target`, this has a consequence that Cargo will
+> share your dependencies with build scripts and proc macros. [`RUSTFLAGS`]
+> will be shared with every `rustc` invocation. With the `--target` flag,
+> build scripts and proc macros are built separately (for the host
+> architecture), and do not share `RUSTFLAGS`.
+
+Within the profile directory (such as `debug` or `release`), artifacts are
+placed into the following directories:
+
+Directory | Description
+----------|------------
+<code style="white-space: nowrap">target/debug/</code> | Contains the output of the package being built (the [binary executables] and [library targets]).
+<code style="white-space: nowrap">target/debug/examples/</code> | Contains [example targets].
+
+Some commands place their output in dedicated directories in the top level of
+the `target` directory:
+
+Directory | Description
+----------|------------
+<code style="white-space: nowrap">target/doc/</code> | Contains rustdoc documentation ([`cargo doc`]).
+<code style="white-space: nowrap">target/package/</code> | Contains the output of the [`cargo package`] and [`cargo publish`] commands.
+
+Cargo also creates several other directories and files needed for the build
+process. Their layout is considered internal to Cargo, and is subject to
+change. Some of these directories are:
+
+Directory | Description
+----------|------------
+<code style="white-space: nowrap">target/debug/deps/</code> | Dependencies and other artifacts.
+<code style="white-space: nowrap">target/debug/incremental/</code> | `rustc` [incremental output], a cache used to speed up subsequent builds.
+<code style="white-space: nowrap">target/debug/build/</code> | Output from [build scripts].
+
+## Dep-info files
+
+Next to each compiled artifact is a file called a "dep info" file with a `.d`
+suffix. This file is a Makefile-like syntax that indicates all of the file
+dependencies required to rebuild the artifact. These are intended to be used
+with external build systems so that they can detect if Cargo needs to be
+re-executed. The paths in the file are absolute by default. See the
+[`build.dep-info-basedir`] config option to use relative paths.
+
+```Makefile
+# Example dep-info file found in target/debug/foo.d
+/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs
+```
+
+## Shared cache
+
+A third party tool, [sccache], can be used to share built dependencies across
+different workspaces.
+
+To setup `sccache`, install it with `cargo install sccache` and set
+`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If
+you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to
+`.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo
+configuration][config]. Refer to sccache documentation for more details.
+
+[`RUSTFLAGS`]: ../reference/config.md#buildrustflags
+[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir
+[`build.rustc-wrapper`]: ../reference/config.md#buildrustc-wrapper
+[`build.target-dir`]: ../reference/config.md#buildtarget-dir
+[`cargo doc`]: ../commands/cargo-doc.md
+[`cargo package`]: ../commands/cargo-package.md
+[`cargo publish`]: ../commands/cargo-publish.md
+[build scripts]: ../reference/build-scripts.md
+[config]: ../reference/config.md
+[def-workspace]:  ../appendix/glossary.md#workspace  '"workspace" (glossary entry)'
+[target]: ../appendix/glossary.md#target '"target" (glossary entry)'
+[environment variable]: ../reference/environment-variables.md
+[incremental output]: ../reference/profiles.md#incremental
+[sccache]: https://github.com/mozilla/sccache
+[profile]: ../reference/profiles.md
+[binary executables]: ../reference/cargo-targets.md#binaries
+[library targets]: ../reference/cargo-targets.md#library
+[example targets]: ../reference/cargo-targets.md#examples

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

@@ -368,7 +368,7 @@ autobins = false
 
 > **MSRV:** Respected as of 1.83 for `autolib`
 
-[Build cache]: ../guide/build-cache.md
+[Build cache]: build-cache.md
 [Rust Edition]: ../../edition-guide/index.html
 [`--test` flag]: ../../rustc/command-line-arguments.html#option-test
 [`cargo bench`]: ../commands/cargo-bench.md

src/doc/src/reference/config.md

@@ -554,7 +554,7 @@ overrides the config setting.
 * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR`
 
 Strips the given path prefix from [dep
-info](../guide/build-cache.md#dep-info-files) file paths. This config setting
+info](../reference/build-cache.md#dep-info-files) file paths. This config setting
 is intended to convert absolute paths to relative paths for tools that require
 relative paths.
 

src/doc/src/reference/profiles.md

@@ -371,7 +371,7 @@ The output for each profile will be placed in a directory of the same name
 as the profile in the [`target` directory]. As in the example above, the
 output would go into the `target/release-lto` directory.
 
-[`target` directory]: ../guide/build-cache.md
+[`target` directory]: build-cache.md
 
 ## Profile selection
 

src/doc/src/reference/workspaces.md

@@ -290,7 +290,7 @@ if that makes sense for the tool in question.
 [`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md
 [package-metadata]: manifest.md#the-metadata-table
 [package-edition]: manifest.md#the-edition-field
-[output directory]: ../guide/build-cache.md
+[output directory]: build-cache.md
 [patch]: overriding-dependencies.md#the-patch-section
 [replace]: overriding-dependencies.md#the-replace-section
 [profiles]: profiles.md

src/etc/man/cargo-bench.1

@@ -276,7 +276,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-\-profile\fR \fIname\fR

src/etc/man/cargo-build.1

@@ -175,7 +175,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-check.1

@@ -171,7 +171,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-clean.1

@@ -66,7 +66,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .SS "Display Options"
 .sp

src/etc/man/cargo-doc.1

@@ -144,7 +144,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-fetch.1

@@ -34,7 +34,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .SS "Display Options"
 .sp

src/etc/man/cargo-fix.1

@@ -266,7 +266,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-install.1

@@ -251,7 +251,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-\-target\-dir\fR \fIdirectory\fR

src/etc/man/cargo-package.1

@@ -179,7 +179,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-\-target\-dir\fR \fIdirectory\fR

src/etc/man/cargo-publish.1

@@ -111,7 +111,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-\-target\-dir\fR \fIdirectory\fR

src/etc/man/cargo-run.1

@@ -81,7 +81,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-rustc.1

@@ -161,7 +161,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-rustdoc.1

@@ -163,7 +163,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR, 

src/etc/man/cargo-test.1

@@ -296,7 +296,7 @@ This may also be specified with the \fBbuild.target\fR
 .sp
 Note that specifying this flag makes Cargo run in a different mode where the
 target artifacts are placed in a separate directory. See the
-\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details.
+\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/reference/build\-cache.html> documentation for more details.
 .RE
 .sp
 \fB\-r\fR,