Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

環境變數

Cargo sets and reads a number of environment variables which your code can detect or override. Here is a list of the variables Cargo sets, organized by when it interacts with them:

Cargo 讀取的環境變數

You can override these environment variables to change Cargo’s behavior on your system:

  • CARGO_LOG — Cargo uses the tracing crate to display debug log messages. The CARGO_LOG environment variable can be set to enable debug logging, with a value such as trace, debug, or warn. Usually it is only used during debugging. For more details refer to the Debug logging.
  • CARGO_HOME — Cargo maintains a local cache of the registry index and of git checkouts of crates. By default these are stored under $HOME/.cargo (%USERPROFILE%\.cargo on Windows), but this variable overrides the location of this directory. Once a crate is cached it is not removed by the clean command. For more details refer to the guide.
  • CARGO_TARGET_DIR — Location of where to place all generated artifacts, relative to the current working directory. See build.target-dir to set via config.
  • CARGO — If set, Cargo will forward this value instead of setting it to its own auto-detected path when it builds crates and when it executes build scripts and external subcommands. This value is not directly executed by Cargo, and should always point at a command that behaves exactly like cargo, as that’s what users of the variable will be expecting.
  • 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, 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.
  • 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 the path to the actual rustc. When building a single-package project without workspaces, that package is considered to be the workspace. 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. If both RUSTC_WRAPPER and RUSTC_WORKSPACE_WRAPPER are set, then they will be nested: the final invocation is $RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC.
  • 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 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, 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.
  • 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, 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 will otherwise be used. See also build.incremental config value.
  • CARGO_CACHE_RUSTC_INFO — If this is set to 0 then Cargo will not try to cache compiler version information.
  • HTTPS_PROXY or https_proxy or http_proxy — The HTTP proxy to use, see http.proxy for more detail.
  • HTTP_TIMEOUT — The HTTP timeout in seconds, see http.timeout for more detail.
  • TERM — If this is set to dumb, it disables the progress bar.
  • BROWSER — The web browser to execute to open documentation with cargo doc’s --open flag, see doc.browser for more details.
  • RUSTFMT — Instead of running rustfmt, cargo fmt will execute this specified rustfmt instance instead.

組態環境變數

Cargo reads environment variables for some configuration values. See the configuration chapter for more details. In summary, the supported environment variables are:

Environment variables Cargo sets for crates

Cargo exposes these environment variables to your crate when it is compiled. Note that this applies for running binaries with cargo run and cargo test as well. To get the value of any of these variables in a Rust program, do this:

let version = env!("CARGO_PKG_VERSION");

version will now contain the value of CARGO_PKG_VERSION.

Note that if one of these values is not provided in the manifest, the corresponding environment variable is set to the empty string, "".

  • CARGO — 執行建置的 cargo 二進位路徑。
  • CARGO_MANIFEST_DIR — The directory containing the manifest of your package.
  • CARGO_MANIFEST_PATH — The path to the manifest of your package.
  • CARGO_PKG_VERSION — 軟體包的完整版本。
  • CARGO_PKG_VERSION_MAJOR — 軟體包的主要版本。
  • CARGO_PKG_VERSION_MINOR — 軟體包的次要版本。
  • CARGO_PKG_VERSION_PATCH — 軟體包的補釘版本。
  • CARGO_PKG_VERSION_PRE — 軟體包的預發行版本。
  • CARGO_PKG_AUTHORS — Colon separated list of authors from the manifest of your package.
  • CARGO_PKG_NAME — 軟體包的名稱。
  • CARGO_PKG_DESCRIPTION — The description from the manifest of your package.
  • CARGO_PKG_HOMEPAGE — The home page from the manifest of your package.
  • CARGO_PKG_REPOSITORY — The repository from the manifest of your package.
  • CARGO_PKG_LICENSE — The license from the manifest of your package.
  • CARGO_PKG_LICENSE_FILE — The license file from the manifest of your package.
  • CARGO_PKG_RUST_VERSION — The Rust version from the manifest of your package. Note that this is the minimum Rust version supported by the package, not the current Rust version.
  • CARGO_PKG_README — 您的軟體包中 README 檔案的路徑。
  • CARGO_CRATE_NAME — The name of the crate that is currently being compiled. It is the name of the Cargo target with - converted to _, such as the name of the library, binary, example, integration test, or benchmark.
  • 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.) Cargo does not guarantee that this directory is empty, and it is not cleaned between builds.
  • 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 purposes. The <name> is the name of the binary target, exactly as-is. For example, CARGO_BIN_EXE_my-program for a binary named my-program. Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.
  • CARGO_PRIMARY_PACKAGE — This environment variable will be set if the package being built is primary. Primary packages are the ones the user selected on the command-line, either with -p flags or the defaults based on the current directory and the default workspace members. This variable will not be set when building dependencies, unless a dependency is also a workspace member that was also selected on the command-line. This is only set when compiling the package (not when running binaries or tests).
  • CARGO_TARGET_TMPDIR — Only set when building integration test or benchmark code. This is a path to a directory inside the target directory where integration tests or benchmarks are free to put any data needed by the tests/benches. Cargo initially creates this directory but doesn’t manage its content in any way, this is the responsibility of the test code.

