探索 Rust 中的 Cargo 工作区

简介

欢迎来到Cargo 工作区。本实验是 Rust 书籍 的一部分。你可以在 LabEx 中练习你的 Rust 技能。

在本实验中，我们将探索 Cargo 的工作区功能，该功能通过将一个包拆分为多个库板条箱来帮助管理多个相关联的并行开发的包。

Skills Graph

Cargo 工作区

在第 12 章中，我们构建了一个包含一个二进制板条箱和一个库板条箱的包。随着项目的发展，你可能会发现库板条箱持续变大，并且你想要将你的包进一步拆分为多个库板条箱。Cargo 提供了一个名为 工作区 的功能，它可以帮助管理多个并行开发的相关包。

创建工作区

一个 工作区 是一组共享同一个 Cargo.lock 文件和输出目录的包。让我们使用一个工作区来创建一个项目 —— 我们将使用简单的代码，这样就能专注于工作区的结构。构建工作区有多种方式，所以我们只展示一种常见的方式。我们将创建一个包含一个二进制包和两个库的工作区。这个二进制包将提供主要功能，并依赖于这两个库。一个库将提供一个 add_one 函数，另一个库提供一个 add_two 函数。这三个板条箱将属于同一个工作区。我们先为工作区创建一个新目录：

mkdir add
cd add

接下来，在 add 目录中，我们创建将配置整个工作区的 Cargo.toml 文件。这个文件不会有 [package] 部分。相反，它将以一个 [workspace] 部分开头，通过指定包含我们二进制板条箱的包的路径，我们可以将成员添加到工作区；在这种情况下，那个路径是 adder：

文件名：Cargo.toml

[workspace]

members = [
    "adder",
]

接下来，我们通过在 add 目录中运行 cargo new 来创建 adder 二进制板条箱：

$ cargo new adder
     Created binary (application) `adder` package

此时，我们可以通过运行 cargo build 来构建工作区。你 add 目录中的文件应该如下所示：

├── Cargo.lock
├── Cargo.toml
├── adder
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── target

工作区在顶层有一个 target 目录，编译后的工件将被放置到这个目录中；adder 包没有它自己的 target 目录。即使我们在 adder 目录中运行 cargo build，编译后的工件仍然会放在 add/target 中，而不是 add/adder/target。Cargo 以这种方式构建工作区中的 target 目录，是因为工作区中的板条箱旨在相互依赖。如果每个板条箱都有自己的 target 目录，那么每个板条箱都必须重新编译工作区中的其他每个板条箱，以便将工件放在自己的 target 目录中。通过共享一个 target 目录，板条箱可以避免不必要的重新构建。

在工作区中创建第二个包

接下来，让我们在工作区中创建另一个成员包，并将其命名为 add_one。修改顶层的 Cargo.toml 文件，在 members 列表中指定 add_one 路径：

文件名：Cargo.toml

[workspace]

members = [
    "adder",
    "add_one",
]

然后生成一个名为 add_one 的新库板条箱：

$ cargo new add_one --lib
Created library $(add_one) package

现在你的 add 目录应该有以下这些目录和文件：

├── Cargo.lock
├── Cargo.toml
├── add_one
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── adder
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── target

在 add_one/src/lib.rs 文件中，让我们添加一个 add_one 函数：

文件名：add_one/src/lib.rs

pub fn add_one(x: i32) -> i32 {
    x + 1
}

现在我们可以让包含二进制文件的 adder 包依赖于包含我们库的 add_one 包。首先，我们需要在 adder/Cargo.toml 中添加对 add_one 的路径依赖：

文件名：adder/Cargo.toml

[dependencies]
add_one = { path = "../add_one" }

Cargo 不会假设工作区中的板条箱会相互依赖，所以我们需要明确指定依赖关系。

接下来，让我们在 adder 板条箱中使用 add_one 函数（来自 add_one 板条箱）。打开 adder/src/main.rs 文件，在顶部添加一条 use 语句，将新的 add_one 库板条箱引入作用域。然后修改 main 函数来调用 add_one 函数，如清单 14 - 7 所示。

文件名：adder/src/main.rs

use add_one;

fn main() {
    let num = 10;
    println!(
        "Hello, world! {num} plus one is {}!",
        add_one::add_one(num)
    );
}

清单 14 - 7：在 adder 板条箱中使用 add_one 库板条箱

让我们通过在顶层的 add 目录中运行 cargo build 来构建工作区！

