环境变量

Cargo 设置并读取了许多环境变量，你的代码可以检测或覆盖这些变量。以下是 Cargo 设置的变量列表，按其交互时机进行组织

Cargo 读取的环境变量

你可以覆盖这些环境变量来改变 Cargo 在你的系统上的行为

  • CARGO_LOG — Cargo 使用 tracing crate 来显示调试日志消息。可以设置 CARGO_LOG 环境变量来启用调试日志，其值可以是 trace、debug 或 warn。通常仅在调试期间使用。有关更多详细信息，请参阅调试日志。
  • CARGO_HOME — Cargo 维护着注册表索引和 crate git checkout 的本地缓存。默认情况下，它们存储在 $HOME/.cargo（Windows 上为 %USERPROFILE%\.cargo）下，但此变量会覆盖此目录的位置。crate 被缓存后，不会通过 clean 命令移除。有关更多详细信息，请参阅指南。
  • CARGO_TARGET_DIR — 放置所有生成工件的位置，相对于当前工作目录。请参阅build.target-dir 通过配置文件设置。
  • CARGO — 如果设置了此变量，Cargo 在构建 crate 以及执行构建脚本和外部子命令时，会转发此值而不是设置为其自身自动检测到的路径。Cargo 不会直接执行此值，它应始终指向一个行为与 cargo 完全相同的命令，因为这是使用此变量的用户所期望的。
  • RUSTC — Cargo 不会运行 rustc，而是执行此指定的编译器。请参阅build.rustc 通过配置文件设置。
  • RUSTC_WRAPPER — Cargo 不会简单地运行 rustc，而是执行此指定的包装器，将其命令行参数作为 rustc 调用传递，第一个参数是实际 rustc 的路径。可用于设置构建缓存工具，如 sccache。请参阅build.rustc-wrapper 通过配置文件设置。将此值设置为空字符串会覆盖配置并重置 Cargo 不使用包装器。
  • RUSTC_WORKSPACE_WRAPPER — Cargo 不会简单地运行 rustc，而是针对工作区成员执行此指定的包装器，将其命令行参数作为 rustc 调用传递，第一个参数是实际 rustc 的路径。在没有工作区的情况下构建单包项目时，该包被视为工作区。它会影响文件名哈希，以便由包装器生成的工件单独缓存。请参阅build.rustc-workspace-wrapper 通过配置文件设置。将此值设置为空字符串会覆盖配置并重置 Cargo 不对工作区成员使用包装器。如果同时设置了 RUSTC_WRAPPER 和 RUSTC_WORKSPACE_WRAPPER，它们将嵌套执行：最终的调用是 $RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC。
  • RUSTDOC — Cargo 不会运行 rustdoc，而是执行此指定的 rustdoc 实例。请参阅build.rustdoc 通过配置文件设置。
  • RUSTDOCFLAGS — 一个空格分隔的自定义标志列表，会传递给 Cargo 执行的所有 rustdoc 调用。与 cargo rustdoc 不同，这对于将标志传递给*所有* rustdoc 实例很有用。请参阅build.rustdocflags 获取更多设置标志的方法。此字符串按空格分割；对于更可靠的多个参数编码，请参见 CARGO_ENCODED_RUSTDOCFLAGS。
  • CARGO_ENCODED_RUSTDOCFLAGS — 一个以 0x1f（ASCII 单元分隔符）分隔的自定义标志列表，会传递给 Cargo 执行的所有 rustdoc 调用。
  • RUSTFLAGS — 一个空格分隔的自定义标志列表，会传递给 Cargo 执行的所有编译器调用。与 cargo rustc 不同，这对于将标志传递给*所有*编译器实例很有用。请参阅build.rustflags 获取更多设置标志的方法。此字符串按空格分割；对于更可靠的多个参数编码，请参见 CARGO_ENCODED_RUSTFLAGS。
  • CARGO_ENCODED_RUSTFLAGS — 一个以 0x1f（ASCII 单元分隔符）分隔的自定义标志列表，会传递给 Cargo 执行的所有编译器调用。
  • CARGO_INCREMENTAL — 如果此值设置为 1，Cargo 将强制当前编译启用增量编译；如果设置为 0，则强制禁用。如果此环境变量不存在，则使用 Cargo 的默认设置。另请参见build.incremental 配置值。
  • CARGO_CACHE_RUSTC_INFO — 如果此值设置为 0，则 Cargo 不会尝试缓存编译器版本信息。
  • HTTPS_PROXY 或 https_proxy 或 http_proxy — 要使用的 HTTP 代理，更多详细信息请参见http.proxy。
  • HTTP_TIMEOUT — HTTP 超时时间（秒），更多详细信息请参见http.timeout。
  • TERM — 如果此值设置为 dumb，则禁用进度条。
  • BROWSER — 使用 cargo doc 的 --open 标志打开文档时要执行的网页浏览器，更多详细信息请参见doc.browser。
  • RUSTFMT — cargo fmt 不会运行 rustfmt，而是执行此指定的 rustfmt 实例。

