环境变量

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

Cargo 读取的环境变量

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

  • CARGO_LOG — Cargo 使用 tracing crate 来显示调试日志消息。可以设置 CARGO_LOG 环境变量来启用调试日志，其值可以是 trace、debug 或 warn。通常它只在调试期间使用。更多详情请参考 调试日志。
  • CARGO_HOME — Cargo 维护注册表索引和 crate 的 git 检出的本地缓存。默认情况下，这些存储在 $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 Unit Separator) 分隔的自定义标志列表，传递给 Cargo 执行的所有 rustdoc 调用。
  • RUSTFLAGS — 一个空格分隔的自定义标志列表，传递给 Cargo 执行的所有编译器调用。与 cargo rustc 相比，这对于将标志传递给 *所有* 编译器实例很有用。参阅 build.rustflags 了解更多设置标志的方法。此字符串按空格分割；为了更健壮地编码多个参数，请参阅 CARGO_ENCODED_RUSTFLAGS。
  • CARGO_ENCODED_RUSTFLAGS — 一个以 0x1f (ASCII Unit Separator) 分隔的自定义标志列表，传递给 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 标志打开文档的 Web 浏览器，请参阅 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 目标的名称，其中 - 转换为 _，例如库、二进制文件、示例、集成测试或基准测试的名称。
  • 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 还在使用 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! 的示例将不起作用，而需要在运行构建脚本时检索这些值

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 实现并行化子进程所需的参数。来自 build.rs 的 Rustc 或 cargo 调用已经可以读取 CARGO_MAKEFLAGS，但是 GNU Make 要求这些标志直接指定为参数，或通过 MAKEFLAGS 环境变量指定。当前 Cargo 不设置 MAKEFLAGS 变量，但是构建脚本可以自由地将 MAKEFLAGS 变量设置为 CARGO_MAKEFLAGS 的内容，从而调用 GNU Make。
  • CARGO_FEATURE_<name> — 对于正在构建的包的每个激活的特性，都将存在此环境变量，其中 <name> 是特性的名称，转换为大写并将 - 转换为 _。
  • CARGO_CFG_<cfg> — 对于正在构建的包的每个配置选项，此环境变量将包含配置的值，其中 <cfg> 是配置的名称，转换为大写并将 - 转换为 _。如果设置了布尔配置，则会显示，否则不会显示。具有多个值的配置将与逗号 , 分隔的值连接到单个变量。这包括编译器内置的值（可以使用 rustc --print=cfg 查看）以及由构建脚本设置的值和传递给 rustc 的额外标志（例如在 RUSTFLAGS 中定义的标志）。以下是这些变量的一些示例

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

    某些 cfg 值（如 debug_assertions、test）和 Cargo 特性（如 feature="foo"）不可用。

  • OUT_DIR — 应放置所有输出和中间工件的文件夹。此文件夹位于正在构建的包的构建目录内，并且对于所讨论的包是唯一的。
  • TARGET — 正在编译的目标三元组。本机代码应针对此三元组进行编译。有关更多信息，请参阅 目标三元组描述。
  • HOST — Rust 编译器的宿主三元组。
  • NUM_JOBS — 指定为顶级并行性的并行性。这对于将 -j 参数传递给 make 之类的系统很有用。请注意，在解释此环境变量时应谨慎。出于历史原因，仍然提供此变量，但是例如，最新版本的 Cargo 不需要运行 make -j，而是可以将 MAKEFLAGS 环境变量设置为 CARGO_MAKEFLAGS 的内容，以激活对 Cargo GNU Make 兼容作业服务器的子 make 调用的使用。
  • OPT_LEVEL, DEBUG — 当前正在构建的配置文件的相应变量的值。
  • PROFILE — 对于发布版本为 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 已解析为用于当前目标的链接器二进制文件的路径（如果已指定）。可以通过编辑 .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。