$ cargo build
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished dev [unoptimized + debuginfo] target(s) in 0.68s

要从 add 目录运行二进制板条箱，我们可以使用 -p 参数和包名，通过 cargo run 指定我们想要运行的工作区中的包：

$ cargo run -p adder
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
     Running `target/debug/adder`
Hello, world! 10 plus one is 11!

这将运行 adder/src/main.rs 中的代码，该代码依赖于 add_one 板条箱。

在工作区中依赖外部包

注意，工作区在顶层只有一个 Cargo.lock 文件，而不是在每个板条箱的目录中都有一个 Cargo.lock。这确保了所有板条箱都使用所有依赖项的相同版本。如果我们将 rand 包添加到 adder/Cargo.toml 和 add_one/Cargo.toml 文件中，Cargo 会将这两个文件中的依赖项解析为 rand 的同一个版本，并将其记录在一个 Cargo.lock 中。使工作区中的所有板条箱使用相同的依赖项意味着这些板条箱将始终相互兼容。让我们将 rand 板条箱添加到 add_one/Cargo.toml 文件的 [dependencies] 部分，这样我们就可以在 add_one 板条箱中使用 rand 板条箱：

文件名：add_one/Cargo.toml

[dependencies]
rand = "0.8.5"

现在我们可以在 add_one/src/lib.rs 文件中添加 use rand;，并且通过在 add 目录中运行 cargo build 来构建整个工作区，这将引入并编译 rand 板条箱。我们会得到一个警告，因为我们没有引用引入作用域的 rand：

$ cargo build
    Updating crates.io index
  Downloaded rand v0.8.5
   --snip--
   Compiling rand v0.8.5
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished dev [unoptimized + debuginfo] target(s) in 10.18s

顶层的 Cargo.lock 现在包含了 add_one 对 rand 的依赖信息。然而，即使 rand 在工作区的某个地方被使用了，除非我们也将 rand 添加到工作区中其他板条箱的 Cargo.toml 文件中，否则我们不能在这些板条箱中使用它。例如，如果我们在 adder 包的 adder/src/main.rs 文件中添加 use rand;，我们会得到一个错误：

$ cargo build
   --snip--
   Compiling adder v0.1.0 (file:///projects/add/adder)
error[E0432]: unresolved import `rand`
 --> adder/src/main.rs:2:5
  |
2 | use rand;
  |     ^^^^ no external crate `rand`

要解决这个问题，编辑 adder 包的 Cargo.toml 文件，并表明 rand 也是它的一个依赖项。构建 adder 包会将 rand 添加到 Cargo.lock 中 adder 的依赖项列表中，但不会下载额外的 rand 副本。Cargo 确保了工作区中每个使用 rand 包的包中的每个板条箱都将使用相同的版本，这为我们节省了空间，并确保了工作区中的板条箱相互兼容。

向工作区添加测试

作为另一项改进，让我们在 add_one 板条箱中添加对 add_one::add_one 函数的测试：

文件名：add_one/src/lib.rs

pub fn add_one(x: i32) -> i32 {
    x + 1
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        assert_eq!(3, add_one(2));
    }
}

现在在顶层的 add 目录中运行 cargo test。在像这样构建的工作区中运行 cargo test 将运行工作区中所有板条箱的测试：

[object Object]

输出的第一部分表明 add_one 板条箱中的 it_works 测试通过了。下一部分表明在 adder 板条箱中未找到测试，最后一部分表明在 add_one 板条箱中未找到文档测试。

我们还可以通过使用 -p 标志并指定要测试的板条箱名称，从顶层目录为工作区中的一个特定板条箱运行测试：

[object Object]

此输出表明 cargo test 仅运行了 add_one 板条箱的测试，而未运行 adder 板条箱的测试。

如果你将工作区中的板条箱发布到 https://crates.io，工作区中的每个板条箱都需要单独发布。与 cargo test 类似，我们可以通过使用 -p 标志并指定要发布的板条箱名称来发布工作区中的特定板条箱。

作为额外的练习，以与添加 add_one 板条箱类似的方式向此工作区添加一个 add_two 板条箱！

随着你的项目不断发展，可以考虑使用工作区：与一大块代码相比，它提供了更易于理解、更小的独立组件。此外，如果多个板条箱经常同时更改，将它们保存在工作区中可以使板条箱之间的协调更加容易。

总结

恭喜你！你已经完成了 Cargo 工作区实验。你可以在 LabEx 中练习更多实验来提升你的技能。