Skip to content

expand RUSTC_WRAPPER docs #10896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 24, 2022
Merged

expand RUSTC_WRAPPER docs #10896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions src/doc/src/reference/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,15 +361,17 @@ Sets the executable to use for `rustc`.
* Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER`

Sets a wrapper to execute instead of `rustc`. The first argument passed to the
wrapper is the path to the actual `rustc`.
wrapper is the path to the actual executable to use
(i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).

##### `build.rustc-workspace-wrapper`
* Type: string (program path)
* 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 `rustc`.
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.

##### `build.rustdoc`
Expand Down
19 changes: 11 additions & 8 deletions src/doc/src/reference/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,18 @@ system:
* `RUSTC` — Instead of running `rustc`, Cargo will execute this specified
compiler instead. See [`build.rustc`] to set via config.
* `RUSTC_WRAPPER` — Instead of simply running `rustc`, Cargo will execute this
specified wrapper instead, passing as its command-line arguments the rustc
invocation, with the first argument being `rustc`. Useful to set up a build
cache tool such as `sccache`. See [`build.rustc-wrapper`] to set via config.
* `RUSTC_WORKSPACE_WRAPPER` — Instead of simply running `rustc`, Cargo will
execute this specified wrapper instead for workspace members only, passing
specified wrapper, passing as its command-line arguments the rustc
invocation, with the first argument being the path to the actual rustc.
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.
Comment on lines +27 to +28
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Workspace wrapper can also be reset with the same trick. However, this seems to be an undocumented behaviour, attributed to these lines.

IMHO, if users start to rely on an undocumented but reasonable behaivour, we should treat it as a feature and document it well, like what you just did.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like the reset is reasonable to document. Could you mention it for rustc-workspace-wrapper as well?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh. If this is going to be documented, adding some tests to prevent regression would be better. Sorry for the reply bombing.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you mention it for rustc-workspace-wrapper as well?

Done.

However I won't have the time to add tests, sorry.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this is what you were referring to, but I opened #10899 to update the test to make this behavior explicitly tested.

* `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 `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.
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.
* `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`
Expand Down