Skip to content
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

Jump to bottom

Improve CARGO_ENCODED_RUSTFLAGS and CARGO_ENCODED_RUSTDOCFLAGS variables docs #10633

Merged
merged 1 commit into from
May 5, 2022
Merged

Improve CARGO_ENCODED_RUSTFLAGS and CARGO_ENCODED_RUSTDOCFLAGS variables docs #10633

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
16 changes: 9 additions & 7 deletions src/doc/src/reference/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -363,18 +363,19 @@ Can be overridden with the `--target-dir` CLI option.
##### `build.rustflags`
* Type: string or array of strings
* Default: none
* Environment: `CARGO_BUILD_RUSTFLAGS` or `RUSTFLAGS`
* Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS`

Extra command-line flags to pass to `rustc`. The value may be a array of
strings or a space-separated string.

There are three mutually exclusive sources of extra flags. They are checked in
Copy link
Member

Choose a reason for hiding this comment

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

three mutually exclusive sources

This should probably say "four" now?

Copy link
Member Author

Choose a reason for hiding this comment

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

Good catch! Thanks!
#10657

order, with the first one being used:

1. `RUSTFLAGS` environment variable.
2. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags`
1. `CARGO_ENCODED_RUSTFLAGS` environment variable.
2. `RUSTFLAGS` environment variable.
3. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags`
config entries joined together.
3. `build.rustflags` config value.
4. `build.rustflags` config value.

Additional flags may also be passed with the [`cargo rustc`] command.

Expand All @@ -399,16 +400,17 @@ appropriate profile setting.
##### `build.rustdocflags`
* Type: string or array of strings
* Default: none
* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `RUSTDOCFLAGS`
* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS`

Extra command-line flags to pass to `rustdoc`. The value may be a array of
strings or a space-separated string.

There are two mutually exclusive sources of extra flags. They are checked in
order, with the first one being used:

1. `RUSTDOCFLAGS` environment variable.
2. `build.rustdocflags` config value.
1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable.
2. `RUSTDOCFLAGS` environment variable.
3. `build.rustdocflags` config value.

Additional flags may also be passed with the [`cargo rustdoc`] command.

Expand Down
14 changes: 8 additions & 6 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 @@ -36,16 +36,18 @@ system:
invocations that Cargo performs. In contrast with [`cargo rustdoc`], this is
useful for passing a flag to *all* `rustdoc` instances. See
[`build.rustdocflags`] for some more ways to set flags. This string is
split by whitespace; for a more robust encoding of multiple arguments,
set `CARGO_ENCODED_RUSTDOCFLAGS` instead with arguments separated by
`0x1f` (ASCII Unit Separator).
split by whitespace; for a more robust encoding of multiple arguments,
see `CARGO_ENCODED_RUSTDOCFLAGS`.
* `CARGO_ENCODED_RUSTDOCFLAGS` - A list of custom flags separated by `0x1f`
(ASCII Unit Separator) to pass to all `rustdoc` invocations that Cargo performs.
Comment on lines 36 to +42
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 mixed on the fact that the old variables have some context not documented in the new variables but this is enough of an improvement I don't think its worth blocking this for the discussion and any updates.

* `RUSTFLAGS` — A space-separated list of custom flags to pass to all compiler
invocations that Cargo performs. In contrast with [`cargo rustc`], this is
useful for passing a flag to *all* compiler instances. See
[`build.rustflags`] for some more ways to set flags. This string is
split by whitespace; for a more robust encoding of multiple arguments,
set `CARGO_ENCODED_RUSTFLAGS` instead with arguments separated by
`0x1f` (ASCII Unit Separator).
split by whitespace; for a more robust encoding of multiple arguments,
see `CARGO_ENCODED_RUSTFLAGS`.
* `CARGO_ENCODED_RUSTFLAGS` - A list of custom flags separated by `0x1f`
(ASCII Unit Separator) to pass to all compiler invocations that Cargo performs.
* `CARGO_INCREMENTAL` — If this is set to 1 then Cargo will force [incremental
compilation] to be enabled for the current compilation, and when set to 0 it
will force disabling it. If this env var isn't present then cargo's defaults
Expand Down