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

docs: add missing CARGO_MAKEFLAGS env for plugins #13872

Merged
merged 2 commits into from
May 7, 2024
Merged

docs: add missing CARGO_MAKEFLAGS env for plugins #13872

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80fcd72
docs: remove unnecessary indentations for each env var
weihanglo May 6, 2024
6dc080f
docs: add missing `CARGO_MAKEFLAGS` env for plugins
weihanglo May 6, 2024
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
81 changes: 36 additions & 45 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 @@ -246,9 +246,9 @@ corresponding environment variable is set to the empty string, `""`.
* `CARGO_BIN_NAME` --- The name of the binary that is currently being compiled.
Only set for [binaries] or binary [examples]. This name does not include any
file extension, such as `.exe`.
* `OUT_DIR` --- If the package has a build script, this is set to the folder where the build
script should place its output. See below for more information.
(Only set during compilation.)
* `OUT_DIR` --- If the package has a build script, this is set to the folder
where the build script should place its output. See below for more information.
(Only set during compilation.)
* `CARGO_BIN_EXE_<name>` --- The absolute path to a binary target's executable.
This is only set when building an [integration test] or benchmark. This may
be used with the [`env` macro] to find the executable to run for testing
Expand Down Expand Up @@ -318,24 +318,19 @@ let out_dir = env::var("OUT_DIR").unwrap();

* `CARGO` --- Path to the `cargo` binary performing the build.
* `CARGO_MANIFEST_DIR` --- The directory containing the manifest for the package
being built (the package containing the build
script). Also note that this is the value of the
current working directory of the build script when it
starts.
being built (the package containing the build script). Also note that this is
the value of the current working directory of the build script when it starts.
* `CARGO_MANIFEST_LINKS` --- the manifest `links` value.
* `CARGO_MAKEFLAGS` --- Contains parameters needed for Cargo's [jobserver]
implementation to parallelize subprocesses.
Rustc or cargo invocations from build.rs can already
read `CARGO_MAKEFLAGS`, but GNU Make requires the
flags to be specified either directly as arguments,
or through the `MAKEFLAGS` environment variable.
Currently Cargo doesn't set the `MAKEFLAGS` variable,
but it's free for build scripts invoking GNU Make
to set it to the contents of `CARGO_MAKEFLAGS`.
* `CARGO_FEATURE_<name>` --- For each activated feature of the package being
built, this environment variable will be present
where `<name>` is the name of the feature uppercased
and having `-` translated to `_`.
implementation to parallelize subprocesses. Rustc or cargo invocations from
build.rs can already read `CARGO_MAKEFLAGS`, but GNU Make requires the flags
to be specified either directly as arguments, or through the `MAKEFLAGS`
environment variable. Currently Cargo doesn't set the `MAKEFLAGS` variable,
but it's free for build scripts invoking GNU Make to set it to the contents
of `CARGO_MAKEFLAGS`.
* `CARGO_FEATURE_<name>` --- For each activated feature of the package being built,
this environment variable will be present where `<name>` is the name of the
feature uppercased and having `-` translated to `_`.
* `CARGO_CFG_<cfg>` --- For each [configuration option][configuration] of the
package being built, this environment variable will contain the value of the
configuration, where `<cfg>` is the name of the configuration uppercased and
Expand All @@ -358,42 +353,35 @@ let out_dir = env::var("OUT_DIR").unwrap();
> Note that different [target triples][Target Triple] have different sets of `cfg` values,
> hence variables present in one target triple might not be available in the other.
* `OUT_DIR` --- the folder in which all output and intermediate artifacts should
be placed. This folder is inside the build directory for the
package being built, and it is unique for the package in question.
be placed. This folder is inside the build directory for the package being built,
and it is unique for the package in question.
* `TARGET` --- the target triple that is being compiled for. Native code should be
compiled for this triple. See the [Target Triple] description
for more information.
compiled for this triple. See the [Target Triple] description for more information.
* `HOST` --- the host triple of the Rust compiler.
* `NUM_JOBS` --- the parallelism specified as the top-level parallelism. This can
be useful to pass a `-j` parameter to a system like `make`. Note
that care should be taken when interpreting this environment
variable. For historical purposes this is still provided but
recent versions of Cargo, for example, do not need to run `make
-j`, and instead can set the `MAKEFLAGS` env var to the content
of `CARGO_MAKEFLAGS` to activate the use of Cargo's GNU Make
compatible [jobserver] for sub-make invocations.
* `OPT_LEVEL`, `DEBUG` --- values of the corresponding variables for the
profile currently being built.
be useful to pass a `-j` parameter to a system like `make`. Note that care
should be taken when interpreting this environment variable. For historical
purposes this is still provided but recent versions of Cargo, for example, do
not need to run `make -j`, and instead can set the `MAKEFLAGS` env var to the
content of `CARGO_MAKEFLAGS` to activate the use of Cargo's GNU Make compatible
[jobserver] for sub-make invocations.
* `OPT_LEVEL`, `DEBUG` --- values of the corresponding variables for the profile currently being built.
* `PROFILE` --- `release` for release builds, `debug` for other builds. This is
determined based on if the [profile] inherits from the [`dev`] or
[`release`] profile. Using this environment variable is not recommended.
Using other environment variables like `OPT_LEVEL` provide a more correct
view of the actual settings being used.
* `DEP_<name>_<key>` --- For more information about this set of environment
variables, see build script documentation about [`links`][links].
* `DEP_<name>_<key>` --- For more information about this set of environment variables,
see build script documentation about [`links`][links].
* `RUSTC`, `RUSTDOC` --- the compiler and documentation generator that Cargo has
resolved to use, passed to the build script so it might
use it as well.
* `RUSTC_WRAPPER` --- the `rustc` wrapper, if any, that Cargo is using.
See [`build.rustc-wrapper`].
* `RUSTC_WORKSPACE_WRAPPER` --- the `rustc` wrapper, if any, that Cargo is
using for workspace members. See
[`build.rustc-workspace-wrapper`].
resolved to use, passed to the build script so it might use it as well.
* `RUSTC_WRAPPER` --- the `rustc` wrapper, if any, that Cargo is using. See [`build.rustc-wrapper`].
* `RUSTC_WORKSPACE_WRAPPER` --- the `rustc` wrapper, if any, that Cargo is using
for workspace members. See [`build.rustc-workspace-wrapper`].
* `RUSTC_LINKER` --- The path to the linker binary that Cargo has resolved to use
for the current target, if specified. The linker can be
changed by editing `.cargo/config.toml`; see the documentation
about [cargo configuration][cargo-config] for more
information.
for the current target, if specified. The linker can be changed by editing
`.cargo/config.toml`; see the documentation about [cargo configuration][cargo-config]
for more information.
* `CARGO_ENCODED_RUSTFLAGS` --- extra flags that Cargo invokes `rustc` with,
separated by a `0x1f` character (ASCII Unit Separator). See
[`build.rustflags`]. Note that since Rust 1.55, `RUSTFLAGS` is removed from
Expand Down Expand Up @@ -428,5 +416,8 @@ Cargo exposes this environment variable to 3rd party subcommands
(ie. programs named `cargo-foobar` placed in `$PATH`):

* `CARGO` --- Path to the `cargo` binary performing the build.
* `CARGO_MAKEFLAGS` --- Contains parameters needed for Cargo's [jobserver]
implementation to parallelize subprocesses.
This is set only when Cargo detects the existence of a jobserver.

For extended information about your environment you may run `cargo metadata`.