動態程式庫路徑

Cargo also sets the dynamic library path when compiling and running binaries with commands like cargo run and cargo test. This helps with locating shared libraries that are part of the build process. The variable name depends on the platform:

  • Windows：PATH
  • macOS：DYLD_FALLBACK_LIBRARY_PATH
  • Unix：LD_LIBRARY_PATH
  • AIX：LIBPATH

The value is extended from the existing value when Cargo starts. macOS has special consideration where if DYLD_FALLBACK_LIBRARY_PATH is not already set, it will add the default $HOME/lib:/usr/local/lib:/usr/lib.

Cargo 會引入以下路徑：

  • Search paths included from any build script with the rustc-link-search instruction. Paths outside of the target directory are removed. It is the responsibility of the user running Cargo to properly set the environment if additional libraries on the system are needed in the search path.
  • The base output directory, such as target/debug, and the “deps” directory. This is mostly for support of proc-macros.
  • The rustc sysroot library path. This generally is not important to most users.

Cargo 為建置腳本設定的環境變數

Cargo sets several environment variables when build scripts are run. Because these variables are not yet set when the build script is compiled, the above example using env! won’t work and instead you’ll need to retrieve the values when the build script is run:

use std::env;
let out_dir = env::var("OUT_DIR").unwrap();

out_dir 現在將包含 OUT_DIR 的值。

  • CARGO — 執行建置的 cargo 二進位路徑。

  • 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.

  • CARGO_MANIFEST_PATH — The path to the manifest of your package.

  • CARGO_MANIFEST_LINKS — 清單 links 值。

  • 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 _.

  • CARGO_CFG_<cfg> — For each configuration option 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 having - translated to _. Boolean configurations are present if they are set, and not present otherwise. Configurations with multiple values are joined to a single variable with the values delimited by ,. This includes values built-in to the compiler (which can be seen with rustc --print=cfg) and values set by build scripts and extra flags passed to rustc (such as those defined in RUSTFLAGS). Some examples of what these variables are:

    Note that different target triples have different sets of cfg values, hence variables present in one target triple might not be available in the other.

    Some cfg values like test are not available.

  • 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. Cargo does not clean or reset this directory between builds, and its contents may persist across rebuilds. Build scripts should not assume that OUT_DIR is empty, and are responsible for managing or cleaning up any files they create.

  • 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.

  • 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.

  • DEBUG — true if any debug information will be generated and false otherwise.

  • OPT_LEVEL — values of the corresponding opt-level variable 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_<links>_<key> — For more information about this set of environment variables, see build script documentation about 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.

  • 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 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 the environment; scripts should use CARGO_ENCODED_RUSTFLAGS instead.

  • CARGO_PKG_<var> — The package information variables, with the same names and values as are provided during crate building.

Environment variables Cargo sets for cargo test

Cargo sets several environment variables when tests are run. You can retrieve the values when the tests are run:

use std::env;
let out_dir = env::var("CARGO_BIN_EXE_foo").unwrap();
  • CARGO_BIN_EXE_<name> — The absolute path to a binary target’s executable. This is only set when running an integration test or benchmark. The <name> is the name of the binary target, exactly as-is. For example, CARGO_BIN_EXE_my-program for a binary named my-program. Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.

Cargo 為第三方子命令設定的環境變數

Cargo exposes this environment variable to 3rd party subcommands (ie. programs named cargo-foobar placed in $PATH):

  • CARGO — 執行建置的 cargo 二進位路徑。
  • 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.