mirror of
https://github.com/gnu4cn/rust-lang-zh_CN.git
synced 2025-03-14 03:10:44 +08:00
Re-constructured Ch14.
This commit is contained in:
rust-lang.xfoss.com
parent
400a9f9543
commit
6fc28b5a1f
@ -12,874 +12,3 @@
|
||||
|
||||
|
||||
相比咱们在本章会讲到的功能，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 中所示：
|
||||
|
||||
|
||||
|
||||
*图 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 中所示：
|
||||
|
||||
|
||||
|
||||
*图 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` 产生出的该代码箱文档首页，看起来的样子：
|
||||
|
||||
|
||||
|
||||
*图 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` 函数更易于找到。
|
||||
|
||||
|
||||
|
||||
*图 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) 上分享对自己有用的代码；那些代码或许对其他人也同样有用！
|
||||
|
||||
@ -95,6 +95,11 @@
|
||||
- [性能比较：循环与迭代器](functional_features/performance.md)
|
||||
|
||||
- [Cargo 的其他方面及 Crates.io](Ch14_More_about_Cargo_and_Crates-io.md)
|
||||
- [使用发布配置文件自定义构建](crates-io/release_profiles.md)
|
||||
- [将代码箱发布到 Crates.io](crates-io/publishing.md)
|
||||
- [Cargo 工作区](crates-io/workspace.md)
|
||||
- [使用 `cargo install` 安装 Crates.io 上的二进制程序](crates-io/cargo_install.md)
|
||||
- [以定制命令扩展 Cargo](crates-io/custom_commands.md)
|
||||
|
||||
- [灵巧指针](Ch15_Smart_Pointers.md)
|
||||
|
||||
|
||||
76
src/crates-io/cargo_install.md
Normal file
76
src/crates-io/cargo_install.md
Normal file
@ -0,0 +1,76 @@
|
||||
# 使用 `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 风格的工具了！
|
||||
10
src/crates-io/custom_commands.md
Normal file
10
src/crates-io/custom_commands.md
Normal file
@ -0,0 +1,10 @@
|
||||
# 使用定制命令扩展 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) 上分享对自己有用的代码；那些代码或许对其他人也同样有用！
|
||||
445
src/crates-io/publishing.md
Normal file
445
src/crates-io/publishing.md
Normal file
@ -0,0 +1,445 @@
|
||||
# 将代码箱发布到 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 中所示：
|
||||
|
||||
|
||||
|
||||
*图 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 中所示：
|
||||
|
||||
|
||||
|
||||
*图 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` 产生出的该代码箱文档首页，看起来的样子：
|
||||
|
||||
|
||||
|
||||
*图 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` 函数更易于找到。
|
||||
|
||||
|
||||
|
||||
*图 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
|
||||
```
|
||||
|
||||
抽出版本，*不会* 删除任何代码。比如，其无法删除那些不小心上传的机密信息。若发生了机密信息被上传的情况，咱们必须立即重置这些机密信息。
|
||||
46
src/crates-io/release_profiles.md
Normal file
46
src/crates-io/release_profiles.md
Normal file
@ -0,0 +1,46 @@
|
||||
# 使用不同发布配置文件，对构建进行定制
|
||||
|
||||
**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)。
|
||||
304
src/crates-io/workspace.md
Normal file
304
src/crates-io/workspace.md
Normal file
@ -0,0 +1,304 @@
|
||||
# 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` 添加到这个工作区！
|
||||
|
||||
当咱们的项目日渐增长时，请考虑使用工作区：相比于一大块代码，要搞清楚较小的、单独的组件就更容易一些。再者，当代码箱经常同时被修改时，把这些代码箱保持在工作区中，就能令到他们之间的协作更容易。
|
||||
Loading…
Reference in New Issue
Block a user