开发工具包管理器CLI构建工具【免费下载链接】cargoThe Rust package manager项目地址https://gitcode.com/gh_mirrors/car/cargo点击查看免费下载本文系统梳理 Rust 包管理器 Cargo 与环境变量的全部交互Cargo 读取哪些变量来改变自身行为、编译 crate 时注入了哪些变量、build script构建脚本运行时会获得哪些专属变量。读者读完可以掌握CARGO_HOME、RUSTFLAGS、CARGO_CFG_*、CARGO_FEATURE_*、OUT_DIR等核心变量的语义、优先级与在build.rs与测试代码中的读取姿势并理解 Cargo 在 src/context/environment.rs 中实现的环境变量快照机制。背景man 手册中的 ENVIRONMENT 片段从哪里来本主题源自 Cargo 仓库的 man 文档片段 doc/man/includes/section-environment.md它只有短短两行## ENVIRONMENT See the reference for details on environment variables that Cargo reads.这个片段由 mdman 模板系统嵌入到36 个cargo-*子命令的 man 页面中如 doc/man/cargo-build.md、doc/man/cargo-test.md、doc/man/cargo-run.md 等均以{{ section-environment }}方式引入统一指向手册参考章节 doc/book/src/reference/environment-variables.md。也就是说任何子命令的--help/ man 文档都会提示读者Cargo 读取哪些环境变量详见参考手册。本文即对该参考手册的完整展开并结合仓库源码逐项印证。参考手册将环境变量按Cargo 何时与之交互分为五类Cargo 读取用户可覆盖改变 Cargo 行为Cargo 为 crate编译期设置Cargo 为 build script 设置Cargo 为cargo test设置Cargo 为第三方子命令设置。下面按此脉络逐一深入。Cargo 读取的环境变量你可以覆盖哪些行为这些变量可以在你的系统环境中设置从而改变 Cargo 的默认行为。它们大多同时存在对应的.cargo/config.toml配置键且环境变量优先级高于 TOML 配置文件详见 doc/book/src/reference/config.md 的 Environment variables 一节。日志、缓存与产物目录变量作用对应配置键CARGO_LOGCargo 使用tracingcrate 输出调试日志取值如trace、debug、warn通常仅调试时使用。还可携带模块过滤器例如CARGO_LOGcargo::compiler::fingerprinttrace cargo build可定位重编译原因见 src/compiler/fingerprint/mod.rs无日志相关CARGO_HOME覆盖 Cargo 本地缓存的根目录。默认位于$HOME/.cargoWindows 为%USERPROFILE%\.cargo。一旦 crate 被缓存cargo clean不会删除它见下方 CARGO_HOME 小节CARGO_TARGET_DIR所有构建产物的输出目录相对于当前工作目录[build.target-dir]CARGO_CACHE_RUSTC_INFO设为0时Cargo 不再缓存编译器版本信息—CARGO_INCREMENTAL设为1强制开启增量编译设为0强制关闭未设置时使用 Cargo 默认值。注意在 CI 环境中默认关闭CARGO_BUILD_INCREMENTALfalse[build.incremental]TERM设为dumb时禁用进度条—在源码层CARGO_TARGET_DIR的读取逻辑位于 src/context/mod.rsGlobalContext::target_dir()依次检查命令行--target-dir、环境变量CARGO_TARGET_DIR空字符串会被明确拒绝并报错、build.target_dir配置项。编译器与 rustdoc 替换变量作用对应配置键CARGO若已设置Cargo 在构建 crate、执行 build script 与外部子命令时转发该值而非自动探测的自身路径。Cargo 不会直接执行它它应指向一个行为与cargo完全一致的命令—RUSTC指定要执行的编译器替代默认的rustc[build.rustc]RUSTC_WRAPPER指定 rustc 包装器Cargo 以实际 rustc 路径为第一个参数调用该包装器典型用途如sccache构建缓存。设为空字符串可覆盖配置并复位为不使用包装器[build.rustc-wrapper]RUSTC_WORKSPACE_WRAPPER仅对 workspace 成员生效的 rustc 包装器单包项目无 workspace时该包本身视为 workspace。它会影响文件名哈希使包装器产物被单独缓存。RUSTC_WRAPPER与它同时设置时会嵌套调用$RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC[build.rustc-workspace-wrapper]RUSTDOC指定要执行的rustdoc实例[build.rustdoc]RUSTFMT指定cargo fmt要执行的rustfmt实例—编译标志RUSTFLAGS 与 CARGO_ENCODED_RUSTFLAGS变量作用对应配置键RUSTFLAGS传给所有rustc调用的自定义标志空格分隔。与cargo rustc不同它作用于所有编译器实例[build.rustflags]CARGO_ENCODED_RUSTFLAGS以0x1fASCII Unit Separator单元分隔符分隔的标志列表比空格分隔更健壮同上RUSTDOCFLAGS传给所有rustdoc调用的标志空格分隔[build.rustdocflags]CARGO_ENCODED_RUSTDOCFLAGS以0x1f分隔的 rustdoc 标志列表同上注意自 Rust 1.55 起RUSTFLAGS会从 build script 的环境中移除脚本应改用CARGO_ENCODED_RUSTFLAGS。源码中 build script 环境的确如此处理见 src/compiler/custom_build.rs先设置CARGO_ENCODED_RUSTFLAGS用\x1f连接随后env_remove(RUSTFLAGS)。网络与显示相关变量作用对应配置键HTTPS_PROXY/https_proxy/http_proxyHTTP 代理[http.proxy]HTTP_TIMEOUTHTTP 超时秒数[http.timeout]BROWSERcargo doc --open用于打开文档的浏览器[doc.browser]配置类环境变量CARGO_* 与 config 键的映射规则Cargo 允许通过环境变量覆盖绝大多数配置项。规则见 doc/book/src/reference/config.md对形如foo.bar的配置键可用环境变量CARGO_FOO_BAR定义。键转大写、点与短横线转下划线。例如配置键target.x86_64-unknown-linux-gnu.runner对应CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER。优先级--config 高于环境变量高于配置文件--config命令行参数 环境变量 TOML 配置文件见 doc/book/src/reference/config.md。目前仅支持整数、布尔、字符串与部分数组类型通过环境变量定义。源码中的实现Env 快照与大小写归一化Cargo 在启动时对进程环境做一次性快照实现位于 src/context/environment.rs 的make_case_insensitive_and_normalized_envcase_insensitive_env将所有键转为大写映射回真实键用于 Windows 上键大小写不敏感的环境normalized_env保留 UTF-8 键值对把键转大写并将-替换为_用于配置系统告警提示例如用户写成CARGO_BUILD-RUSTC时会收到错误格式提示。配置值的读取则经由GlobalContext::get的 Typed Config Value API仅支持CARGO_前缀的环境键见 src/context/environment.rs 的文档注释。全量清单与 config 键一一对应参考手册列出的配置环境变量包括均指向 doc/book/src/reference/config.md 对应小节alias / 构建CARGO_ALIAS_name、CARGO_BUILD_WARNINGS、CARGO_BUILD_JOBS、CARGO_BUILD_RUSTC、CARGO_BUILD_RUSTC_WRAPPER、CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER、CARGO_BUILD_RUSTDOC、CARGO_BUILD_TARGET、CARGO_BUILD_TARGET_DIR、CARGO_BUILD_BUILD_DIR、CARGO_BUILD_PROFILE、CARGO_BUILD_RUSTFLAGS、CARGO_BUILD_RUSTDOCFLAGS、CARGO_BUILD_INCREMENTAL、CARGO_BUILD_DEP_INFO_BASEDIR缓存 / 新建项目 / 凭据CARGO_CACHE_AUTO_CLEAN_FREQUENCY、CARGO_CARGO_NEW_VCS、CARGO_CREDENTIAL_ALIAS_name、CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCYHTTPCARGO_HTTP_DEBUG、CARGO_HTTP_PROXY、CARGO_HTTP_TIMEOUT、CARGO_HTTP_CAINFO、CARGO_HTTP_PROXY_CAINFO、CARGO_HTTP_CHECK_REVOKE、CARGO_HTTP_SSL_VERSION、CARGO_HTTP_LOW_SPEED_LIMIT、CARGO_HTTP_MULTIPLEXING、CARGO_HTTP_USER_AGENTinstall / netCARGO_INSTALL_ROOT、CARGO_INSTALL_PROFILE、CARGO_NET_RETRY、CARGO_NET_GIT_FETCH_WITH_CLI、CARGO_NET_OFFLINEprofileCARGO_PROFILE_name_BUILD_OVERRIDE_key、CARGO_PROFILE_name_CODEGEN_UNITS、CARGO_PROFILE_name_DEBUG、CARGO_PROFILE_name_DEBUG_ASSERTIONS、CARGO_PROFILE_name_INCREMENTAL、CARGO_PROFILE_name_LTO、CARGO_PROFILE_name_OVERFLOW_CHECKS、CARGO_PROFILE_name_OPT_LEVEL、CARGO_PROFILE_name_PANIC、CARGO_PROFILE_name_RPATH、CARGO_PROFILE_name_SPLIT_DEBUGINFO、CARGO_PROFILE_name_STRIPregistries / registryCARGO_REGISTRIES_name_CREDENTIAL_PROVIDER、CARGO_REGISTRIES_name_INDEX、CARGO_REGISTRIES_name_MIN_PUBLISH_AGE、CARGO_REGISTRIES_name_TOKEN、CARGO_REGISTRIES_CRATES_IO_PROTOCOL、CARGO_REGISTRY_CREDENTIAL_PROVIDER、CARGO_REGISTRY_DEFAULT、CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS、CARGO_REGISTRY_GLOBAL_MIN_PUBLISH_AGE、CARGO_REGISTRY_TOKENresolverCARGO_RESOLVER_INCOMPATIBLE_PUBLISH_AGE、CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS、CARGO_RESOLVER_LOCKFILE_PATHtargetCARGO_TARGET_tuple_LINKER、CARGO_TARGET_tuple_RUNNER、CARGO_TARGET_tuple_RUSTFLAGS、CARGO_TARGET_tuple_RUSTDOCFLAGStuple 需转为大写与下划线termCARGO_TERM_QUIET、CARGO_TERM_VERBOSE、CARGO_TERM_COLOR、CARGO_TERM_HYPERLINKS、CARGO_TERM_UNICODE、CARGO_TERM_PROGRESS_WHEN、CARGO_TERM_PROGRESS_WIDTH、CARGO_TERM_PROGRESS_TERM_INTEGRATION。补充CARGO_HOME 的目录结构CARGO_HOME不仅是缓存根目录还包含 Cargo 的全局配置与安装产物。按 doc/book/src/guide/cargo-home.md 所述文件config.toml全局配置、credentials.tomlcargo login写入的私密凭据、.crates.toml/.crates2.jsoncargo install安装的包信息勿手工编辑目录bin/cargo install与 rustup 安装的可执行文件需加入$PATH、git/db/git 依赖的裸仓库、git/checkouts/git 依赖检出目录、registry/index/注册表索引的裸 git 仓库、registry/cache/下载的.crategzip 压缩包、registry/src/解压后的源码。在 CI 中缓存 Cargo home 时手册建议仅缓存.crates.toml、.crates2.json、bin/、registry/index/、registry/cache/、git/db/避免同时缓存.crate与其解压源码两份数据。源码层中git/与registry/子目录的定位见 src/context/mod.rs。Cargo 为 crate 设置的环境变量编译期可见cargo run与cargo test运行二进制时同样注入这些变量。在 Rust 代码中可用env!宏在编译期读取let version env!(CARGO_PKG_VERSION);version即包含CARGO_PKG_VERSION的值。注意若 manifest 未提供对应字段相关变量会被设为空字符串。完整清单详见 doc/book/src/reference/environment-variables.md路径CARGO正在执行构建的 cargo 二进制路径、CARGO_MANIFEST_DIR包 manifest 所在目录、CARGO_MANIFEST_PATHmanifest 的完整路径包信息CARGO_PKG_VERSION完整版本、CARGO_PKG_VERSION_MAJOR/MINOR/PATCH/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 版本而非当前 rustc 版本、CARGO_PKG_README目标信息CARGO_CRATE_NAME当前编译 crate 名-转为_适用于 lib/bin/example/集成测试/bench、CARGO_BIN_NAME当前编译的二进制名不含.exe等扩展名仅二进制目标与二进制 example 设置构建脚本输出OUT_DIR若有 build script指向其输出目录Cargo 不保证目录为空且两次构建间不清空测试辅助CARGO_BIN_EXE_name集成测试或 benchmark 构建时指向某二进制可执行文件的绝对路径name为二进制目标原名如CARGO_BIN_EXE_my-program、CARGO_TARGET_TMPDIR仅集成测试/benchmark 构建时设置指向 target 目录内供测试自由使用的目录Cargo 创建但不管理其内容主包标记CARGO_PRIMARY_PACKAGE仅当包是主包时设置。主包指用户在命令行用-p选中的包或当前目录/默认 workspace 成员编译依赖时不会设置除非该依赖同时是被选中的 workspace 成员且仅编译包时设置运行二进制或测试时不设。源码佐证这些变量在 src/compiler/compilation.rs 中逐一注入CARGO_PKG_VERSION_*、CARGO_PKG_NAME、CARGO_MANIFEST_DIR、CARGO_MANIFEST_PATH均直接取自 package 对象CARGO_BIN_NAME与CARGO_CRATE_NAME由 fill_rustc_tool_env 设置CARGO_BIN_EXE_name在 src/compiler/artifact.rs 为测试构建补充cargo check时也会提供占位值以让env!(CARGO_BIN_EXE_...)宏可编译CARGO_PRIMARY_PACKAGE与CARGO_TARGET_TMPDIR见 src/compiler/mod.rs。动态库搜索路径编译与运行cargo run/cargo test时Cargo 还会扩展动态库搜索路径以定位构建过程的共享库变量名因平台而异平台变量WindowsPATHmacOSDYLD_FALLBACK_LIBRARY_PATHUnixLD_LIBRARY_PATHAIXLIBPATHCargo 会在启动时已有值的基础上追加以下路径任何 build script 通过rustc-link-search指令给出的搜索路径target目录之外的路径会被移除系统库需用户自行设置环境基础输出目录如target/debug及其deps目录主要为 proc-macro 支持rustc sysroot 库路径一般对用户不重要。macOS 有特殊处理若DYLD_FALLBACK_LIBRARY_PATH未设置Cargo 会补上默认的$HOME/lib:/usr/local/lib:/usr/lib——对应源码 src/compiler/compilation.rs 中的逻辑。Cargo 为 build script 设置的环境变量build scriptbuild.rs运行时这些变量尚未被设置因此不能用env!宏必须在运行时读取use std::env; let out_dir env::var(OUT_DIR).unwrap();out_dir即包含OUT_DIR的值。基础信息CARGO执行构建的 cargo 二进制路径CARGO_MANIFEST_DIR被构建包含 build script 的包的 manifest 目录也是 build script 启动时的当前工作目录CARGO_MANIFEST_PATH包 manifest 的路径CARGO_MANIFEST_LINKSmanifest 中links键的值见 src/compiler/custom_build.rsCARGO_PKG_var与编译期 variables set for crates 同名同值的包信息变量。并行度与 jobserverCARGO_MAKEFLAGS包含 Cargo jobserver 实现所需的参数用于并行化子进程。rustc或cargo调用可直接读取GNU Make 则要求通过MAKEFLAGS环境变量或命令行参数指定。Cargo 自身不设置MAKEFLAGS但 build script 可自由地把CARGO_MAKEFLAGS的内容赋给它以在子 make 中启用 Cargo 的 GNU Make 兼容 jobserver。jobserver 在源码中的管理见 src/compiler/build_runner/mod.rs若环境中没有外部 jobservergctx.jobserver_from_env()Cargo 会创建自己的jobserver::Client此外 src/compiler/build_config.rs 会在同时指定-j与外部 jobserver 时发出警告。features 与 cfgCARGO_FEATURE_name对每个已激活 feature设置该变量name为 feature 名转大写、-转_CARGO_CFG_cfg对每个配置项设置该变量cfg为配置名转大写、-转_。布尔型配置存在即设置、不存在即不设置多值配置用逗号连接为单变量。它包含编译器内置值可用rustc --printcfg查看以及 build script 与额外rustc标志如RUSTFLAGS设置的值。常见示例CARGO_CFG_FEATURE— 每个已激活 featureCARGO_CFG_UNIX/CARGO_CFG_WINDOWS— Unix/Windows 平台CARGO_CFG_TARGET_FAMILYunix,wasm、CARGO_CFG_TARGET_OSmacos、CARGO_CFG_TARGET_ARCHx86_64、CARGO_CFG_TARGET_VENDORapple、CARGO_CFG_TARGET_ENVgnu、CARGO_CFG_TARGET_ABIeabihf、CARGO_CFG_TARGET_POINTER_WIDTH64、CARGO_CFG_TARGET_ENDIANlittle、CARGO_CFG_TARGET_FEATUREmmx,sse。注意两点不同 target tuple 的cfg值集合不同某个 tuple 存在的变量在另一个 tuple 中可能不存在test等部分 cfg 值不可用。CARGO_CFG_*应优先于cfg!宏或#[cfg]属性在 build script 中使用后者检查的是host平台而非target。如需类型化 API可考虑社区build-rscrate 而非手工解析。源码层面CARGO_FEATURE_name与CARGO_CFG_cfg的注入在 src/compiler/custom_build.rsfeature 与 cfg 被收集进cfg_map后遍历写入键名转换复用 src/compiler/mod.rs 的envify函数转大写、-转_同时会依据 profile 设置手工注入debug_assertions并跳过 rustc 查询中的同名值。构建环境OUT_DIRbuild script 所有输出与中间产物的目录位于该包的构建目录内、对包唯一。Cargo不会在构建间清空或重置它内容可能跨重编译保留build script 不应假设OUT_DIR为空需自行管理创建的文件。它仅在 build script 执行与 crate 编译期间设置运行时不可用对应源码 src/compiler/custom_build.rsTARGET当前编译的目标 tuple原生代码应针对它编译HOSTrustc 编译器的 host tupleNUM_JOBS顶层并行度可传给make -j之类的系统。注意这是历史遗留变量新版 Cargo 并不需要make -j改为将MAKEFLAGS设为CARGO_MAKEFLAGS内容即可激活 jobserver 供子 make 使用DEBUG将生成任何 debug 信息时为true否则falseOPT_LEVEL当前 profile 对应opt-level的值PROFILErelease 构建为release其余为debug依据 profile 是否继承自dev/release。不推荐使用该变量OPT_LEVEL等变量能更准确地反映实际设置DEP_links_key详见 build script 文档中links键的说明。编译器上下文RUSTC、RUSTDOCCargo 解析出的编译器与文档生成器路径供 build script 复用RUSTC_WRAPPERCargo 正在使用的 rustc 包装器若有RUSTC_WORKSPACE_WRAPPER对 workspace 成员生效的包装器若有——源码中两者设置/移除逻辑见 src/compiler/custom_build.rsRUSTC_LINKERCargo 为当前 target 解析出的链接器二进制路径若指定可通过.cargo/config.toml修改CARGO_ENCODED_RUSTFLAGSCargo 调用 rustc 时附带的额外标志以0x1f分隔自 Rust 1.55 起RUSTFLAGS从环境中移除脚本应改用本变量。路径消毒trim-pathsCARGO_TRIM_PATHS_SCOPEtrim-pathsprofile 选项的值。若 build script 把绝对路径引入构建产物如调用编译器用户可请求在各类产物中将其消毒常见需处理的路径包括OUT_DIR、CARGO_MANIFEST_DIR、CARGO_MANIFEST_PATH及 build script 引入的其他路径如 include 目录。为向前兼容build script 应接受逗号分隔的 scope 列表CARGO_TRIM_PATHS_REMAPCargo 传给编译器的fromto路径重映射对以平台路径分隔符连接trim-paths为none时为空。build script 可把这些映射转发给 C/C 编译器如通过cc的-ffile-prefix-map使路径消毒与构建其余部分保持一致。两者的注入见 src/compiler/custom_build.rsCARGO_TRIM_PATHS_REMAP由trim_paths_remap计算生成。cargo test 与第三方子命令cargo test 专属变量CARGO_BIN_EXE_name在运行集成测试或 benchmark 时设置指向二进制目标可执行文件的绝对路径name为二进制目标原名如CARGO_BIN_EXE_my-program除非二进制有未启用的必需 feature否则它会在测试构建时自动构建。运行时读取示例use std::env; let out_dir env::var(CARGO_BIN_EXE_foo).unwrap();第三方子命令可见的变量对放置于$PATH的第三方子命令即名为cargo-foobar的程序Cargo 暴露CARGO执行构建的 cargo 二进制路径CARGO_MAKEFLAGSCargo jobserver 实现所需的参数仅当 Cargo 检测到 jobserver 存在时才设置。若需更全面的环境信息可运行cargo metadata获取机器可读的项目/依赖数据。实战小结与最佳实践优先用配置键而非散落的环境变量多数行为既有环境变量也有 config 键配置文件更便于团队共享环境变量适合 CI 一次性覆盖注意其优先级高于 TOML 文件--config又高于环境变量。给 rustc 传标志用CARGO_ENCODED_RUSTFLAGS空格分隔的RUSTFLAGS在含引号/特殊字符时易出错0x1f分隔更健壮且 build script 内RUSTFLAGS已被移除。build script 中读 target 平台用CARGO_CFG_*不要用cfg!/#[cfg]它们检查的是 host。OUT_DIR不做清空假设build script 需自行幂等地管理其中文件。区分编译期与运行期env!(CARGO_PKG_*)在编译期求值CARGO_CFG_*、CARGO_FEATURE_*、OUT_DIR仅在 build script 运行时可用运行时程序无法读取。更多细节请继续查阅仓库内的权威来源doc/book/src/reference/environment-variables.md完整清单、doc/book/src/reference/config.md配置键与环境变量映射、doc/book/src/guide/cargo-home.mdCARGO_HOME 结构以及实现层 src/context/environment.rs环境快照、src/compiler/custom_build.rsbuild script 环境注入。赞分享开发工具包管理器CLI构建工具【免费下载链接】cargoThe Rust package manager项目地址https://gitcode.com/gh_mirrors/car/cargo点击查看免费下载相关推荐Cargo 环境变量完全指南Cargo 读取与设置的全部变量详解Cargo 环境变量完全指南Cargo 读取与设置的全部变量详解 导读 环境变量是 Cargo 与外部世界交互的桥梁一方面开发者可以通过设置环境变量覆盖开发工具包管理器CLI构建工具九大网盘直链怎么拿网盘直链下载助手五分钟上手指南九大网盘直链怎么拿网盘直链下载助手五分钟上手指南 用网盘网页版下载文件速度常卡在几十 KB/s等不了几分钟就想换方案。网盘直链下载助手LinkSwift前端Numba 环境变量完全指南从 .numba_config.yaml 到 NUMBA_* 全量配置解析Numba 环境变量完全指南从 .numba_config.yaml 到 NUMBA_ 全量配置解析 Numba 通过一组以 NUMBA_ 前缀开头的环境变量编译器高性能计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考