Skip to content

Commit acd673b

Browse files
committed
Auto merge of #13648 - RalfJung:RUSTC_WORKSPACE_WRAPPER, r=weihanglo
RUSTC_WORKSPACE_WRAPPER: clarify docs Follow-up to [Zulip discussion](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Question.20about.20RUSTC_WORKSPACE_WRAPPER)
2 parents 07253b7 + 27a4741 commit acd673b

File tree

3 files changed

+38
-11
lines changed

3 files changed

+38
-11
lines changed

src/doc/src/reference/config.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -415,10 +415,14 @@ wrapper is the path to the actual executable to use
415415
* Default: none
416416
* Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER`
417417

418-
Sets a wrapper to execute instead of `rustc`, for workspace members only.
419-
The first argument passed to the wrapper is the path to the actual
420-
executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
421-
It affects the filename hash so that artifacts produced by the wrapper are cached separately.
418+
Sets a wrapper to execute instead of `rustc`, for workspace members only. When building a
419+
single-package project without workspaces, that package is considered to be the workspace. The first
420+
argument passed to the wrapper is the path to the actual executable to use (i.e., `build.rustc`, if
421+
that is set, or `"rustc"` otherwise). It affects the filename hash so that artifacts produced by the
422+
wrapper are cached separately.
423+
424+
If both `rustc-wrapper` and `rustc-workspace-wrapper` are set, then they will be nested:
425+
the final invocation is `$RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC`.
422426

423427
#### `build.rustdoc`
424428
* Type: string (program path)

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

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

tests/testsuite/build.rs

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5210,6 +5210,27 @@ fn rustc_wrapper() {
52105210
.run();
52115211
}
52125212

5213+
/// Checks what happens when both rust-wrapper and rustc-workspace-wrapper are set.
5214+
#[cargo_test]
5215+
fn rustc_wrapper_precendence() {
5216+
let p = project().file("src/lib.rs", "").build();
5217+
let rustc_wrapper = tools::echo_wrapper();
5218+
let ws_wrapper = rustc_wrapper.with_file_name("rustc-ws-wrapper");
5219+
assert_ne!(rustc_wrapper, ws_wrapper);
5220+
std::fs::hard_link(&rustc_wrapper, &ws_wrapper).unwrap();
5221+
5222+
let running = format!(
5223+
"[RUNNING] `{} {} rustc --crate-name foo [..]",
5224+
rustc_wrapper.display(),
5225+
ws_wrapper.display(),
5226+
);
5227+
p.cargo("build -v")
5228+
.env("RUSTC_WRAPPER", &rustc_wrapper)
5229+
.env("RUSTC_WORKSPACE_WRAPPER", &ws_wrapper)
5230+
.with_stderr_contains(running)
5231+
.run();
5232+
}
5233+
52135234
#[cargo_test]
52145235
fn rustc_wrapper_relative() {
52155236
Package::new("bar", "1.0.0").publish();

0 commit comments

Comments
 (0)