环境变量

Cargo 会设置和读取许多环境变量，您的代码可以检测或覆盖这些变量。以下是 Cargo 设置的变量列表，按其交互时间排序

Cargo 读取的环境变量

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

  • CARGO_LOG - Cargo 使用 tracing crate 来显示调试日志消息。可以将 CARGO_LOG 环境变量设置为启用调试日志记录，其值可以是 trace、debug 或 warn。通常它只在调试期间使用。有关更多详细信息，请参阅调试日志记录。
  • CARGO_HOME - Cargo 维护注册表索引和 crates 的 git 签出的本地缓存。默认情况下，它们存储在 $HOME/.cargo 下（Windows 上为 %USERPROFILE%\.cargo），但此变量会覆盖此目录的位置。缓存 crate 后，将不会被 clean 命令删除。有关更多详细信息，请参阅指南。
  • CARGO_TARGET_DIR - 放置所有生成工件的位置，相对于当前工作目录。请参阅build.target-dir 以通过配置进行设置。
  • CARGO - 如果设置，Cargo 将转发此值，而不是在构建 crates 以及执行构建脚本和外部子命令时将其设置为自动检测到的路径。此值不会被 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 - 传递给 Cargo 执行的所有 rustdoc 调用的以 0x1f（ASCII 单元分隔符）分隔的自定义标志列表。
  • RUSTFLAGS - 传递给 Cargo 执行的所有编译器调用的自定义标志的空格分隔列表。与 cargo rustc 相比，这对于将标志传递给所有编译器实例很有用。有关设置标志的更多方法，请参阅 build.rustflags。此字符串由空格分隔；有关多个参数的更健壮的编码，请参阅 CARGO_ENCODED_RUSTFLAGS。
  • CARGO_ENCODED_RUSTFLAGS - 传递给 Cargo 执行的所有编译器调用的自定义标志列表，由 0x1f（ASCII 单元分隔符）分隔。
  • 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 标志打开文档的 Web 浏览器，有关更多详细信息，请参阅 doc.browser。
  • RUSTFMT - cargo fmt 将执行此指定的 rustfmt 实例，而不是运行 rustfmt。

配置环境变量

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

Cargo 为箱子设置的环境变量

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

let version = env!("CARGO_PKG_VERSION");

version 现在将包含 CARGO_PKG_VERSION 的值。

请注意，如果清单中未提供其中一个值，则相应的环境变量将设置为字符串 ""。

  • CARGO - 执行构建的 cargo 二进制文件的路径。
  • CARGO_MANIFEST_DIR - 包含包清单的目录。
  • 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 目标 的名称，将 - 转换为 _，例如库、二进制文件、示例、集成测试或基准测试的名称。
  • CARGO_BIN_NAME - 当前正在编译的二进制文件的名称。仅针对 二进制文件 或二进制 示例 设置。此名称不包括任何文件扩展名，例如 .exe。
  • OUT_DIR - 如果包具有构建脚本，则将其设置为构建脚本应放置其输出的文件夹。有关更多信息，请参见下文。（仅在编译期间设置。）
  • CARGO_BIN_EXE_<name> - 二进制目标可执行文件的绝对路径。这仅在构建 集成测试 或基准测试时设置。这可以与 env 宏 一起使用，以查找要运行以进行测试的可执行文件。<name> 是二进制目标的名称，与原样完全相同。例如，对于名为 my-program 的二进制文件，为 CARGO_BIN_EXE_my-program。除非二进制文件具有未启用的必需功能，否则二进制文件会在测试构建时自动构建。
  • CARGO_PRIMARY_PACKAGE - 如果正在构建的包是主包，则将设置此环境变量。主包是用户在命令行上选择的包，可以使用 -p 标志或基于当前目录和默认工作空间成员的默认值。构建依赖项时，不会设置此环境变量。这仅在编译包时设置（而不是在运行二进制文件或测试时）。
  • CARGO_TARGET_TMPDIR - 仅在构建 集成测试 或基准测试代码时设置。这是目标目录中一个目录的路径，集成测试或基准测试可以在其中自由放置测试/基准测试所需的任何数据。Cargo 最初会创建此目录，但不会以任何方式管理其内容，这是测试代码的责任。
  • CARGO_RUSTC_CURRENT_DIR - 这是调用 rustc 的路径 （仅限 nightly 版本）。

动态库路径

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”目录。这主要用于对 rustc 编译器插件的旧版支持。
  • rustc sysroot 库路径。这通常对大多数用户来说并不重要。

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

Cargo 在运行构建脚本时会设置几个环境变量。因为在编译构建脚本时尚未设置这些变量，所以上面使用 env! 的示例将不起作用，而需要在运行构建脚本时检索值

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

out_dir 现在将包含 OUT_DIR 的值。

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

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

  • OUT_DIR - 应在其中放置所有输出和中间工件的文件夹。此文件夹位于正在构建的包的构建目录内，并且对于相关包是唯一的。
  • TARGET - 正在为其编译的目标三元组。本机代码应针对此三元组进行编译。有关更多信息，请参见 目标三元组 描述。
  • HOST - Rust 编译器的主机三元组。
  • NUM_JOBS - 指定为顶级并行度的并行度。这对于将 -j 参数传递给像 make 这样的系统很有用。请注意，在解释此环境变量时应小心。出于历史原因，仍然提供此功能，但最近版本的 Cargo（例如）不需要运行 make -j，而是可以将 MAKEFLAGS 环境变量设置为 CARGO_MAKEFLAGS 的内容，以激活对子 make 调用使用 Cargo 的 GNU Make 兼容 jobserver。
  • OPT_LEVEL、DEBUG - 当前正在构建的配置文件的相应变量的值。
  • PROFILE - 发布版本为 release，其他版本为 debug。这是根据 配置文件 是否从 dev 或 release 配置文件继承来确定的。不建议使用此环境变量。使用其他环境变量（如 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 已解析为用于当前目标的链接器二进制文件的路径（如果已指定）。可以通过编辑 .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 metadata。