RUSTC_WORKSPACE_WRAPPER: clarify docs

src/doc/src/reference/config.md

@@ -415,10 +415,14 @@ wrapper is the path to the actual executable to use
 * Default: none
 * Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER`
 
-Sets a wrapper to execute instead of `rustc`, for workspace members only.
-The first argument passed to the wrapper is the path to the actual
-executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
-It affects the filename hash so that artifacts produced by the wrapper are cached separately.
+Sets a wrapper to execute instead of `rustc`, for workspace members only. When building a
+single-package project without workspaces, that package is considered to be the workspace. The first
+argument passed to the wrapper is the path to the actual executable to use (i.e., `build.rustc`, if
+that is set, or `"rustc"` otherwise). It affects the filename hash so that artifacts produced by the
+wrapper are cached separately.
+
+If both `rustc-wrapper` and `rustc-workspace-wrapper` are set, then they will be nested:
+the final invocation is `$RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC`.
 
 #### `build.rustdoc`
 * Type: string (program path)

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

@@ -37,13 +37,15 @@ system:
   Useful to set up a build cache tool such as `sccache`. See
   [`build.rustc-wrapper`] to set via config. Setting this to the empty string
   overwrites the config and resets cargo to not use a wrapper.
-* `RUSTC_WORKSPACE_WRAPPER` --- Instead of simply running `rustc`, for workspace
-  members Cargo will execute this specified wrapper, passing
-  as its command-line arguments the rustc invocation, with the first argument
-  being the path to the actual rustc. It affects the filename hash
-  so that artifacts produced by the wrapper are cached separately.
-  See [`build.rustc-workspace-wrapper`] to set via config. Setting this to the empty string
-  overwrites the config and resets cargo to not use a wrapper for workspace members.
+* `RUSTC_WORKSPACE_WRAPPER` --- Instead of simply running `rustc`, for workspace members Cargo will
+  execute this specified wrapper, passing as its command-line arguments the rustc invocation, with
+  the first argument being the path to the actual rustc. When building a single-package project
+  without workspaces, that package is considered to be the workspace. It affects the filename hash
+  so that artifacts produced by the wrapper are cached separately. See
+  [`build.rustc-workspace-wrapper`] to set via config. Setting this to the empty string overwrites
+  the config and resets cargo to not use a wrapper for workspace members. If both `RUSTC_WRAPPER`
+  and `RUSTC_WORKSPACE_WRAPPER` are set, then they will be nested: the final invocation is
+  `$RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC`.
 * `RUSTDOC` --- Instead of running `rustdoc`, Cargo will execute this specified
   `rustdoc` instance instead. See [`build.rustdoc`] to set via config.
 * `RUSTDOCFLAGS` --- A space-separated list of custom flags to pass to all `rustdoc`

tests/testsuite/build.rs

@@ -5210,6 +5210,27 @@ fn rustc_wrapper() {
         .run();
 }
 
+/// Checks what happens when both rust-wrapper and rustc-workspace-wrapper are set.
+#[cargo_test]
+fn rustc_wrapper_precendence() {
+    let p = project().file("src/lib.rs", "").build();
+    let rustc_wrapper = tools::echo_wrapper();
+    let ws_wrapper = rustc_wrapper.with_file_name("rustc-ws-wrapper");
+    assert_ne!(rustc_wrapper, ws_wrapper);
+    std::fs::hard_link(&rustc_wrapper, &ws_wrapper).unwrap();
+
+    let running = format!(
+        "[RUNNING] `{} {} rustc --crate-name foo [..]",
+        rustc_wrapper.display(),
+        ws_wrapper.display(),
+    );
+    p.cargo("build -v")
+        .env("RUSTC_WRAPPER", &rustc_wrapper)
+        .env("RUSTC_WORKSPACE_WRAPPER", &ws_wrapper)
+        .with_stderr_contains(running)
+        .run();
+}
+
 #[cargo_test]
 fn rustc_wrapper_relative() {
     Package::new("bar", "1.0.0").publish();