Describe dep-info files a little better.

diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md
index 0c455b2ae539f3ee791208fe16f4ec48979c975b..f96721c410a41d2a88287d279d38c36f452296a8 100644 (file)
--- a/src/doc/src/guide/build-cache.md
+++ b/src/doc/src/guide/build-cache.md
@@ -49,6 +49,20 @@ Directory | Description
 <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
@@ -60,6 +74,7 @@ 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.
 
+[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir
 [`build.target-dir`]: ../reference/config.md#buildtarget-dir
 [`cargo doc`]: ../commands/cargo-doc.md
 [`cargo package`]: ../commands/cargo-package.md

diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index e580e9158b5981a64d07a72d98d650cb15f5a7b6..f2369c386194b66e3eb3dca911d80f8608f94ee8 100644 (file)
--- a/src/doc/src/reference/config.md
+++ b/src/doc/src/reference/config.md
@@ -348,14 +348,10 @@ overrides the config setting.
 * Default: none
 * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR`
 
-Strips the given path prefix from dep info file paths.
-
-Cargo saves a "dep info" file with a `.d` suffix which 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. This config setting can be set to strip the given prefix
-from all of the paths for tools that require relative paths.
+Strips the given path prefix from [dep
+info](../guide/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.
 
 The setting itself is a config-relative path. So, for example, a value of
 `"."` would strip all paths starting with the parent directory of the `.cargo`