Auto merge of #13872 - weihanglo:doc, r=epage

bors · bors · commit 9b4a50183f57 · 2024-05-07T04:48:21.000Z
docs: add missing CARGO_MAKEFLAGS env for plugins
diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md
@@ -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
@@ -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
@@ -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
@@ -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`.
