The Rust Programming Language - 第14章 更多关于Cargo和Crates.io的内容 - 14.2 将crate发布到Crate.io

14 更多关于Cargo和Crates.io的内容

进一步认识Cargo和Crate.io

目前为止，我们只使用过Cargo构建、运行和测试代码这些最基本的功能，本章我们来探索更多功能

使用发布配置来自定义构建

将库发布到crate.io

使工作空间来组织根本更大的项目

从crate.io安装二进制文件

使用自定义的命令来扩展Cargo

14.2 将crate发布到Crate.io

我们曾在项目中使用crate.io上的包作为依赖，其实crate.io是一个平台，用来分发包的源代码和托管开源代码，这意味着，我们也可以发布我们构建好的包，从而向别人分享代码

Rust和cargo 有一些帮助他人更方便找到和使用我们发布的包的功能，我们来一一介绍

编写有用的文档注释

清楚的文档注释可以让别人更好的理解和使用代码，以往我们使用//斜杠注释代码

文档注释使用///,文档注释位于需要文档的项之前，如下：

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}

可以使用cargo doc来生成这个文档注释的HTML文件，他保存在target/doc目录下

为了方便起见，运行cargo doc --open 会构建当前crate文档并在浏览器打开，可以跟随导航进一步查看

Functions
add_one Adds one to the number given.

pub fn add_one(x: i32) -> i32

Adds one to the number given.

Examples
let arg = 5;
let answer = my_crate::add_one(arg);

assert_eq!(6, answer);

常用文档注释部分

文档注释一般除了包含上述信息之外，有些注释还可能包含：

Panics: 这个函数可能会panic的场景

Errors：说明什么情况下可能会出现何种错误以及针对于这些错误该怎么处理

Safety: 如果这个函数使用unsafe代码，这一部分应该会涉及到期望函数调用者支持的确保unsafe块中代码正常工作的不变条件

当然这些都是更多信息，你也可以不写这些内容

文档注释作为测试

注释中的例子是可以用cargo test测试的

Doc-tests my_crate
running 1 test
test src\lib.rs - add_one (line 5) ... ok

注释包含项的结构

还有另一种风格的文档，//！，这为包注释的项，而不是位于注释之后的项增加文档，这通常位于crate根文件（通常是src/lib.rs）或模块的根文件为crate或模块整体提供文档

//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
// --snip--

使用cargo doc --open将会发现这些注释显示在my_crate文档的首页

Crate my_crate
[−]My Crate
my_crate is a collection of utilities to make performing certain calculations more convenient.

Functions
add_one Adds one to the number given. Adds one to the number given.

位于项之中的文档注释对于描述crate和模块特别有用。使用它们描述其容器整体的目的来帮助crate用户理解你的代码组织

使用 pub use导出合适的公有API

我们之前学习了mod组织代码模块，也学习了pub关键字将项变为公有，还学习了用use将项引入作用域。但是这是只是方便了我们组织代码，对于代码调用者来说并不友好。不过我们可以使用pub use重导出项来使公有结构不同于私有结构

我们来看个例子

//! # Art
//!
//! A library for modeling artistic concepts.

pub mod kinds {
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

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

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        // --snip--
    }
}

使用cargo doc --open 打开

Crate my_crate
[−]Art
A library for modeling artistic concepts.

Modules
kinds
utils

但是我们看到模块中的两个枚举是不可见的，如果要导入art中的项，得像下面一样

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

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

但其实调用者不太熟悉我们代码组织的结构，因此我们用pub use 来重导出一下

//! # Art
//!
//! A library for modeling artistic concepts.

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

pub mod kinds {
     /// The primary colors according to the RYB color model.
     pub enum PrimaryColor {
         Red,
         Yellow,
         Blue,
     }
 
     /// The secondary colors according to the RYB color model.
     pub enum SecondaryColor {
         Orange,
         Green,
         Purple,
     }
 }
 
 pub mod utils {
     use crate::kinds::*;
 
     /// Combines two primary colors in equal amounts to create
     /// a secondary color.
     pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
         // --snip--
         SecondaryColor::Orange
     }
 }

cargo doc --open

Crate my_crate
[−]Art
A library for modeling artistic concepts.

Re-exports
pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

Modules
kinds
utils

这样代码的内部结构就一目了然了，调用者也知道里面有什么了

而用户可以按照如下方式调用

use art::PrimaryColor;
use art::mix;

fn main() {
    // --snip--
}

这个重导出结构麻烦的一点就是需要代码构建者去做这个事情

创建Crate.io账号

访问https://crates.io/，注册并且获取API token，

cargo login cioR8FhNZp9E1UzfKS8Xpz7bEISBdbsTmIC

发布crate之前

发布之前我们需要在crate的Cargo.toml文件的[package]部分增加一些本crate的元信息，如：

[package]
name = "guessing_game"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
edition = "2018"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

[dependencies]

发布到Crate.io

发布的时候请务必小心，因为发布是永久性的

再次运行 cargo publish 命令。这次它应该会成功：

Updating registry `https://github.com/rust-lang/crates.io-index`
Packaging guessing_game v0.1.0 (file:///projects/guessing_game)
Verifying guessing_game v0.1.0 (file:///projects/guessing_game)
Compiling guessing_game v0.1.0
(file:///projects/guessing_game/target/package/guessing_game-0.1.0)
 Finished dev [unoptimized + debuginfo] target(s) in 0.19 secs
Uploading guessing_game v0.1.0 (file:///projects/guessing_game)

发布现存crate的新版本

当你发布新版本时，改变Cargo.toml中version所指定的值，接着运行cargo publish来上传新版本

使用cargo yank 从Crate.io撤回版本

撤回的意思不是说删除以前的版本，而是阻止将来的项目将它们加入到依赖中

cargo yank --vers 1.0.l

也可以撤销撤回操作，并允许项目可以再次依赖某个版本，通过在命令上增加 --undo

cargo yank --vers 1.0.1 --undo

撤回功能并不在意删除不小心上传的秘密信息。如果出现了这种情况，请立即重新设置这些秘密信息