@ -1,7 +1,6 @@
## 将 crate 发布到 Crates.io
> [ch14-02-publishing-to-crates-io.md ](https://github.com/rust-lang/book/blob/master/src/ch14-02-publishing-to-crates-io.md )
> < br >
> [ch14-02-publishing-to-crates-io.md ](https://github.com/rust-lang/book/blob/master/src/ch14-02-publishing-to-crates-io.md ) > < br >
> commit c084bdd9ee328e7e774df19882ccc139532e53d8
我们曾经在项目中使用 [crates.io ](https://crates.io )<!-- ignore --> 上的包作为依赖,不过你也可以通过发布自己的包来向它人分享代码。[crates.io](https://crates.io)<!-- ignore --> 用来分发包的源代码,所以它主要托管开源代码。
@ -10,13 +9,13 @@ Rust 和 Cargo 有一些帮助它人更方便找到和使用你发布的包的
### 编写有用的文档注释
准确的包文档有助于其他用户理解如何以及何时使用他们,所以花一些时间编写文档是值得的。第三章中我们讨论了如何使用两斜杠 `//` 注释 Rust 代码。Rust 也有特定的用于文档的注释类型,通常被称为 ** 文档注释**( *documentation comments* ),他们会生成 HTML 文档。这些 HTML 展示公有 API 文档注释的内容,他们意在让对库感兴趣的程序员理解如何 ** 使用** 这个 crate, 而不是它是如何被 ** 实现** 的。
准确的包文档有助于其他用户理解如何以及何时使用他们,所以花一些时间编写文档是值得的。第三章中我们讨论了如何使用两斜杠 `//` 注释 Rust 代码。Rust 也有特定的用于文档的注释类型,通常被称为 ** 文档注释**( _documentation comments_ ),他们会生成 HTML 文档。这些 HTML 展示公有 API 文档注释的内容,他们意在让对库感兴趣的程序员理解如何 ** 使用** 这个 crate, 而不是它是如何被 ** 实现** 的。
文档注释使用三斜杠 `///` 而不是两斜杆并 支持 Markdown 注解来格式化文本。文档注释就位于需要文档的项的之前。示例 14-1 展示了一个 `my_crate` crate 中 `add_one` 函数的文档注释:
文档注释使用三斜杠 `///` 而不是两斜杆以 支持 Markdown 注解来格式化文本。文档注释就位于需要文档的项的之前。示例 14-1 展示了一个 `my_crate` crate 中 `add_one` 函数的文档注释:
< span class = "filename" > 文件名: src/lib.rs< / span >
```rust,ignore
```` rust,ignore
/// 将给定的数字加一
///
/// # Examples
@ -30,11 +29,11 @@ Rust 和 Cargo 有一些帮助它人更方便找到和使用你发布的包的
pub fn add_one(x: i32) -> i32 {
x + 1
}
```
````
< span class = "caption" > 示例 14-1: 一个函数的文档注释< / span >
这里,我们提供了一个 `add_one` 函数工作的描述,接着开始了一个标题为 `Examples` 的部分,和展示如何使用 `add_one` 函数的代码。可以运行 `cargo doc` 来生成这个文档注释的 HTML 文档。这个命令运行由 Rust 分发的工具 `rustdoc` 并将生成的 HTML 文档放入 *target/doc* 目录。
这里,我们提供了一个 `add_one` 函数工作的描述,接着开始了一个标题为 `Examples` 的部分,和展示如何使用 `add_one` 函数的代码。可以运行 `cargo doc` 来生成这个文档注释的 HTML 文档。这个命令运行由 Rust 分发的工具 `rustdoc` 并将生成的 HTML 文档放入 _target/doc_ 目录。
为了方便起见,运行 `cargo doc --open` 会构建当前 crate 文档(同时还有所有 crate 依赖的文档)的 HTML 并在浏览器中打开。导航到 `add_one` 函数将会发现文档注释的文本是如何渲染的,如图 14-1 所示:
@ -69,9 +68,9 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
#### 注释包含项的结构
还有另一种风格的文档注释,`//!`,这为包含注释的项,而不是注释之后的项增加文档。这通常用于 crate 根文件(通常是 *src/lib.rs* )或模块的根文件为 crate 或模块整体提供文档。
还有另一种风格的文档注释,`//!`,这为包含注释的项,而不是注释之后的项增加文档。这通常用于 crate 根文件(通常是 _src/lib.rs_ )或模块的根文件为 crate 或模块整体提供文档。
作为一个例子,如果我们希望增加描述包含 `add_one` 函数的 `my_crate` crate 目的的文档,可以在 *src/lib.rs* 开头增加以 `//!` 开头的注释,如示例 14-2 所示:
作为一个例子,如果我们希望增加描述包含 `add_one` 函数的 `my_crate` crate 目的的文档,可以在 _src/lib.rs_ 开头增加以 `//!` 开头的注释,如示例 14-2 所示:
< span class = "filename" > 文件名: src/lib.rs< / span >
@ -87,7 +86,7 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
< span class = "caption" > 示例 14-2: `my_crate` crate 整体的文档< / span >
注意 `//!` 的最后一行之后没有任何代码。因为他们以 `//!` 开头而不是 `///` ,这是属于包含此注释的项而不是注释之后项的文档。在这个情况中,包含这个注释的项是 *src/lib.rs* 文件,也就是 crate 根文件。这些注释描述了整个 crate。
注意 `//!` 的最后一行之后没有任何代码。因为他们以 `//!` 开头而不是 `///` ,这是属于包含此注释的项而不是注释之后项的文档。在这个情况中,包含这个注释的项是 _src/lib.rs_ 文件,也就是 crate 根文件。这些注释描述了整个 crate。
如果运行 `cargo doc --open` ,将会发现这些注释显示在 `my_crate` 文档的首页,位于 crate 中公有项列表之上,如图 14-2 所示:
@ -229,13 +228,13 @@ fn main() {
$ cargo login abcdefghijklmnopqrstuvwxyz012345
```
这个命令会通知 Cargo 你的 API token 并将其储存在本地的 *~/.cargo/credentials* 文件中。注意这个 token 是一个 ** 秘密**( **secret**)且不应该与其他人共享。如果因为任何原因与他人共享了这个信息,应该立即到 [crates.io ](https://crates.io )<!-- ignore --> 重新生成这个 token。
这个命令会通知 Cargo 你的 API token 并将其储存在本地的 _~/.cargo/credentials_ 文件中。注意这个 token 是一个 ** 秘密**( **secret**)且不应该与其他人共享。如果因为任何原因与他人共享了这个信息,应该立即到 [crates.io ](https://crates.io )<!-- ignore --> 重新生成这个 token。
### 发布新 crate 之前
有了账号之后,比如说你已经有一个希望发布的 crate。在发布之前, 你需要在 crate 的 *Cargo.toml* 文件的 `[package]` 部分增加一些本 crate 的元信息( metadata) 。
有了账号之后,比如说你已经有一个希望发布的 crate。在发布之前, 你需要在 crate 的 _Cargo.toml_ 文件的 `[package]` 部分增加一些本 crate 的元信息( metadata) 。
首先 crate 需要一个唯一的名称。虽然在本地开发 crate 时,可以使用任何你喜欢的名称。不过 [crates.io ](https://crates.io )<!-- ignore --> 上的 crate 名称遵守先到先得的分配原则。一旦某个 crate 名称被使用,其他人就不能再发布这个名称的 crate 了。请在网站上搜索你希望使用的名称来找出它是否已被使用。如果没有,修改 *Cargo.toml* 中 `[package]` 里的名称为你希望用于发布的名称,像这样:
首先 crate 需要一个唯一的名称。虽然在本地开发 crate 时,可以使用任何你喜欢的名称。不过 [crates.io ](https://crates.io )<!-- ignore --> 上的 crate 名称遵守先到先得的分配原则。一旦某个 crate 名称被使用,其他人就不能再发布这个名称的 crate 了。请在网站上搜索你希望使用的名称来找出它是否已被使用。如果没有,修改 _Cargo.toml_ 中 `[package]` 里的名称为你希望用于发布的名称,像这样:
< span class = "filename" > 文件名: Cargo.toml< / span >
@ -255,9 +254,9 @@ homepage or repository.
error: api errors: missing or empty metadata fields: description, license.
```
这是因为我们缺少一些关键信息:关于该 crate 用途的描述和用户可能在何种条款下使用该 crate 的 license。为了修正这个错误, 需要在 *Cargo.toml* 中引入这些信息。
这是因为我们缺少一些关键信息:关于该 crate 用途的描述和用户可能在何种条款下使用该 crate 的 license。为了修正这个错误, 需要在 _Cargo.toml_ 中引入这些信息。
描述通常是一两句话,因为它会出现在 crate 的搜索结果中和 crate 页面里。对于 `license` 字段,你需要一个 **license 标识符值** ( *license identifier value* )。[Linux 基金会的 Software Package Data Exchange (SPDX)][spdx] 列出了可以使用的标识符。例如,为了指定 crate 使用 MIT License, 增加 `MIT` 标识符:
描述通常是一两句话,因为它会出现在 crate 的搜索结果中和 crate 页面里。对于 `license` 字段,你需要一个 **license 标识符值** ( _license identifier value_ )。[Linux 基金会的 Software Package Data Exchange (SPDX)][spdx] 列出了可以使用的标识符。例如,为了指定 crate 使用 MIT License, 增加 `MIT` 标识符:
[spdx]: http://spdx.org/licenses/
@ -273,7 +272,7 @@ license = "MIT"
关于项目所适用的 license 指导超出了本书的范畴。很多 Rust 社区成员选择与 Rust 自身相同的 license, 这是一个双许可的 `MIT OR Apache-2.0` 。这个实践展示了也可以通过 `OR` 分隔为项目指定多个 license 标识符。
那么,有了唯一的名称、版本号、由 `cargo new` 新建项目时增加的作者信息、描述和所选择的 license, 已经准备好发布的项目的 *Cargo.toml* 文件可能看起来像这样:
那么,有了唯一的名称、版本号、由 `cargo new` 新建项目时增加的作者信息、描述和所选择的 license, 已经准备好发布的项目的 _Cargo.toml_ 文件可能看起来像这样:
< span class = "filename" > 文件名: Cargo.toml< / span >
@ -295,7 +294,7 @@ license = "MIT OR Apache-2.0"
现在我们创建了一个账号,保存了 API token, 为 crate 选择了一个名字,并指定了所需的元数据,你已经准备好发布了!发布 crate 会上传特定版本的 crate 到 [crates.io ](https://crates.io )<!-- ignore --> 以供他人使用。
发布 crate 时请多加小心,因为发布是 ** 永久性的**( *permanent* )。对应版本不可能被覆盖,其代码也不可能被删除。[crates.io](https://crates.io)<!-- ignore --> 的一个主要目标是作为一个存储代码的永久文档服务器,这样所有依赖 [crates.io ](https://crates.io )<!-- ignore --> 中的 crate 的项目都能一直正常工作。而允许删除版本没办法达成这个目标。然而,可以被发布的版本号却没有限制。
发布 crate 时请多加小心,因为发布是 ** 永久性的**( _permanent_ )。对应版本不可能被覆盖,其代码也不可能被删除。[crates.io](https://crates.io)<!-- ignore --> 的一个主要目标是作为一个存储代码的永久文档服务器,这样所有依赖 [crates.io ](https://crates.io )<!-- ignore --> 中的 crate 的项目都能一直正常工作。而允许删除版本没办法达成这个目标。然而,可以被发布的版本号却没有限制。
再次运行 `cargo publish` 命令。这次它应该会成功:
@ -314,15 +313,15 @@ Uploading guessing_game v0.1.0 (file:///projects/guessing_game)
### 发布现存 crate 的新版本
当你修改了 crate 并准备好发布新版本时,改变 *Cargo.toml* 中 `version` 所指定的值。请使用 [语义化版本规则][semver] 来根据修改的类型决定下一个版本号。接着运行 `cargo publish` 来上传新版本。
当你修改了 crate 并准备好发布新版本时,改变 _Cargo.toml_ 中 `version` 所指定的值。请使用 [语义化版本规则][semver] 来根据修改的类型决定下一个版本号。接着运行 `cargo publish` 来上传新版本。
[semver]: http://semver.org/
### 使用 `cargo yank` 从 Crates.io 撤回版本
虽然你不能删除之前版本的 crate, 但是可以阻止任何将来的项目将他们加入到依赖中。这在某个版本因为这样或那样的原因被破坏的情况很有用。对于这种情况, Cargo 支持 ** 撤回**( *yanking* )某个版本。
虽然你不能删除之前版本的 crate, 但是可以阻止任何将来的项目将他们加入到依赖中。这在某个版本因为这样或那样的原因被破坏的情况很有用。对于这种情况, Cargo 支持 ** 撤回**( _yanking_ )某个版本。
撤回某个版本会阻止新项目开始依赖此版本,不过所有现存此依赖的项目仍然能够下载和依赖这个版本。从本质上说,撤回意味着所有带有 *Cargo.lock* 的项目的依赖不会被破坏,同时任何新生成的 *Cargo.lock* 将不能使用被撤回的版本。
撤回某个版本会阻止新项目开始依赖此版本,不过所有现存此依赖的项目仍然能够下载和依赖这个版本。从本质上说,撤回意味着所有带有 _Cargo.lock_ 的项目的依赖不会被破坏,同时任何新生成的 _Cargo.lock_ 将不能使用被撤回的版本。
为了撤回一个 crate, 运行 `cargo yank` 并指定希望撤回的版本: