文档【免费下载链接】rfcsRFCs for changes to Rust项目地址https://gitcode.com/gh_mirrors/rf/rfcs点击查看免费下载本指南以 RFC 3176Cargo Multi-Dep ArtifactsFeature Namemultidep 为骨架系统讲解 Cargo 如何允许对同一 crate 声明多个依赖通过重命名依赖实现从而为不同目标target同时构建并获取二进制产物。读完你将掌握重命名依赖的声明语法、artifacttarget多目标组合配置、CARGO_ARTIFACT-TYPE_DIR_DEP与CARGO_ARTIFACT-TYPE_FILE_DEP_NAME环境变量的精确语义以及版本统一、feature 处理、Profile 覆盖等边界行为可直接用于构建跨平台固件、WebAssembly 辅助程序等多目标场景。背景与动机为什么需要同一 crate 依赖多次Cargo 对依赖图有一个长期存在的约束在单个 crate 的直接依赖中不允许对同一 crate 声明两个依赖——如果两个依赖都解析到同一版本Cargo 会将其视为错误。然而RFC 3028Cargo Binary DependenciesFeature Namebindeps 引入了artifact dependencies产物依赖允许 crate 依赖另一个 crate 编译出来的二进制bin、C 动态库cdylib或 C 静态库staticlib并可按指定target构建。由此产生一个真实痛点某些 crate 需要针对多个目标获取同一个 crate 编译出的二进制。RFC 3176 原文给出的典型场景是一个支持运行多种目标的虚拟机可能需要为每种目标平台准备对应的固件firmware。这些固件可能来自不同的 crate但也经常来自同一个 crate 为不同目标分别编译——例如同一份引导程序源码需要产出aarch64版、riscv64版和x86_64版。在没有本特性之前用户只能通过引入一个中间 crate把同一个 crate 构建两次间接塞进依赖树来绕过限制或者为每个目标手工维护一份依赖条目并自行拼接产物。RFC 3176 要解决的问题正是允许一个包在同一版本、同一 crate 上声明多个依赖只要每个依赖使用不同的重命名名称从而让同一 crate 可为多个目标各构建一份 artifact 依赖。需要明确本 RFC 的边界它不允许依赖同一 crate 的多个 semver 兼容版本只允许对完全相同的一个版本建立多个依赖条目。核心机制用重命名依赖实现多重依赖重命名依赖Renaming Dependencies回顾Cargo 早已支持重命名依赖在[dependencies]中给依赖指定一个与发布名不同的本地名称语法为[dependencies] 本地名称 { package 真实包名, version ... }重命名通常用于在代码中以更短的名字引用依赖、或在依赖树中区分不同来源的 crate。RFC 3176 在此基础上扩展了一个新用途只要重命名后的名称互不相同就可以对同一版本、同一 crate 声明多个依赖。RFC 原文给出的最小示例[dependencies] example1 { package example, version 1.2.3 } example2 { package example, version 1.2.3 }两个依赖条目都指向examplecrate 的1.2.3版本但分别以example1、example2作为本地名称Cargo 便会同时提供两个入口。这在需要在代码的不同部分以两个不同名称引用同一 crate 时非常有用。多目标 artifact 依赖核心实战配置将这一机制与 artifact 依赖、target字段结合即得到本 RFC 的核心使用形态。RFC 原文给出的多目标固件示例[dependencies] example_arm { package example, version 1.2.3, artifact bin, target aarch64-unknown-none } example_riscv { package example, version 1.2.3, artifact bin, target riscv64imac-unknown-none-elf } example_x86 { package example, version 1.2.3, artifact bin, target x86_64-unknown-none }逐字段解读package example三个条目指向同一个crateversion 1.2.3三个条目要求同一个版本这是合法的前提——RFC 只允许同版本的多重依赖若解析到不同版本则仍按原规则处理artifact bin声明 artifact 依赖要求构建该 crate 的二进制产物对应依赖 crate manifest 中的[[bin]]段。RFC 3028 还支持cdylib、staticlib以及数组形式artifact [bin, cdylib]和bin:某个二进制名的精确指定形式详见 RFC 3028 的 Reference 部分target ...为每个条目指定不同的编译目标例如aarch64-unknown-noneARM 无 OS 环境、riscv64imac-unknown-none-elfRISC-V、x86_64-unknown-nonex86_64。Cargo 会为每个条目分别构建example的二进制并以各自指定的重命名名称将产物目录提供给当前 crate注意编译目标的写法riscv64imac-unknown-none-elf在环境变量名中会按 Cargo 规则转换为riscv64imac_unknown_none_elf下划线替换连字符example_arm对应CARGO_BIN_DIR_EXAMPLE_ARMexample_riscv对应CARGO_BIN_DIR_EXAMPLE_RISCVexample_x86对应CARGO_BIN_DIR_EXAMPLE_X86。这样构建脚本或编译期代码就能精确拿到每个目标平台的产物目录将其嵌入include_bytes!等或打包进最终产物。环境变量规则详解目录变量与文件变量RFC 3176 明确对于每个 artifact 依赖Cargo 都提供与 RFC 3028 一致的标准环境变量集合本 RFC 只是让同一 crate 的多个重命名条目各自独立获得这套变量。目录变量CARGO_ARTIFACT-TYPE_DIR_DEPARTIFACT-TYPE依赖声明的artifact类型的大写形式如BIN、CDYLIB、STATICLIBDEP你给依赖指定的名称重命名后的本地名称而非原始包名。与 Cargo 其他环境变量一致依赖名称会转为大写、连字符替换为下划线。该变量指向包含该依赖全部产物的目录。典型用途把目录加入$PATH或$LD_LIBRARY_PATH后再调用外部构建系统或脚本。RFC 3028 中的经典示例是CARGO_BIN_DIR_CMAKE。文件变量CARGO_ARTIFACT-TYPE_FILE_DEP_NAMEDEP同样是重命名后的依赖名称转换规则同上NAMEartifact 在提供方 crate中的名字如某个[[bin]]的名字或[lib]的库名不会被任何规则改写——可能保持小写、可能包含连字符该变量给出具体某个 artifact 的完整路径。关键语义RFC 3176 特别强调重命名名称决定DEP部分但不影响NAME部分。也就是说同一个 crate 为不同目标构建出的二进制其文件级变量表现为CARGO_BIN_FILE_EXAMPLE_ARM_mybin CARGO_BIN_FILE_EXAMPLE_RISCV_mybin CARGO_BIN_FILE_EXAMPLE_X86_mybinNAME如mybin保持不变变化的只是DEP前缀。这保证了每个目标的产物都能被精确寻址又不会因重命名而破坏产物的原始命名。RFC 3028 还补充了一个便捷规则若 artifact 名字与原始包名一致Cargo 会额外提供去掉_NAME后缀的变量副本。例如cmakecrate 提供名为cmake的二进制时CARGO_BIN_FILE_CMAKE与CARGO_BIN_FILE_CMAKE_cmake同时可用。这一规则对多重依赖同样适用。变量注入的构建阶段RFC 3028 中规定了不同依赖段的环境变量注入位置多重依赖沿用同一套规则[build-dependencies]中的 artifact 依赖变量注入build.rs脚本通过std::env::var_os读取路径可能不是合法 UTF-8[dependencies]中的 artifact 依赖变量在 crate 编译期注入通过env!读取[dev-dependencies]中的 artifact 依赖变量在编译 examples、tests、benchmarks 时注入通过env!读取。一个完整的build.rs消费示例源自 RFC 3028 的风格// build.rs use std::{env, process::Command}; fn main() { // 直接拿到某个目标平台的二进制路径 let riscv_bin env::var_os(CARGO_BIN_FILE_EXAMPLE_RISCV_mybin) .expect(riscv binary missing); let mut cmd Command::new(riscv_bin); assert!(cmd.status().expect(run failed).success()); // 或者把产物目录加入 PATH let dir env::var_os(CARGO_BIN_DIR_EXAMPLE_ARM).expect(arm artifacts dir); // dir 加入 PATH 后供其他构建步骤使用…… }版本统一Version Unification语义RFC 3176 明确规定多重依赖参与版本统一的方式与 Cargo 在完整依赖树中统一版本的方式完全一致允许同一 crate 的多个 semver 兼容版本不得共存依赖树中一个 crate 只能出现一个 semver 兼容版本允许同一 crate 的多个semver 不兼容版本可以共存例如0.1.7和1.2.4依赖条目中的版本字符串不必逐字符相同只要最终解析到同一个版本即可。因此example1 { package example, version 1.2.3 }与example2 { package example, version 1.2.3 }合法是因为二者解析结果相同但1.2.3与1.2.4这样的不同解析结果仍会按既有规则报错或产生多版本共存。本 RFC 只是放宽了同一 crate 同一版本只能有一个直接依赖条目的限制。需要特别指出Cargo 不会在不同目标的依赖之间统一 feature。同一个依赖树中可以同时存在对同一 crate 的普通依赖与多个 artifact 依赖且普通依赖与各目标 artifact 依赖可以各自启用不同的 feature 集。这为同一个 crate 为不同平台编译不同特性保留了灵活性。构建行为细节多目标 多份构建当同一 crate 存在多个target不同的 artifact 依赖时Cargo 会为每个指定的target分别构建该依赖并把每份构建结果通过对应的重命名名称提供给当前 crate。为多目标构建 artifact 依赖可能会连带构建多份其他传递依赖——这些传递依赖同样遵循依赖树内的统一规则即在各自的目标维度内统一而不是跨目标强制统一。artifact 与 target 的自由组合同一 crate 的多个依赖条目可以指定不同的artifact值例如一个条目只要二进制、另一个条目要cdylib也可以指定不同的target值。Cargo 会按如下规则处理对给定的一个target将该 target 下所有条目的 artifact 需求合并一次性构建该目标所需的所有指定产物为某个 target 请求特定 artifact不影响为另一个 target 构建的产物集合。换言之example_arm { ..., artifact bin, target aarch64-unknown-none }与example_arm2 { ..., artifact cdylib, target aarch64-unknown-none }这类组合会被合并到同一个 ARM 目标构建中而example_x86的产物与 ARM 目标完全独立。Profile 覆盖的边界Profile overrides配置覆盖按原始 crate 名package 名指定而非依赖的重命名名称。因此本 RFC 当前不支持为不同的 artifact 依赖条目分别覆盖不同的 Profile 设置——无论你对同一个 crate 声明了多少个重命名条目它们共享同一套按原始包名匹配的 Profile 覆盖。这一点既是当前实现的一个限制也是 RFC 后续演进方向之一见下文未来可能性。使用夜间选项-Z multidep在本特性稳定之前需要向cargo传入仅夜间版可用的选项cargo nightly build -Z multidep若cargo遇到同一 crate 的多重依赖、但未指定该选项会继续按原有行为报错错误语义与当前同一版本同一 crate 出现多个直接依赖的报错一致。与之对照前置的 artifact 依赖特性在稳定前也依赖-Z bindeps见 RFC 3028。如果你在同一份Cargo.toml中同时使用二者需要同时确认对应的夜间选项。注意上述内容以本 RFC 文档写作时点2021 年的状态为准特性是否已随某个 Cargo 版本稳定、以及当前是否仍需夜间选项请以 Cargo 官方参考文档cargo reference的 artifact 依赖一节和当前工具链实际行为为准。设计取舍与备选方案RFC 3176 详细记录了几个关键设计决策理解它们有助于正确使用与评估该特性。为何不采用target 列表语法一个更简短的备选方案是允许在target字段中直接写一个列表例如example { package example, version 1.2.3, artifact bin, target [aarch64-unknown-none, riscv64imac-unknown-none-elf, x86_64-unknown-none] }RFC 否决了这一方案理由包括若一条依赖对应多个 targetCargo 必须把 target 名称并入提供给该依赖的环境变量如CARGO_BIN_DIR_...会显著复杂化 artifact 依赖的环境变量协议也会显著增加 Cargo 内部实现的复杂度而用不同名称拆分依赖的方式无论对 Cargo 内部还是对声明依赖的 crate 代码而言都更易于管理和引用。为何允许非 artifact 的多重依赖虽然本 RFC 的首要用例是 artifact 依赖但它顺带允许了同一 crate 同名版本、不同重命名名称的普通多重依赖即本文开头example1/example2的例子。RFC 认为这是无害扩展等价于use name1 as name2;之类的效果并明确表示如果这一扩展带来任何实质性复杂度可以轻易将特性限制为仅对 artifact 依赖生效而不损害首要用例。与引入中间 crate的替代方案对比在没有本特性时让依赖树包含同一 crate 的多个副本artifact 与否需要引入中间 crate 间接实现。RFC 指出本特性把这种能力下沉到单个 crate 的直接依赖层面从而避免为每个目标成倍地引入甚至需要发布琐碎的中间 crate——这对需要大量目标的场景尤其重要。代价Drawbacks该特性要求 Cargo 处理单个 crate 的直接依赖中存在同一 crate 的多份副本。虽然 Cargo 对完整依赖树中的多副本已有支持但当前会在单 crate 直接依赖这一层级直接拒绝多副本因此修改此约束可能需要在 Cargo 代码库中重做部分既有假设——这是实现上的主要成本。未来可能性RFC 3176 为后续演进预留了两个明确方向按依赖条目或按 target的 Profile 覆盖当前 Profile 覆盖按原始包名匹配无法对同一 crate 的不同重命名条目设置不同 Profile。未来扩展可以引入依赖名称或 target 维度允许为每条依赖分别指定 Profile 覆盖。构建选项的 target 维度指定构建某个 target 的 artifact 依赖时依赖方可能希望指定更多构建细节例如 target features 或 target 专属的二进制布局选项。目前 Cargo 通过.cargo/config.toml暴露此类选项而非Cargo.toml未来若支持在Cargo.toml中指定需要允许不仅按依赖名、还要按 target 来指定这些选项。与生态中其他 RFC 的关系RFC 3028Cargo Binary Dependencies本 RFC 的前置与基石。它定义了artifact bin | cdylib | staticlib、lib true、target字段、环境变量协议、-Z bindeps以及产物的目录布局target/TARGET/artifact/CRATE_NAME-METADATA_HASH/ARTIFACT_TYPE。RFC 3176 的所有环境变量与构建语义都建立在 3028 之上。RFC 0002RFC 流程两份 RFC 都是 Rust 生态substantial changes走 RFC 评审流程的产物相关流程说明见 RFC Book 的 README。小结RFC 3176multidep用一个极小的语法增量解决了真实的多目标产物依赖难题只要对同一 crate 的同一版本使用不同的重命名名称Cargo 就允许同时建立多个artifact依赖条目并为每个条目独立构建、独立注入环境变量。它既不改变版本统一规则也不跨目标统一 feature而是以重命名即区分的方式保持了 Cargo 内部与用户代码两侧的简洁性。对需要为 ARM、RISC-V、x86_64 等目标同时产出固件、引导程序或辅助二进制的项目这一特性把原本需要中间 crate 或手工多构建的繁琐流程收敛为一份清晰的Cargo.toml配置。赞分享文档【免费下载链接】rfcsRFCs for changes to Rust项目地址https://gitcode.com/gh_mirrors/rf/rfcs点击查看免费下载相关推荐htmlq 依赖管理Cargo 工作空间组织多 crate 项目htmlq 依赖管理Cargo 工作空间组织多 crate 项目 在 Rust 项目开发中依赖管理是保证代码质量和构建效率的关键环节。htmlq 作为一款类开发工具Rust RFC 1525 深度解析Cargo Workspace 如何统一多 crate 仓库的依赖版本与构建产物Rust RFC 1525 深度解析Cargo Workspace 如何统一多 crate 仓库的依赖版本与构建产物 导读 RFC 1525 https://文档Cargo Tree 依赖树可视化命令完全指南从依赖图、Features 追踪到重复依赖排查Cargo Tree 依赖树可视化命令完全指南从依赖图、Features 追踪到重复依赖排查 cargo tree 是 Cargo 内置的依赖关系可视化命令开发工具包管理器CLI构建工具上一篇突破性能瓶颈Milvus向量数据库优化实战指南下一篇Suricata IP Reputation 实战指南从信誉数据文件、配置调优到 iprep 规则匹配创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
