10.1 Cargo工具详解

Cargo 是 Rust 的官方构建系统和包管理器。它不仅是 Rust 生态系统的核心，也是每个 Rust 开发者日常工作中最常使用的工具。Cargo 负责项目的构建、依赖管理、测试、文档生成和发布等一系列任务，极大地简化了 Rust 项目的开发流程。

创建新项目

使用 cargo new 命令可以快速创建一个新的 Rust 项目。该命令会生成一个标准的项目目录结构和必要的配置文件。

cargo new my_project

执行上述命令后，Cargo 会创建一个名为 my_project 的目录，其中包含以下内容：

  • Cargo.toml：项目的清单文件，用于定义项目元数据、依赖项和构建配置。
  • src/main.rs：默认的入口文件，包含一个简单的 "Hello, world!" 程序。
  • .gitignore：自动生成的 Git 忽略文件（如果当前目录不在 Git 仓库中）。

如果需要创建一个库项目（而不是可执行程序），可以添加 --lib 标志：

cargo new my_library --lib

项目结构与 Cargo.toml

一个典型的 Cargo 项目结构如下：

my_project/
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── main.rs      # 或 lib.rs
│   └── bin/         # 可选，用于存放多个可执行文件
├── tests/           # 集成测试文件
├── examples/        # 示例代码
└── benches/         # 性能基准测试

Cargo.toml 文件是项目的核心配置文件，采用 TOML 格式。一个基本的 Cargo.toml 文件包含以下部分：

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"
description = "一个示例 Rust 项目"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[dev-dependencies]
criterion = "0.5"

[build-dependencies]
cc = "1.0"

[profile.release]
opt-level = 3
  • [package]：定义项目的基本信息，如名称、版本、使用的 Rust 版本（edition）等。
  • [dependencies]：声明项目运行时所需的第三方库及其版本约束。
  • [dev-dependencies]：声明仅在测试、示例或基准测试中使用的依赖。
  • [build-dependencies]：声明仅在构建脚本（build.rs）中使用的依赖。
  • [profile.release]：配置发布构建（--release）的优化级别等参数。

依赖管理

Cargo 使用 Cargo.toml 中的 [dependencies] 部分来管理项目的依赖。依赖可以来自 crates.io（Rust 官方的包注册中心）、Git 仓库或本地路径。

版本约束示例：

  • "1.0"：表示兼容 >=1.0.0 且 <2.0.0 的任何版本（SemVer 兼容）。
  • "^1.0"：与 "1.0" 相同，允许更新到 1.x.x 的最新版本。
  • "~1.2"：允许更新到 1.2.x 的最新版本，但不更新到 1.3.0。
  • ">=1.0, <2.0"：指定版本范围。
  • "=1.0.0"：锁定到特定版本。

添加依赖的方式：

  1. 手动编辑 Cargo.toml：直接在文件中添加依赖声明。

  2. 使用 cargo add 命令：这是更推荐的方式，它会自动更新 Cargo.toml 并下载依赖。

    cargo add serde
cargo add tokio --features full

当添加或修改依赖后，Cargo 会生成或更新 Cargo.lock 文件。Cargo.lock 会锁定所有依赖（包括传递依赖）的确切版本，确保所有开发者或构建环境使用完全相同的依赖树，从而实现可重现的构建。对于应用程序项目，Cargo.lock 应该被提交到版本控制系统；对于库项目，通常不提交。

构建与运行

Cargo 提供了几个核心命令来管理项目的生命周期：

  • cargo build：编译项目。默认生成调试版本（debug build），输出文件位于 target/debug/ 目录。
  • cargo build --release：编译优化后的发布版本，输出文件位于 target/release/ 目录。适用于性能敏感的最终产品。
  • cargo run：编译并运行项目。如果代码没有变化，Cargo 会跳过编译步骤，直接运行已有的可执行文件。
  • cargo check：快速检查代码是否能通过编译，但不生成可执行文件。这比 cargo build 快得多，常用于开发过程中快速验证代码的正确性。
  • cargo clean：删除 target/ 目录，清理所有构建产物。

测试与文档

  • cargo test：运行项目中的所有测试（包括单元测试、集成测试和文档测试）。这是 Rust 开发中非常重要的一个环节。
  • cargo doc：根据代码中的文档注释（///）生成 HTML 文档。生成的文档位于 target/doc/ 目录。
  • cargo doc --open：生成文档后自动在浏览器中打开。

发布与分发

  • cargo publish：将你的库包发布到 crates.io，供其他开发者使用。发布前需要登录 crates.io 并获取 API token。
  • cargo install：从 crates.io 或其他来源安装二进制 crate 到本地系统。例如，cargo install ripgrep 可以安装 rg 命令。

其他常用命令

  • cargo update：更新 Cargo.lock 文件中的依赖版本，使其符合 Cargo.toml 中的版本约束。
  • cargo search <query>：在 crates.io 上搜索包。
  • cargo tree：以树状图形式显示项目的依赖关系，有助于分析依赖冲突和包大小。
  • cargo fmt：使用 rustfmt 工具自动格式化代码。
  • cargo clippy：运行 clippy 代码检查工具，提供代码改进建议和潜在错误警告。

工作空间（Workspaces）

对于大型项目，Cargo 支持工作空间功能，允许你将一个项目拆分为多个相互关联的子包（crate）。通过在根目录的 Cargo.toml 中定义 [workspace] 成员，可以统一管理所有子包的构建、测试和依赖。

[workspace]
members = [
    "crate-a",
    "crate-b",
    "shared-utils",
]

工作空间内的所有子包共享同一个 Cargo.lock 文件和 target/ 目录，确保依赖版本的一致性。

总结

Cargo 是 Rust 生态系统中不可或缺的一部分。它提供了一套完整、一致且高效的开发工具链，从项目初始化、依赖管理、构建测试到文档生成和发布，覆盖了软件开发的整个生命周期。熟练掌握 Cargo 的各项命令和配置，是成为一名高效 Rust 开发者的基础。

Last Updated::