# Cargo 的其他方面与 Crates.io

**More About Cargo and Crates.io**

到目前为止，咱们只使用了 Cargo 的一些最基本特性，来构建、运行与测试所编写的代码，而 Cargo 可以完成多得多的事情。本章中，咱们将讨论他一些别的、更为先进的特性，来展示如何完成以下的这些事情：

- 经由不同发布配置文件，定制咱们的构建，customize your build through release profiles；
- 把库发布在 [crates.io](https://crates.io) 上；
- 使用工作区来组织大型项目，organize large projects with workspaces;
- 从 [crates.io](https://crates.io) 安装库；
- 使用定制命令来扩展 Cargo 。


相比咱们在本章会讲到的功能，Cargo 甚至能完成更多，因此对于 Cargo 全部特性的完整阐释，请参阅 [他的文档](https://doc.rust-lang.org/cargo/)。


## 使用不同发布配置文件，对构建进行定制

**Customizing Builds with Release Profiles**

在 Rust 中，所谓 *发布配置文件，release profiles*，是带有实现程序员对编译代码有着更多掌控的，一些预定义及可定制的配置文件。相对其他配置文件，每个配置文件都是被独立配置的。

Cargo 有两个主要发布配置文件：运行 `cargo build` 时 Cargo 用到的 `dev` 配置文件，与运行 `cargo build --release` 时 Cargo 用到的 `release` 配置文件。`dev` 配置文件被定义为有着用于开发的一些良好默认配置，而 `release` 配置文件有着用于发布构建的良好默认配置。

从咱们构建的输出中，这些配置文件名字或许不陌生：

```console
$ cargo build
    Finished dev [unoptimized + debuginfo] target(s) in 0.0s
$ cargo build --release
    Finished release [optimized] target(s) in 0.0s
```

其中 `dev` 及 `release`，即由编译器用到的不同配置文件。

Cargo 有着在咱们在项目的 `Cargo.toml` 文件中，未曾显式添加任何 `[profile.*]` 小节时，所适用的各个配置文件的默认设置。通过添加咱们打算定制的任何配置文件的 `[profile.*]` 小节，咱们就会覆盖掉默认设置的任何子集。比如，下面是 `dev` 与 `release` 配置文件中 `opt-level` 设置的默认值：

文件名：`Cargo.toml`

```toml
[profile.dev]
opt-level = 0

[profile.release]
opt-level = 3
```

这个 `opt-level` 设置项，控制了 Rust 将应用到咱们代码的优化数目，有着范围 `0` 到 `3` 的取值范围。应用更多优化会延长编译时间，因此若咱们是在开发过程中而频繁编译代码，那么即使产生出的代码运行较慢，咱们也会想要更少的优化来更快地编译。因此默认的 `opt-level` 就是 `0`。而在咱们已准备好发布咱们的代码时，那么就最好用更多时间来编译。咱们将只以发布模式编译一次，但会运行编译好的程序许多次，因此发布模式就以较长的编译时间，换取到运行较快的代码。那就是 `release` 配置文件的 `opt-level` 默认为 `3` 的原因。

通过在 `Cargo.toml` 中，给某个默认值添加不同的值，就可以覆盖掉这个默认值。比如，在打算于开发配置文件中使用优化级别 `1` 时，就可以把下面这两行，添加到项目的 `Cargo.toml`：

文件名：`Cargo.toml`

```toml
[profile.dev]
opt-level = 1
```

此代码会覆盖默认设置 `0`。现在当咱们运行 `cargo build` 时，Cargo 将使用 `dev` 配置文件的默认设置，加上咱们对 `opt-level` 的定制。由于咱们把 `opt-level` 设置为了 `1`，Cargo 将应用相比于默认设置更多，但不如发布构建那样多的优化。

对于各个配置文件的完整配置项清单与默认设置，请参阅 [Cargo 文档](https://doc.rust-lang.org/cargo/reference/profiles.html)。


## 将代码箱发布到 Crates.io

**Publishing a Crate to Crates.io**

咱们已将 [crates.io](https://crates.io) 上的一些包，用作了咱们项目的依赖，而通过发布自己的包，咱们还可以与其他人分享咱们自己的代码。位于 [crates.io](https://crates.io) 网站的代码箱登记，会分发咱们包的源码，因此其主要保存开放源码的代码。

Rust 与 Cargo，均有着令到咱们所发布的包，易于为他人找到并使用的一些特性。咱们将讲到其中一些特性，并讲解怎样发布包，how to publish a package。


### 制作有用的文档注释

**Making Useful Documentation Comments**

准确地为咱们的包编写文档，将帮助到其他使用者获悉怎样及何时来使用他们，因此投入时间来编写文档是值得的。第 3 章中，咱们曾讨论过如何使用双斜杠 `//`来注释 Rust 代码。Rust 还有用于文档的一种将生成 HTML 文档的特殊注释，而被方便地称作 *文档注释，documentation comment*。这些 HTML 会显示出公开 API 项目的文档注释内容，这些内容是为对了解怎样 *使用，use* 咱们的代码箱，而非咱们代码箱如何实现感兴趣的程序员所准备的。

文档注释用的是三斜杠 `///` 而非双斜杠，并支持用于格式化文本的 Markdown 写法。要把文档注释恰好放在他们要注释的项目前，而紧接着注释项目。下面清单 14-1 给出了名为 `cargo_features_demo` 代码箱中，`add_one` 函数的文档注释。

文件名：`src/lib.rs`

~~~rust
/// 将一加到所给数字。
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = cargo_features_demo::add_one(arg);
///
/// assert_eq! (6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}
~~~

*清单 14-1：函数的文档注释*

这里，咱们给到了 `add_one` 函数完成什么的描述，以标题 `Examples` 开始了一个小节，并随后提供了演示怎样使用 `add_one` 函数的代码。咱们可通过运行 `cargo doc` 命令，生成文档注释的 HTML 文档。这个命令会运行与 Rust 一起分发的 `rustdoc` 工具，并将生成的 HTML 文档放在 `target/doc` 目录中。

处于便利目的，运行 `cargo doc --open` 将构建出当前代码箱文档（以及咱们代码箱全部依赖的文档）的 HTML，并随后在 web 浏览器中打开得到的结果。导航到那个 `add_one` 函数，咱们将看到文档注释中的文本如何渲染出来，如下图片 14-01 中所示：

![`add_one` 函数的 HTML 文档](images/14-01.png)

*图 14-01：`add_one` 函数的 HTML 文档*

#### 经常用到的小节

**Commonly Used Sections**

咱们曾使用清单 14-1 中的 `# Examples`  Markdown 标题，来创建出 HTML 中带有标题 “Examples” 的小节。下面是代码箱作者们，经常在他们文档中用到的一些其他小节：

- **Panics**：被文档注释的函数可能终止运行的情形。那些不愿其程序终止运行的调用者，就应确保在这些情形下他们不会调用该函数；
- **Errors**：若函数返回了 `Result`，那么描述出可能发生的各种错误，及何种条件下会造成那些错误的返回，就能有效帮助到调用者，从而他们可以编写出以不同方式，处理不同类别错误的代码;
- **Safety**：若函数调用起来是 `unsafe` 的（在第 19 章咱们就会讨论到不安全），那么就应有一个解释为何该函数不安全，并说明该函数期望调用者要遵守哪些不变因素的小节，if the funciton is `unsafe` to call(we discuss unsafety in Chapter 19), there should be a section explaining why the function is unsafe and covering the invariants that the function expects callers to uphold。


多数的文档注释并不需要全部这些小节，但这仍不失为一个提醒咱们，关于咱们代码使用者将有兴趣了解的各方面的一个良好检查单。


#### 作为测试的文档注释

**Documentation Comments as Tests**

在文档注释中添加一些示例代码块，可以帮助演示怎样使用咱们的库，且这样做有着附带的好处，an additional bonus：运行 `cargo test` 将把文档中示例代码作为测试运行！带有示例的文档属实很好。而在文档编写好后，由于代码已被修改而造成示例不工作，也是极为糟糕的。当咱们以清单 14-1 中 `add_one` 函数的文档，运行 `cargo test`，就将在测试结果中看到这样一个小节：

```console
   Doc-tests cargo_features_demo

running 1 test
test src/lib.rs - add_one (line 7) ... ok

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

现在当咱们修改那个函数或者那个示例，从而让示例中的 `assert_eq!` 终止运行，并再次运行 `cargo tset` 时，咱们将看到文档测试，the doc tests，捕获到示例与代码不再相互同步！

> 注：此状况下的输出为：

```console
   Doc-tests cargo_features_demo

running 1 test
test src/lib.rs - add_one (line 7) ... FAILED

failures:

---- src/lib.rs - add_one (line 7) stdout ----
Test executable failed (exit status: 101).

stderr:
thread 'main' panicked at 'assertion failed: `(left == right)`
  left: `6`,
 right: `7`', src/lib.rs:7:1
stack backtrace:
   0:     0x5620cf499480 - std::backtrace_rs::backtrace::libunwind::trace::h32eb3e08e874dd27
                               at /rustc/897e37553bba8b42751c67658967889d11ecd120/library/std/src/../../backtrace/src/back                             trace/libunwind.rs:93:5
   // ...
  36:                0x0 - <unknown>



failures:
    src/lib.rs - add_one (line 7)

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

error: doctest failed, to rerun pass `--doc`
```

> 注：执行 `cargo test --doc`，将只运行文档注释中的示例代码。

#### 注释被包含所在项目

**Commenting Contained Items，代码箱、模组整体的注释**

`//!` 样式的文档注释，会把文档添加到包含注释的条目，而非注释之后的条目。咱们通常在代码箱根文件里（依惯例即 `src/lib.rs`），或模组里，添加这些文档注释，来将代码箱或模组作为整体，而为其编写文档，the style of doc comment `//!` adds documentation to the item contains the comments rather than to the items following the comments. We typically use these doc comments inside the crate root file(`src/lib.rs` by convention) or inside a module to document the crate or the module as a whole。

比如，要添加描述包含了 `add_one` 函数的 `cargo_features_demo` 代码箱目的的文档，咱们就要添加以 `//!` 开始的文档注释，到 `src/lib.rs` 文件的开头，如下清单 14-2 中所示：

文件：`src/lib.rs`

```rust
//! # Cargo 特性示例代码箱
//!
//! `cargo_features_demo` 是令到执行某些确切计算更便利
//! 的一些工具的集合。
//!

/// 将一加到所给数字。
// --跳过代码--
```

*清单 14-2：作为一个整体的 `cargo_features_demo` 代码箱的文档*

请注意由于咱们是以 `//!` 而非 `///` 开始的这些注释，因此在以 `//!` 开始的最后一行后，并无任何代码的，咱们是在给包含此注释的程序项目，而非紧接着此注释的程序项目编写文档。在此示例中，那个程序项目就是 `src/lib.rs` 文件，为代码箱根。这些注释描述了整个代码箱。

当咱们运行 `cargo doc --open` 时，这些注释将显示在 `cargo_features_demo` 代码箱文档的首页，he front page，位处代码箱公开项目的清单之上，如下图 14-02 中所示：

![渲染出的 `cargo_features_demo` 代码箱文档](images/14-02.png)

*图 14-02：渲染出的 `cargo_features_demo` 代码箱文档, 包括着将该代码箱作为整体描述的注释*

程序项目里的文档注释，用于对描述代码箱及模组尤其有用。使用他们来解释容器，the container，的整体目标，有助于咱们的用户们理解代码箱的组织结构。


### 使用 `pub use` 导出便利的公开 API

**Exporting a Convinient Public API with `pub use`**

在咱们发布代码箱时，公开 API 的结构是主要的考量。相比与咱们，使用咱们代码箱的人们对代码箱结构的没有那么熟悉，并在咱们的代码箱有着大型模组层次结构时，难于找到他们打算使用的部分。

在第 7 章中，咱们曾讲到过怎样使用 `pub` 关键字把一些程序项目构造为公开，与怎样使用 `use` 关键字，把程序项目带入到作用域。但是，咱们在开发某个代码箱时，对咱们有意义的组织结构（模组树），对于咱们的用户则可能不那么便利。咱们会打算把代码箱结构组织为包含多个级别的层次，但随后某个想要使用定义在层次结构深处类型的人，就可能在找出那个类型是否存在上遇到麻烦。他们可能还会对必须敲入 `use cargo_features_demo::some_module::another_module::UsefulType;`，而非敲入 `use cargo_features_demo::UsefulType;` 而感到恼火。

可喜的是，若代码箱组织结构 *不* 便于其他人在另一库中使用，咱们不必重新调整代码箱的内部组织：相反，咱们可通过使用 `pub use`，重新导出程序项目，而构造出一种不同于咱们私有组织结构的公开组织结构。重新导出，re-export，会取一处的公开程序项目，而在另一处将其构造为公开，就跟这个项目是在那另一处被定义过一样。

比如说，咱们构造了用于建模美术概念的一个名为 `art` 的库。这个库里有两个模组：包含了两个名为 `PrimaryColor` 与 `SeccondaryColor` 枚举的 `kinds` 模组，与包含了名为 `mix` 函数的 `utils` 模组，如下清单 14-3 中所示：

文件名：`src/lib.rs`

```rust
//! # art
//!
//! 建模诸多美术概念的一个库。

pub mod kinds {
    /// RYB 颜色模型下的主要颜色。
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// RYB 颜色模型下的次要颜色。
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// 结合两种等量的主要颜色，创建出
    /// 某种次要颜色。
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        // --跳过代码--
        SecondaryColor::Purple
    }
}
```

*清单 14-3：有着组织到 `kinds` 与 `utils` 两个模组中的一些程序项目的 `art` 库*

下图 14-03 展示了由 `cargo doc` 产生出的该代码箱文档首页，看起来的样子：

![列出 `kinds` 与 `utils` 两个模组的 `art` 代码箱文档首页](images/14-03.png)

*图 14-3：列出 `kinds` 与 `utils` 两个模组的 `art` 代码箱文档首页*


请注意 `PrimaryColor` 与 `SecondaryColor` 两个类型，及 `mix` 函数都未在首页上列出。要看到他们，咱们必须点击 `kinds` 与 `utils`。

依赖于这个库的另一代码箱，将需要把程序项目从 `art` 带入到作用域的 `use` 语句，与指明当前定义的模组结构。下面清单 14-4 给出了用到 `art` 代码箱中 `PrimaryColor` 与 `mix` 两个程序项目的代码箱示例：

文件名：`src/main.rs`

```rust
use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}
```

*清单 14-4：用到 `art` 代码箱以内部组织结构导出程序项目的代码箱*

> **注**：使用本地未发布代码箱的方法，是在 `Cargo.toml` 的 `[dependencies]` 小节中，列出要使用的本地未发布代码箱。参见 [How to use a local unpublished crate?](https://stackoverflow.com/a/33025972)

文件：`Cargo.toml`

```toml
// --跳过代码--

[dependencies]
art = { path = "../art" }
```

清单 14-4 中用到 `art` 代码箱代码的作者，不得不搞清楚 `PrimaryColor` 是在 `kinds` 模组中，及 `mix` 函数是在 `utils` 模组中。`art` 代码箱的模组结构（即模组树），相比于用到该代码箱的开发者，与在 `art` 代码箱上编写代码的开发者要更为密切。对于试图搞清楚怎样使用 `art` 代码箱的人来说，其内部组织结构并未包含任何有用信息，而因为要用到他的开发者，不得不搞明白要在那里去查看，且必须在 `use` 语句中指明那些模组名字，这反而会造成混乱。

要从公开 API 中移除内部组织结构，咱们可把清单 14-3 中 `art` 代码箱的代码，修改为添加一些 `pub use` 语句，来在顶层处重导出程序项目，to re-export the items at the top level，如下清单 14-5 中所示：

文件名：`src/lib.rs`

```rust
//! # art
//!
//! 建模诸多美术概念的一个库。

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds;
pub mod utils;
```

*清单 14-5：添加 `pub use` 语句来重导出程序项目*

如下图 14-04 中所示，`cargo doc` 为此代码箱所产生出的 API 文档，现在将在首页上列出并链接到重导出项，从而令到 `PrimaryColor` 与 `SecondaryColor` 两个类型及 `mix` 函数更易于找到。

![列出了重导出项目的 `art` 代码箱文档首页](images/14-04.png)

*图 14-4：列出重导出项的 `art` 代码箱文档首页*

`art` 代码箱的用户，依然可以像清单 14-4 中所演示的那样，发现及使用清单 14-3 的内部结构，或者他们可使用清单 14-5 中更为便利的结构，如下清单 14-6 中所示：

文件名：`src/main.rs`

```rust
use art::mix;
use art::PrimaryColor;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}
```

*清单 14-6：使用着 `art` 代码箱重导出项的程序*

其中有许多嵌套模组的情形下，以 `pub use` 在顶层重导出类型，可在用到该代码箱的人的体验方面，造成显著不同。`pub use` 的另一常见用途则是，为将依赖代码箱的定义构造为咱们自己代码箱公开 API 的一部分，而重导出当前代码箱中某个依赖的定义。

创建出有用的公开 API 结构，与其说是一门科学，不如说是一门艺术，而咱们可不断迭代，来找到对用户运作最佳的 API。选择 `pub use` 会给到咱们在内部组织代码箱方式上的灵活性，并解除了内部结构与呈现给代码箱用户的组织结构的耦合。请查看咱们曾安装的代码箱代码，来发现他们的内部结构，是否不同于其公开 API。


### 建立 Crates.io 帐号

在咱们能发布代码箱之前，咱们需要在 [crates.io](https://crates.io) 上创建帐号，并得到 API 令牌，an API token。而要这样做，就要访问 [crates.io](https://crates.io) 处的主页，并通过 GitHub 帐号登录。（目前 GitHub 帐号是必须的，但该站点今后可能会支持其他创建帐号途径。）在登录后，咱们就要访问 [https://crates.io/me/](https://creates.io/me/) 处的帐号设置，而获取自己的 API 密钥，API key。然后使用咱们的 API 密钥，运行 `cargo login` 命令，如下：

```console
$ cargo login abcdefghijklmnopqrstuvwxyz012345
```

此命令将告知 Cargo 咱们的 API 令牌，并在 `~/.cargo/credentials` 文件中本地存储起来。请注意此令牌是个 *秘密，secret*：不要与任何人分享。不论因何种缘故，与任何人分享了，咱们都应吊销他，并在 [crates.io](https://crates.io) 上生成新的令牌。

### 添加元数据到新代码箱

Adding Metadata to a New Crate**

假设咱们有了个打算发布的代码箱。在发布前，咱们将需要在代码箱的 `Cargo.toml` 文件的 `[package]` 小节中，添加一些元数据。

咱们的代码箱将需要一个独特的名字。当咱们在本地于代码箱上工作时，咱们可以给代码箱取任意喜欢的名字。但是，[crates.io](https://crates.io) 上代码箱的名字，则是以先到先得的原则分配的，allocated on a first-come, first-served basis。一旦某个代码箱名字已被占用，其他人就不能发布有着那个名字的代码箱。在尝试发布某个代码箱之前，咱们要检索一下打算使用的名字。若这个名字已被使用，咱们将需要找到另一名字，并编辑 `Cargo.toml` 文件中 `[package]` 小节下的 `name` 字段，来使用这个用作发布的新名字，像下面这样：

文件名：`Cargo.toml`

```toml
[package]
name = "guessing_game"
```

即使咱们已选了个独特的名字，当咱们此时运行 `cargo publish` 来发布这个代码箱时，仍将得到一条告警及随后的报错：


```console
cargo publish                                                                                          lennyp@vm-manjaro
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
   Packaging guessing_game v0.1.0 (/home/lennyp/rust-lang/guessing_game)
   Verifying guessing_game v0.1.0 (/home/lennyp/rust-lang/guessing_game)
   Compiling libc v0.2.132
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.16
   Compiling getrandom v0.2.7
   Compiling rand_core v0.6.3
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (/home/lennyp/rust-lang/guessing_game/target/package/guessing_game-0.1.0)
    Finished dev [unoptimized + debuginfo] target(s) in 3.55s
   Uploading guessing_game v0.1.0 (/home/lennyp/rust-lang/guessing_game)
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata
```

此报错是由于咱们缺失了一些重要信息：描述及许可证是必须的，由此人们就会明白咱们的代码箱完成的什么，及在何种条件下他们可以使用他。在 `Cargo.toml` 中，由于代码箱的描述，会与咱们的代码箱一起呈现在搜索结果中，因此请添加仅仅一两句话的描述。而对于 `license` 字段，则需要提供 *某个许可证标识符值，a licence identifier value*。[Linux 基金会的软件包数据交换站，Linux Foundation's Software Package Data Exchange, SPDX，spdx.org](http://spdx.org/licenses/) 列出了可供这个值使用的标识符。比如，为指明咱们已使用 MIT 许可证，授权咱们的软件包，就要添加 `MIT` 的许可证标识符：


文件名：`Cargo.toml`

```toml
[package]
name = "guessing_game"
license = "MIT"
```

若咱们打算使用某个未出现于 SPDX 中的许可证，咱们就需要把那种许可证的文本，放置于某个文件里，把这个文件包含在咱们的项目中，并于随后使用 `license-file` 来指出那个文件的名字，而不再使用 `license` 键，the `license` key。

至于哪种许可证适合于咱们的项目方面的指南，是超出这本书的范围的。Rust 社区的许多人，都以 Rust 项目同样的方式，即采用 `MIT OR Apache-2.0` 双重许可证，授权他们的项目。这种实践表明，咱们也可以通过 `OR` 来指定出多个许可证标识符，从而让咱们的项目有着多种许可证。

在添加了独特名字、版本号、代码箱描述及许可证后，已准备好发布项目的 `Cargo.toml`文件，就会看起来像下面这样：

文件名：`Cargo.toml`

```toml
[package]
name = "guessing_game"
license = "MIT"
version = "0.1.0"
description = "一个在其中猜出计算机所选数字的有趣游戏。"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
rand = "0.8.3"
```

[Cargo 文档](https://doc.rust-lang.org/cargo/) 介绍了为确保其他人能更容易发现并使用咱们代码箱，而可指明的别的一些元数据。


### 发布到 Crates.io

既然咱们已经创建了账号，保存了 API 令牌，选择了代码箱名字，并指定了必需的元数据，那么咱们就准备好发布了！发布代码箱，会上传特定版本到 [crates.io](https://crates.io)，供其他人使用。

因为发布是 *永久性的，permanent*，因此要当心。版本绝无可能被覆盖，且代码无法被删除。[crates.io](https://crates.io) 的一个主要目标，是要充当代码的永久存档，以便依赖于 [crates.io](https://crates.io) 中代码箱的所有项目构建都将持续工作。而允许版本的删除，就会令到实现那个目标几无可能。不过，在咱们可发布的代码箱版本数目上没有限制。

再度运行 `cargo publish` 命令。现在他就应成功了：

```console
$ cargo publish                                                                        lennyp@vm-manjaro
    Updating crates.io index
warning: manifest has no documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
   Packaging guessing_game-xfossdotcom v0.1.0 (/home/lennyp/rust-lang/guessing_game)
   Verifying guessing_game-xfossdotcom v0.1.0 (/home/lennyp/rust-lang/guessing_game)
   Compiling libc v0.2.132
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.16
   Compiling getrandom v0.2.7
   Compiling rand_core v0.6.3
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game-xfossdotcom v0.1.0 (/home/lennyp/rust-lang/guessing_game/target/package/guessing_game-xfossdotcom-0.1.0)
    Finished dev [unoptimized + debuginfo] target(s) in 2.73s
   Uploading guessing_game-xfossdotcom v0.1.0 (/home/lennyp/rust-lang/guessing_game)
```

恭喜！现在咱们就已与 Rust 社区分享了咱们的代码，且任何人都可将咱们的代码箱，添加为他们项目的依赖。

> 注：在 Crates.io 上的账号电子邮箱未验证时，将报出如下错误：

```console
Caused by:
  the remote server responded with an error: A verified email address is required to publish crates to crates.io. Visit https://crates.io/me to set and verify your email address.
```

### 发布既有代码箱的新版本

咱们完成咱们代码箱的修改，而准备好发布新版本时，咱们要修改 `Cargo.toml` 中所指定的 `version` 值并重新发布。请运用 [语义版本控制规则，Semantic Versioning rules](http://semver.org/)，根据咱们已做出修改的类别，来确定出恰当的下一版本编号为何。然后运行 `cargo publish` 来上传新版本。


### 使用 `cargo yank` 命令弃用 Crates.io 上的版本

**Depracating Versions from Crates.io with `cargo yank`**

尽管咱们无法移除代码箱的先前版本，但咱们可以阻止任何今后的项目，将其添加为新的依赖项。这在某个代码箱版本由于某种原因，或别的问题而损坏时是有用的。在诸如此类的情形下，Cargo 支持把某个代码箱版本 *抽出来*，in such situations, Cargo supports *yanking* a crate version。

抽出某个版本，在允许所有依赖该版本的既有项目继续工作的同时，会阻止新项目依赖那个版本。本质上，一次版本抽出，表示带有 `Cargo.lock` 的全部项目不会破坏，而任何今后生成的 `Cargo.lock` 文件，都将不使用被抽出的版本。

要抽出代码箱的某个版本，就要在咱们先前已发布的代码箱目录中，运行 `cargo yank` 并指定出要抽出的版本。比如，咱们曾发布了名为 `guessing_game` 代码箱的 `0.1.0` 版本，而打算抽出他，咱们就要在 `guessing_game` 的项目目录下，运行下面的命令：

```console
$ cargo yank --vers 0.1.0                                                           4s lennyp@vm-manjaro
    Updating crates.io index
        Yank guessing_game-xfossdotcom@0.1.0
```

通过把 `--undo` 添加到这个命令，咱们还可以撤销某次抽出，而允许项目开始再度依赖于某个版本：

```console
$ cargo yank --vers 0.1.0 --undo                                                    lennyp@vm-manjaro
    Updating crates.io index
      Unyank guessing_game-xfossdotcom@0.1.0
```

抽出版本，*不会* 删除任何代码。比如，其无法删除那些不小心上传的机密信息。若发生了机密信息被上传的情况，咱们必须立即重置这些机密信息。


## Cargo 工作区

**Cargo Workspaces**

在第 12 章中，咱们曾构建了个包含二进制代码箱和库代码箱的包，a package。随着咱们项目的持续开发，咱们会发现库代码箱会持续变大，而咱们就会想要把咱们的包，进一步拆分为多个库代码箱。Cargo 提供了可帮助管理多个齐头并进开发的相关包，名为 *工作区，workspace* 的特性。

> 注：总结 Rust 开发的层次结构如下：工作区，workspace -> 包，package -> 代码箱，crate -> 模组，module -> 语句，statement。

### 创建工作区

*工作区，a workspace* 是共享了同一 `Cargo.lock` 文件与输出目录的包集合。咱们来构造一个用到工作区的项目 -- 咱们将使用一些简单代码，这样咱们便可着重于工作区的结构。组织工作区有多种方式，因此咱们将只给出一种常见方式。咱们将会有包含着一个二进制代码箱，与两个库代码箱的一个工作区。其中的二进制代码箱，将提供主要功能，其将依赖于其中的两个库代码箱。而一个库代码箱将提供 `add_one` 函数，另一个则会提供 `add_two` 函数。这三个代码箱，都将是同一工作区的一部分。咱们将以创建出工作区目录开始：

```console
$ mkdir add
$ cd add
```

接下来，在 `add` 目录中，咱们就要创建出将对整个工作区加以配置的 `Cargo.toml` 文件。这个文件不会有 `[package]` 小节。相反，他会以 `[workspace]` 小节开始，其将允许咱们，通过指定出有着咱们的二进制代码箱的包路径，而把成员添加到工作区；在这个示例中，那个路径为 `adder`:

文件名：`Cargo.toml`

```toml
[workspace]
members = [
    "adder",
]
```

接着，咱们将通过在 `add` 目录里运行 `cargo new`，而创建出 `adder` 二进制代码箱：

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

到这里，咱们就可通过运行 `cargo build` 构建出工作区。`add` 目录下的文件，看起来应像下面这样：

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

在其顶层，工作区有个 `target` 目录，那些编译出的物件，the compiled artifacts，就会放入其中；`adder` 包没有自己的 `target` 目录。即使咱们在 `adder` 目录内运行 `cargo build`，那些编译出的物件，仍将出现在 `add/target` 中，而不是 `add/adder/target` 目录里。Cargo 之所以像这样来组织 `target` 目录，是因为工作区中的代码箱是为了依赖于彼此。若各个代码箱都有自己的 `target` 目录，那么为了把编译出的物件放在自己的 `target` 目录中，就不得不重新编译工作区中其他各个代码箱。经由共用一个 `target` 目录，代码箱就可以避免不必要的重新构建。


### 在工作区中创建第二个包

**Creating the Second Package in the Workspace**

接着，咱们来创建工作区中的另一个成员包，并将其叫做 `add_one`。请修改顶层的 `Cargo.toml`，在 `members` 清单中指明 `add_one` 的路径：

文件名：`Cargo.toml`

```toml
[workspace]

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

随后生成名为 `add_one` 的新库代码箱：

```console
$ cargo new add_one --lib                                                                        lennyp@vm-manjaro
     Created library `add_one` package
```

`add` 目录现在应该有这些目录与文件：

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

在 `add_one/src/lib.rs` 文件中，咱们来添加一个 `add_one` 函数：

文件名：`add_one/src/lib.rs`

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

现在咱们就可以让有着咱们二进制代码箱的 `adder` 包，依赖于有着咱们库代码箱的 `add_one` 包了。首先，咱们将需要把有关 `add_one` 的路径依赖，a path dependency，添加到 `adder/Cargo.toml`。

文件名：`adder/Cargo.toml`

```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`

```rust
use add_one::add_one;

fn main() {
    let num = 10;
    println!("你好，世界！{num} 加一为 {}!", add_one(num));
}
```

*清单 14-7：在 `adder` 代码箱中使用 `add_one` 库代码箱*

咱们来通过在 `add` 目录顶层运行 `cargo build`，构建工作区！

```console
$ cargo build                                                                                 lennyp@vm-manjaro
   Compiling add_one v0.1.0 (/home/lennyp/rust-lang/add/add_one)
   Compiling adder v0.1.0 (/home/lennyp/rust-lang/add/adder)
    Finished dev [unoptimized + debuginfo] target(s) in 0.40s
```

而要在 `add` 目录运行二进制代码箱，咱们可通过使用 `-p` 命令行参数，指明咱们打算允许工作区中的哪个包，及与 `cargo run` 运行的包名字：

```console
$ cargo run -p adder                                                                          lennyp@vm-manjaro
   Compiling adder v0.1.0 (/home/lennyp/rust-lang/add/adder)
    Finished dev [unoptimized + debuginfo] target(s) in 0.35s
     Running `target/debug/adder`
你好，世界！
        10 加 1 为 11!
```

这会运行 `adder/src/main.rs` 中的代码，其依赖于 `add_one` 代码箱。


### 于工作区中依赖外部代码箱

**Depending on an External Package in a Workspace**

请注意工作区只有一个在顶层的 `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`

```toml
rand = "0.8.3"
```

现在咱们便可把 `use rand;` 添加到 `add_one/src/lib.rs` 文件了，而通过在 `add` 目录中运行 `cargo build` 构建整个工作区，就会带入并编译 `rand` 代码箱。由于咱们没有引用咱们已带入到作用域中的 `rand`，因此咱们将得到一条告警：

```console
$ cargo build                                                                                 lennyp@vm-manjaro
    Updating crates.io index
  Downloaded rand_core v0.6.4
  Downloaded ppv-lite86 v0.2.17
  Downloaded getrandom v0.2.8
  Downloaded libc v0.2.137
  Downloaded 4 crates (681.6 KB) in 1.29s
   Compiling libc v0.2.137
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.17
   Compiling getrandom v0.2.8
   Compiling rand_core v0.6.4
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling add_one v0.1.0 (/home/lennyp/rust-lang/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

   Compiling adder v0.1.0 (/home/lennyp/rust-lang/add/adder)
    Finished dev [unoptimized + debuginfo] target(s) in 6.76s
```

顶层的 `Cargo.lock`，现在包含了有关 `add_one` 对 `rand` 的依赖信息。但是，即使 `rand` 在工作区中的某处被用到，除非把 `rand` 添加到其他代码箱的 `Cargo.toml` 文件，否则咱们就不能在其他代码箱中使用他。比如，若咱们把 `use rand;` 添加到 `adder` 包的 `adder/src/main.rs` 文件，咱们将得到一个报错：

```console
$ cargo build                                                                                 lennyp@vm-manjaro
   --跳过前面的告警--
   Compiling adder v0.1.0 (/home/lennyp/rust-lang/add/adder)
error[E0432]: unresolved import `rand`
 --> adder/src/main.rs:1:5
  |
1 | use rand;
  |     ^^^^ no external crate `rand`

For more information about this error, try `rustc --explain E0432`.
error: could not compile `adder` due to previous error
```

要修正这个错误，就也要编辑 `adder` 包的 `Cargo.toml` 文件，而表明 `rand` 是其依赖项。构建 `adder` 包就将把 `rand`，添加到 `Cargo.lock` 中 `adder` 的依赖项清单，但不会有额外的 `rand` 拷贝将被下载。Cargo 已确保工作区中，每个用到 `rand` 包的包中的每个代码箱，都将使用同一版本，从而给咱们节省空间，并确保工作区中的代码箱都将兼容于彼此。


### 添加测试到工作区

**Adding a Test to a Workspace**

为说明另一项改进，咱们来添加一个 `add_one` 代码箱里 `add_one::add_one` 函数的测试：

文件名：`add_one/src/lib.rs`

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

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

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

现在请于顶层的 `add` 目录中运行 `cargo test`。在像这样组织起来的工作区中，运行 `cargo test`，就会运行工作区中所有代码箱的测试：

```console
$ cargo test                                                                                                           lennyp@vm-manjaro
   Compiling add_one v0.1.0 (/home/lennyp/rust-lang/add/add_one)
   Compiling adder v0.1.0 (/home/lennyp/rust-lang/add/adder)
    Finished test [unoptimized + debuginfo] target(s) in 0.68s
     Running unittests src/lib.rs (target/debug/deps/add_one-837c2ad0efe6b80c)

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-2277ab1084738161)

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` 代码箱中的 `it_works` 测试通过了。下一小节显示，在 `adder` 代码箱中找到零个测试，而随后的最后小节，显示在 `add_one` 代码箱中找到零个文档测试。（*注*：二进制代码箱中不会有文档测试？）

咱们还可通过使用 `-p` 命令行标志，并指明要测试的代码箱名字，而在顶层目录处运行工作区中特定代码箱的测试：


```console
$ cargo test -p add_one                                                                                                lennyp@vm-manjaro
    Finished test [unoptimized + debuginfo] target(s) in 0.01s
     Running unittests src/lib.rs (target/debug/deps/add_one-837c2ad0efe6b80c)

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` 代码箱的测试，而未运行 `adder` 代码箱的测试。

若咱们把工作区中的代码箱发布到 `crates.io` ，工作区中的各个代码箱将需要被单独发布。与 `cargo test` 类似，咱们可通过使用 `-p` 命令行标志，并指明打算发布的代码箱名字，而发布工作区中的特定代码箱。

作为附加练习，请以与 `add_one` 代码箱类似方式，把 `add_two` 添加到这个工作区！

当咱们的项目日渐增长时，请考虑使用工作区：相比于一大块代码，要搞清楚较小的、单独的组件就更容易一些。再者，当代码箱经常同时被修改时，把这些代码箱保持在工作区中，就能令到他们之间的协作更容易。


## 使用 `cargo install` 安装二进制代码箱

**Installing Binaries with `cargo install`**

`cargo install` 命令允许咱们在本地安装和使用二进制的代码箱。这并不是要取代系统包，system packages；它的目的是为 Rust 开发者提供一种方便的方式来安装别人在 [crates.io](https://crates.io) 上分享的工具。请注意咱们只能安装有二进制目标的包，packages that have binary targets。所谓 *二进制目标，binary target*，即与本身为非可运行，而适合于在其他程序中包含的库目标，a libary target，相反，因为代码箱有着一个 `src/main.rs` 文件，或有着被指定为二进制的另一文件时，而创建出的可以运行的程序。通常，代码箱会在 `README` 文件中，有着关于其是否为库代码箱，还是有着二进制目标，或二者皆具方面的信息。

使用 `cargo install` 安装的全部二进制程序文件，都被存储在安装根的 `bin` 文件中，in the installation root's `bin` folder。在使用 `rustup.rs` 安装 Rust，且没做任何定制配置时，这个目录将是 `$HOME/.cargo/bin`。为能运行咱们使用 `cargo install` 安装的程序，就要确保那个目录在 `$PATH` 中。

> 注：可在任意位置运行 `cargo install` 命令，来安装 Crates.io 上的 Rust 二进制程序，这些程序都将被安装在 `$HOME/.cargo/bin` 下。若已安装了某个 Rust 程序后再安装他，那么就会有如下输出：

```console
$ cargo install ripgrep                                                                                              1m 4s lennyp@vm-manjaro
    Updating crates.io index
     Ignored package `ripgrep v13.0.0` is already installed, use --force to override
```

比如，咱们曾在第 12 章中提到，有个用于搜索文件，`grep` 工具的 Rust 实现 `ripgrep`。要安装 `ripgrep`，咱们可运行如下命令：

```console
$ cargo install ripgrep
    Updating crates.io index
  Installing ripgrep v13.0.0
   Compiling memchr v2.5.0
   Compiling cfg-if v1.0.0
   Compiling libc v0.2.137
   Compiling log v0.4.17
   Compiling proc-macro2 v1.0.47
   Compiling lazy_static v1.4.0
   Compiling regex-automata v0.1.10
   Compiling quote v1.0.21
   Compiling unicode-ident v1.0.5
   Compiling bstr v0.2.17
   Compiling syn v1.0.103
   Compiling aho-corasick v0.7.20
   Compiling regex-syntax v0.6.28
   Compiling serde_derive v1.0.147
   Compiling encoding_rs v0.8.31
   Compiling serde v1.0.147
   Compiling regex v1.7.0
   Compiling grep-matcher v0.1.5
   Compiling serde_json v1.0.89
   Compiling unicode-width v0.1.10
   Compiling fnv v1.0.7
   Compiling same-file v1.0.6
   Compiling once_cell v1.16.0
   Compiling thread_local v1.1.4
   Compiling globset v0.4.9
   Compiling textwrap v0.11.0
   Compiling encoding_rs_io v0.1.7
   Compiling memmap2 v0.5.8
   Compiling bitflags v1.3.2
   Compiling crossbeam-utils v0.8.14
   Compiling bytecount v0.6.3
   Compiling itoa v1.0.4
   Compiling ryu v1.0.11
   Compiling strsim v0.8.0
   Compiling termcolor v1.1.3
   Compiling clap v2.34.0
   Compiling grep-searcher v0.1.10
   Compiling atty v0.2.14
   Compiling base64 v0.13.1
   Compiling grep-printer v0.1.6
   Compiling grep-cli v0.1.6
   Compiling grep-regex v0.1.10
   Compiling ripgrep v13.0.0
   Compiling walkdir v2.3.2
   Compiling ignore v0.4.18
   Compiling grep v0.2.10
   Compiling num_cpus v1.14.0
    Finished release [optimized + debuginfo] target(s) in 1m 09s
  Installing /home/lennyp/.cargo/bin/rg
   Installed package `ripgrep v13.0.0` (executable `rg`)
```

输出的倒数第二行显示出已安装二进制程序的位置与名字，在这个示例中名字便是 `rg`。正如前面提到的，只要安装目录是在 `$PATH` 中，随后咱们就可以运行 `rg --help`，并启动一个用于检索文件的更快、更具 Rust 风格的工具了！


## 使用定制命令扩展 Cargo

**Extending Cargo with Custom Commands**

Cargo 被设计为在无需修改 Cargo 下，咱们就可以使用新的子命令，对其加以扩展。若咱们的 `$PATH` 中有名为 `cargo-something` 的二进制程序，咱们便可通过运行 `cargo something`，将其作为 Cargo 的子命令运行。像这样的定制命令，还会在咱们运行 `cargo --list` 时给列出来。使用 `cargo install` 安装扩展，并随后跟运行内建的 Cargo 工具一样运行他们的这种能力，正是 Cargo 设计的一项超级便利的好处！


## 本章小结

运用 Cargo 与 [crates.io](https://crates.io) 分享代码，是令到 Rust 生态对于许多不同任务都有用的一个方面。Rust 的标准库是小型且稳定的，但在不同于语言本身的时间线上，代码箱则易于共享、运用以及改进。请不要羞于在 [crates.io](https://crates.io) 上分享对自己有用的代码；那些代码或许对其他人也同样有用！