配置环境变量

Cargo 读取一些配置值的环境变量。有关更多详细信息，请参见配置章节。总而言之，支持的环境变量有

Cargo 为 crate 设置的环境变量

Cargo 在编译时将这些环境变量暴露给你的 crate。请注意，这也适用于使用 cargo run 和 cargo test 运行二进制文件。要在 Rust 程序中获取任何这些变量的值，请执行以下操作

let version = env!("CARGO_PKG_VERSION");

version 现在将包含 CARGO_PKG_VERSION 的值。

请注意，如果在清单中未提供这些值之一，相应的环境变量将设置为空字符串 ""。

  • CARGO — 执行构建的 cargo 二进制文件的路径。
  • CARGO_MANIFEST_DIR — 包含你的包的清单的目录。
  • CARGO_MANIFEST_PATH — 你的包的清单的路径。
  • CARGO_PKG_VERSION — 你的包的完整版本。
  • CARGO_PKG_VERSION_MAJOR — 你的包的主版本号。
  • CARGO_PKG_VERSION_MINOR — 你的包的次版本号。
  • CARGO_PKG_VERSION_PATCH — 你的包的补丁版本号。
  • CARGO_PKG_VERSION_PRE — 你的包的预发布版本。
  • CARGO_PKG_AUTHORS — 你的包的清单中作者的列表，用冒号分隔。
  • CARGO_PKG_NAME — 你的包的名称。
  • CARGO_PKG_DESCRIPTION — 你的包的清单中的描述。
  • CARGO_PKG_HOMEPAGE — 你的包的清单中的主页。
  • CARGO_PKG_REPOSITORY — 你的包的清单中的仓库。
  • CARGO_PKG_LICENSE — 你的包的清单中的许可证。
  • CARGO_PKG_LICENSE_FILE — 你的包的清单中的许可证文件。
  • CARGO_PKG_RUST_VERSION — 你的包的清单中的 Rust 版本。请注意，这是包支持的最低 Rust 版本，而不是当前的 Rust 版本。
  • CARGO_PKG_README — 你的包的 README 文件的路径。
  • CARGO_CRATE_NAME — 当前正在编译的 crate 的名称。它是 Cargo target 的名称，其中 - 被转换为 _，例如库、二进制文件、示例、集成测试或基准测试的名称。
  • CARGO_BIN_NAME — 当前正在编译的二进制文件的名称。仅为二进制文件或二进制示例设置。此名称不包含任何文件扩展名，例如 .exe。
  • OUT_DIR — 如果包有构建脚本，此变量会被设置为构建脚本应放置其输出的文件夹。有关更多信息，请参见下文。（仅在编译期间设置。）
  • CARGO_BIN_EXE_<name> — 二进制 target 可执行文件的绝对路径。仅在构建集成测试或基准测试时设置。这可以与 env macro 一起使用，以查找用于测试目的的可执行文件。<name> 是二进制 target 的名称，完全按原样。例如，对于名为 my-program 的二进制文件，变量是 CARGO_BIN_EXE_my-program。二进制文件在构建测试时会自动构建，除非二进制文件具有未启用的必需 features。
  • CARGO_PRIMARY_PACKAGE — 如果正在构建的包是主要包，则会设置此环境变量。主要包是用户在命令行上选择的包，通过 -p 标志或基于当前目录和默认工作区成员的默认值选择。构建依赖项时不会设置此变量，除非该依赖项同时也是在命令行上选择的工作区成员。这仅在编译包时设置（不在运行二进制文件或测试时）。
  • CARGO_TARGET_TMPDIR — 仅在构建集成测试或基准测试代码时设置。这是指向 target 目录内的一个目录的路径，集成测试或基准测试可以在其中随意放置测试/基准所需的数据。Cargo 最初创建此目录，但不对其内容进行任何管理，这是测试代码的责任。

动态库路径

Cargo 在使用 cargo run 和 cargo test 等命令编译和运行二进制文件时也会设置动态库路径。这有助于定位作为构建过程一部分的共享库。变量名称取决于平台

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

该值在 Cargo 启动时从现有值扩展。macOS 有特殊考虑，如果 DYLD_FALLBACK_LIBRARY_PATH 尚未设置，它将添加默认值 $HOME/lib:/usr/local/lib:/usr/lib。

Cargo 包含以下路径

  • 通过 rustc-link-search 指令从任何构建脚本包含的搜索路径。target 目录之外的路径将被移除。如果搜索路径中需要系统上的附加库，则运行 Cargo 的用户有责任正确设置环境。
  • 基本输出目录，例如 target/debug，以及“deps”目录。这主要用于支持 proc-macros。
  • rustc sysroot 库路径。这对于大多数用户来说通常不重要。

Cargo 为构建脚本设置的环境变量

在运行构建脚本时，Cargo 会设置几个环境变量。由于这些变量在构建脚本编译时尚未设置，因此上面使用 env! 的示例不起作用，你需要在使用 std::env::var 运行构建脚本时检索值

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

