Document rustc wrapper

src/cargo/util/config/mod.rs

@@ -873,9 +873,17 @@ impl Config {
             return Ok(Some(path));
         }
 
-        let var = format!("build.{}", tool);
-        if let Some(tool_path) = self.get_path(&var)? {
-            return Ok(Some(tool_path.val));
+        // For backwards compatibility we allow both snake_case config paths as well as the
+        // idiomatic kebab-case paths.
+        let config_paths = [
+            format!("build.{}", tool),
+            format!("build.{}", tool.replace('_', "-")),
+        ];
+
+        for config_path in &config_paths {
+            if let Some(tool_path) = self.get_path(&config_path)? {
+                return Ok(Some(tool_path.val));
+            }
         }
 
         Ok(None)

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

@@ -7,8 +7,9 @@ a similar result can be achieved by using a third party tool, [sccache].
 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`. Refer to sccache documentation for more details.
+`.bashrc`. Alternatively, you can set `build.rustc-wrapper` in the
+ [Cargo configuration][config]. Refer to sccache documentation for more
+ details.
 
 [sccache]: https://github.com/mozilla/sccache
-
-
+[config]: ../reference/config.md

src/doc/src/reference/config.md

@@ -130,6 +130,8 @@ debug = false
 [build]
 jobs = 1                  # number of parallel jobs, defaults to # of CPUs
 rustc = "rustc"           # the rust compiler tool
+rustc-wrapper = ".."      # run this wrapper instead of `rustc`; useful to set up a
+                          # build cache tool such as `sccache`
 rustdoc = "rustdoc"       # the doc generator tool
 target = "triple"         # build for the target triple (ignored by `cargo install`)
 target-dir = "target"     # path of where to place all generated artifacts

src/doc/src/reference/environment-variables.md

@@ -20,7 +20,8 @@ system:
   compiler instead.
 * `RUSTC_WRAPPER` — Instead of simply running `rustc`, Cargo will execute this
   specified wrapper instead, passing as its commandline arguments the rustc
-  invocation, with the first argument being rustc.
+  invocation, with the first argument being `rustc`. Useful to set up a build
+  cache tool such as `sccache`.
 * `RUSTDOC` — Instead of running `rustdoc`, Cargo will execute this specified
   `rustdoc` instance instead.
 * `RUSTDOCFLAGS` — A space-separated list of custom flags to pass to all `rustdoc`