[!info] related notes

• 所属 MOC: Rust MOC, 工具链与工程结构 MOC
• 安装: 安装 Rust 并运行第一个程序
• 命令: Cargo 命令速查
• 工程结构: Rust Cargo workspace
• 相关工具: Rustup, Rust

Cargo

这是什么

Cargo 是 Rust 官方工具链中的项目构建与包管理工具。

可以把它放在下面这条链里理解：

rustup
→ 安装/切换 Rust toolchain

Cargo
→ 描述项目
→ 解析依赖
→ 调用 rustc 构建
→ 运行测试 / 文档 / 发布工作流

rustc
→ 真正编译 Rust 源码

Cargo 不是 Rust 编译器本身。

核心对象

Cargo.toml

项目 manifest，表达：

• package / workspace 元数据；
• dependencies；
• features；
• build/profile 配置；
• workspace members 等。

它更接近项目的声明性 Source of Truth。

Cargo.lock

记录依赖解析后的具体版本结果，用于让同一依赖图更可重复。

是否提交 lockfile 要结合 crate 类型和团队策略理解，而不是简单把它当临时缓存。

target/

默认构建产物与中间缓存目录。

它是可再生成的 build artifact，不应和项目源码/依赖声明混为一谈。

crates.io / registry

Cargo 可以从 registry 获取 crate，并处理依赖解析、下载与构建。

Cargo 主要负责什么

项目初始化
依赖管理
构建 / check / run
测试 / benchmark
文档
workspace
feature / profile
package / publish

具体命令统一维护在 Cargo 命令速查，本页不维护第二份命令大全。

Cargo 与 rustc

最容易混淆的是：

rustc
= 编译器

Cargo
= 项目级构建/依赖/工作流入口

Cargo 会根据 manifest 和依赖图组织编译，再调用 rustc 完成具体 crate 的编译。

所以大型 Rust 工程通常直接通过 Cargo 工作，而不是手工逐个调用 rustc。

Workspace

多个 crate 可以被一个 Cargo workspace 组织：

repository
├─ Cargo.toml   ← workspace root
└─ crates/
   ├─ core/
   ├─ cli/
   └─ web/

workspace 主要用于共享项目级组织、依赖解析和构建工作流。

具体语义见 Rust Cargo workspace。

Feature 与 Profile

Cargo 还负责两个重要工程维度：

• features：控制可选能力/依赖组合；
• profiles：控制 dev/release 等构建配置。

它们都会影响最终编译图，但不应该被理解成运行时动态开关。

什么时候用 Cargo

几乎所有标准 Rust 项目都会以 Cargo 作为默认项目入口：

• 新建 crate；
• 管依赖；
• build/check/test；
• 多 crate workspace；
• 生成 docs；
• package / publish。

如果只是学习一个完全独立的单文件语法实验，可以直接 rustc；一旦进入真实项目，Cargo 通常就是默认工程入口。

局限与边界

• Cargo 不是通用 CI/CD 系统；
• Cargo 不替代 rustup 管理 toolchain；
• Cargo 不自动解决业务层模块边界设计；
• Cargo workspace 不等于所有 monorepo 问题都已经解决；
• registry / dependency resolution 与最终程序运行时是不同阶段。

使用入口

• 安装工具链：安装 Rust 并运行第一个程序
• 常用命令：Cargo 命令速查
• 多 crate：Rust Cargo workspace

官方入口

• Cargo Book: https://doc.rust-lang.org/cargo/
• crates.io: https://crates.io/