Cargo 工作空间

在第 12 章中，我们构建了一个包含二进制 crate 和库 crate 的包。随着项目的发展，你可能会发现库 crate 不断变大，你希望将包进一步拆分成多个库 crate。Cargo 提供了一个称为 工作空间 的功能，可以帮助管理同时开发的多个相关包。

创建工作空间

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

$ mkdir add
$ cd add

接下来，在 add 目录中，我们创建 Cargo.toml 文件，用于配置整个工作空间。这个文件不会有 [package] 部分。相反，它将以一个 [workspace] 部分开头，允许我们将成员添加到工作空间。我们还特意通过将 resolver 设置为 "3"，使用 Cargo 最新的解析器算法版本。

文件名: Cargo.toml

[workspace]
resolver = "3"

接下来，我们将在 add 目录中运行 cargo new 来创建 adder 二进制 crate

$ cargo new adder
    Creating binary (application) `adder` package
      Adding `adder` as member of workspace at `file:///projects/add`

在工作空间内运行 cargo new 还会自动将新创建的包添加到工作空间 Cargo.toml 文件中 [workspace] 定义的 members 键下，像这样

[workspace]
resolver = "3"
members = ["adder"]

此时，我们可以通过运行 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 目录，是因为工作空间中的 crate 旨在相互依赖。如果每个 crate 都有自己的 target 目录，那么每个 crate 都必须重新编译工作空间中的其他每个 crate，以便将其产物放入自己的 target 目录中。通过共享一个 target 目录，crate 可以避免不必要的重复构建。

在工作空间中创建第二个包

接下来，让我们在工作空间中创建另一个成员包，并将其命名为 add_one。生成一个新的库 crate 命名为 add_one

$ cargo new add_one --lib
    Creating library `add_one` package
      Adding `add_one` as member of workspace at `file:///projects/add`

顶层的 Cargo.toml 现在将包含 add_one 路径在 members 列表中

文件名: Cargo.toml

[workspace]
resolver = "3"
members = ["adder", "add_one"]

你的 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 不假定工作空间中的 crate 会相互依赖，因此我们需要明确说明依赖关系。

接下来，让我们在 adder crate 中使用 add_one 函数（来自 add_one crate）。打开 adder/src/main.rs 文件，修改 main 函数使其调用 add_one 函数，如列表 14-7 所示。

文件名: adder/src/main.rs 
fn main() {
    let num = 10;
    println!("Hello, world! {num} plus one is {}!", add_one::add_one(num));
}
列表 14-7: 在 adder crate 中使用 add_one 库 crate

让我们在顶层 *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` profile [unoptimized + debuginfo] target(s) in 0.22s

要从 *add* 目录运行二进制 crate，我们可以使用 -p 参数和包名来指定我们要运行工作空间中的哪个包，配合 cargo run 命令

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

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

在工作空间中依赖外部包

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

文件名: add_one/Cargo.toml

[dependencies]
rand = "0.8.5"

现在，我们可以将 use rand; 添加到 *add_one/src/lib.rs* 文件中，然后在 *add* 目录中运行 cargo build 构建整个工作空间，这将引入并编译 rand crate。我们会得到一个警告，因为我们没有使用引入作用域的 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)
warning: unused import: `rand`
 --> add_one/src/lib.rs:1:5
  |
1 | use rand;
  |     ^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

warning: `add_one` (lib) generated 1 warning (run `cargo fix --lib -p add_one` to apply 1 suggestion)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.95s

顶层的 *Cargo.lock* 现在包含关于 add_one 依赖 rand 的信息。然而，即使 rand 在工作空间中的某个地方被使用，除非我们在其他 crate 的 *Cargo.toml* 文件中也添加 rand，否则不能在工作空间的其他 crate 中使用它。例如，如果我们为 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 副本。只要工作空间中每个包的每个使用 rand 包的 crate 都指定了兼容的 rand 版本，Cargo 就会确保它们使用相同的版本，从而节省空间并确保工作空间中的 crate 相互兼容。

如果工作空间中的 crate 指定了同一依赖项的不兼容版本，Cargo 会分别解析它们，但仍会尝试解析尽可能少的版本。

向工作空间添加测试

为了进一步增强，让我们在 add_one crate 中添加一个针对 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 将运行工作空间中所有 crate 的测试

$ cargo test
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.20s
     Running unittests src/lib.rs (target/debug/deps/add_one-93c49ee75dc46543)

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/adder-3a47283c568d2b6a)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests add_one

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

输出的第一部分显示 add_one crate 中的 it_works 测试通过了。下一部分显示在 adder crate 中找到了零个测试，然后最后一部分显示在 add_one crate 中找到了零个文档测试。

我们也可以通过在顶层目录中使用 -p 标志并指定要测试的 crate 名称，来运行工作空间中某个特定 crate 的测试

$ cargo test -p add_one
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running unittests src/lib.rs (target/debug/deps/add_one-93c49ee75dc46543)

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests add_one

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

这个输出显示 cargo test 只运行了 add_one crate 的测试，而没有运行 adder crate 的测试。

如果你将工作空间中的 crate 发布到 crates.io，工作空间中的每个 crate 都需要单独发布。就像 cargo test 一样，我们可以通过使用 -p 标志并指定要发布的 crate 名称，来发布工作空间中的某个特定 crate。

作为额外的练习，按照与 add_one crate 类似的方式，向这个工作空间添加一个 add_two crate！

随着项目的增长，考虑使用工作空间：它可以让你使用更小、更容易理解的组件，而不是一大坨代码。此外，如果工作空间中的 crate 经常同时更改，将它们放在工作空间中可以使 crate 之间的协调更加容易。