rust-cargo-build

Rust Cargo 构建系统

将 Cargo 用作版本化包管理器、构建协调器和自动化接口。决策应基于项目实际使用的 Cargo 版本、MSRV、工作区根目录、目标和发布模式。以官方 Cargo Book 为权威依据；本技能聚焦于任务选择、执行和验证。

预检

运行最小相关子集：

rustc --version --verbose
cargo --version
cargo locate-project --workspace
cargo metadata --no-deps --format-version 1

确定：

• 根清单是一个包还是虚拟工作区；
• 声明的 edition、rust-version、解析器和锁文件策略；
• 所选包、目标、功能、配置文件和目标三元组；
• 依赖源、注册表配置和离线限制；
• 所请求的行为在已安装的 Cargo 版本上是否稳定。

路由到合适的参考资料

仅阅读当前任务所需的参考资料：

任务	参考资料
查找权威的 Cargo 指南、参考文档、命令或变更日志页面	官方文档索引
选择 Cargo 命令并了解其副作用	Cargo 命令索引
启动、构建、运行、测试、生成文档，或为包添加 CI	Cargo 指南工作流
配置包元数据及 lib/bin/example/test/bench 目标	清单和目标
配置依赖源、功能、覆盖项或解析器	依赖、功能和解析器
配置成员和继承的工作区字段	工作区
配置 .cargo/config.toml、环境变量、别名、网络或目标设置	配置和环境
调整 dev/release/自定义配置文件	配置文件
生成代码、编译原生依赖，或从 build.rs 发出 Cargo 指令	构建脚本
诊断重新构建、重复编译、缓存布局、耗时或未来不兼容问题	构建缓存和诊断
配置链接器、运行器或非主机目标	交叉编译
配置注册表、源替换、供应商目录、凭据或身份验证	注册表和身份验证
检查包内容、发布、管理所有者或撤回某个版本	打包和发布
围绕稳定版 Cargo JSON 或包 ID 构建脚本和工具	元数据和自动化
评估 cargo-features、-Z 或其他仅限 nightly 的行为	不稳定 Cargo 功能

核心工作流

1. 定位根目录 — 编辑前确认工作区根目录和生效的清单。
2. 声明兼容性 — 记录版本、MSRV、支持的目标、stable/nightly 策略和功能约定。
3. 检查生效状态 — 使用 cargo metadata、cargo tree 和生效的配置，而不是仅根据某一个清单推断。
4. 做出最小更改 — 优先采用惯用目标、增量式功能、工作区继承和稳定版 Cargo 行为。
5. 执行所需矩阵 — 明确选择包、目标、功能、配置文件和目标三元组。
6. 先诊断再优化 — 更改配置文件或缓存之前，先利用耗时、依赖边、详细输出和重新构建证据进行诊断。
7. 验证产物和副作用 — 检查生成的文件、包内容、锁文件更改、注册表目标和凭据处理。

决策规则

清单、MSRV 和 Resolver

• 不要将 edition 与 MSRV 等同；声明 package.rust-version 并测试对应的工具链。
• 将 resolver 视为适用于整个工作区。在虚拟工作区中明确设置。
• 根据已安装的 Cargo 文档或变更日志，核实 resolver 默认值和受版本限制的字段。
• 仅当 Cargo 的惯用路径不够用时，才保留显式的 target 表。

Cargo.lock 和可复现性

• 如有疑问，请提交 Cargo.lock；当前 Cargo Guide 默认建议将其纳入版本控制。
• 根据仓库的发布、CI 和依赖验证策略决定例外情况，而不是遵循笼统的“应用要提交，库不用提交”规则。
• 如果不得更改已提交的锁文件，请使用 --locked。
• 仅当必须同时禁止锁文件修改和网络访问时，才使用 --frozen。
• 审查锁文件差异；不要仅为绕过 CI 失败而删除锁文件或执行大范围更新。

依赖项和功能

• 将功能视为可叠加的，并使用 cargo tree -e features 验证统一结果。
• 使用特定于目标的依赖项进行平台选择；不要在目标依赖项表中使用 cfg(feature = "...")。
• 当可复现性有要求时，将 Git 依赖项固定到某个修订版本。
• 仅将 [patch]、源替换和 vendoring 用于文档规定的用途；不要将它们视为可以互换。

配置和环境

• 区分清单配置和分层的 Cargo 配置。
• 根据命令的工作目录确认 .cargo/config.toml 的查找位置。
• 不要将密钥放入已提交的配置或命令历史记录中。
• 将构建脚本和 proc macro 的主机设置，与最终构件使用的目标设置分开。

构建脚本

• 仅将生成的构件写入 OUT_DIR。
• 精确发出 cargo::rerun-if-changed 和 cargo::rerun-if-env-changed 指令。
• 确保输出可复现，并避免在构建期间访问网络。
• 将原生链接指令和 links 元数据视为公开的集成契约。

配置文件、缓存和诊断

• 衡量实际需要优化的工作流：check、增量开发、测试、CI、发布链接、运行时或二进制文件大小。
• 将配置文件定义保留在工作区根目录。
• 除非 Reference 文档说明了输出位置，否则将构建目录布局视为 Cargo 内部实现细节。
• 优先使用 cargo build --timings、cargo tree -d 和未来不兼容性报告，而非臆测性地删除缓存。

注册表和发布

• 区分注册表、源替换、目录源和 vendoring。
• 在登录或发布操作之前，先确定凭据提供程序和注册表身份。
• 发布前运行 cargo package --list 并验证软件包。
• 登录、更改所有者、发布、撤回版本或修改凭据，都必须获得明确授权。

Stable 和 Nightly

• 优先采用 stable Cargo 行为。
• 在建议使用 nightly 之前，明确指出具体的不稳定功能、调用形式、跟踪 issue、回退方案和移除条件。
• 切勿将 cargo-features、-Z 或 [unstable] 配置说成 stable 功能。
• 重新检查变更日志，因为不稳定接口可能会稳定、变更或消失。

验证

调整矩阵，不要盲目运行不受支持的组合：

cargo metadata --format-version 1
cargo fmt --all --check
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo package --list

如果仓库已提交或要求使用锁文件，请在受支持的 Cargo 命令后追加 --locked。如果工作区有意排除某些功能或目标，请定义明确的矩阵并记录原因。

边界

• Crate 选择、公告、许可证、禁用项和供应链策略 → rust-dependencies
• 工作区和 crate 拓扑 → rust-workspace
• 测试架构、测试夹具、属性测试和覆盖率 → rust-testing
• rustdoc 内容和文档架构 → rust-documentation
• rustfmt、Clippy 策略和 Edition 迁移 → rust-style-clippy
• 运行时性能和内存分配行为 → rust-performance
• API 兼容性和版本升级决策 → rust-semver
• 嵌入式目标运行时和硬件集成 → rust-embedded

即使更高层级的决策属于其他技能，Cargo 命令的具体机制仍可在此讨论。

完成标准

• 确定生效的工作区、Cargo 版本、MSRV、目标、功能和配置文件上下文。
• 针对与版本相关的行为，链接相关的官方 Cargo 页面。
• 区分稳定行为和 nightly 实验。
• 验证生效的依赖关系图和配置。
• 确保可复现性和凭据安全。
• 在宣布成功前，确认制品、软件包或注册表的副作用。

数据隐私

此技能不会收集、存储或传输用户数据。请将注册表令牌、Git 凭据、环境变量、生成的制品和软件包内容视为可能包含敏感信息。