out_dir 现在将包含 OUT_DIR 的值。

  • CARGO — 执行构建的 cargo 二进制文件的路径。
  • CARGO_MANIFEST_DIR — 包含正在构建的包（包含构建脚本的包）的清单的目录。另请注意，这是构建脚本启动时当前工作目录的值。
  • CARGO_MANIFEST_PATH — 你的包的清单的路径。
  • CARGO_MANIFEST_LINKS — 清单 links 值。
  • CARGO_MAKEFLAGS — 包含 Cargo jobserver 实现并行化子进程所需的参数。构建脚本中的 Rustc 或 Cargo 调用已经可以读取 CARGO_MAKEFLAGS，但 GNU Make 要求标志直接作为参数指定，或通过 MAKEFLAGS 环境变量指定。目前 Cargo 不设置 MAKEFLAGS 变量，但调用 GNU Make 的构建脚本可以自由地将其设置为 CARGO_MAKEFLAGS 的内容。
  • CARGO_FEATURE_<name> — 对于正在构建的包的每个激活的 feature，此环境变量都会存在，其中 <name> 是 feature 名称的大写形式，并且 - 已转换为 _。
  • CARGO_CFG_<cfg> — 对于正在构建的包的每个配置选项，此环境变量将包含配置的值，其中 <cfg> 是配置名称的大写形式，并且 - 已转换为 _。布尔型配置如果设置了就会存在，否则不存在。具有多个值的配置会合并到一个变量中，值之间用 , 分隔。这包括编译器内置的值（可以通过 rustc --print=cfg 查看）以及由构建脚本设置的以及传递给 rustc 的额外标志设置的值（例如在 RUSTFLAGS 中定义的值）。以下是一些这些变量的示例

    请注意，不同的目标三元组具有不同的 cfg 值集合，因此在一个目标三元组中存在的变量可能在另一个目标三元组中不可用。

    某些 cfg 值，如 debug_assertions 和 test 不可用。

  • OUT_DIR — 所有输出和中间工件应放置的文件夹。此文件夹位于正在构建的包的构建目录内，并且对于该包是唯一的。
  • TARGET — 正在编译的目标三元组。本地代码应针对此三元组进行编译。有关更多信息，请参见目标三元组描述。
  • HOST — Rust 编译器的宿主三元组。
  • NUM_JOBS — 指定的顶级并行度。这对于向 make 等系统传递 -j 参数可能有用。请注意，解释此环境变量时应谨慎。出于历史原因，此变量仍然提供，但新版本的 Cargo，例如，无需运行 make -j，而是可以将 MAKEFLAGS 环境变量设置为 CARGO_MAKEFLAGS 的内容，以激活 Cargo 与 GNU Make 兼容的jobserver 用于子 make 调用。
  • OPT_LEVEL, DEBUG — 当前正在构建的 profile 对应的变量值。
  • PROFILE — release 构建时为 release，其他构建时为 debug。这取决于profile 是否继承自 dev 或 release profile。不推荐使用此环境变量。使用其他环境变量（如 OPT_LEVEL）可以更准确地反映实际使用的设置。
  • DEP_<name>_<key> — 有关这组环境变量的更多信息，请参见构建脚本文档中关于links 的部分。
  • RUSTC, RUSTDOC — Cargo 决定使用的编译器和文档生成器，传递给构建脚本，以便构建脚本也可以使用它们。
  • RUSTC_WRAPPER — 如果 Cargo 使用了 rustc 包装器，则为该包装器。请参见build.rustc-wrapper。
  • RUSTC_WORKSPACE_WRAPPER — 如果 Cargo 使用了用于工作区成员的 rustc 包装器，则为该包装器。请参见build.rustc-workspace-wrapper。
  • RUSTC_LINKER — Cargo 决定用于当前 target 的链接器二进制文件的路径（如果指定）。可以通过编辑 .cargo/config.toml 来更改链接器；有关更多信息，请参见Cargo 配置文档。
  • CARGO_ENCODED_RUSTFLAGS — Cargo 调用 rustc 时使用的额外标志，以 0x1f 字符（ASCII 单元分隔符）分隔。请参见build.rustflags。请注意，自 Rust 1.55 起，RUSTFLAGS 已从环境中移除；脚本应改用 CARGO_ENCODED_RUSTFLAGS。
  • CARGO_PKG_<var> — 包信息变量，名称和值与crate 构建时提供的相同。

Cargo 为第三方子命令设置的环境变量

Cargo 将此环境变量暴露给第三方子命令（即放置在 $PATH 中的名为 cargo-foobar 的程序）

  • CARGO — 执行构建的 cargo 二进制文件的路径。
  • CARGO_MAKEFLAGS — 包含 Cargo jobserver 实现并行化子进程所需的参数。仅当 Cargo 检测到 jobserver 存在时才设置此变量。

有关环境的更多信息，你可以运行 cargo metadata。