Rust学习第十二天——cargo, crates.io

学习内容

• 通过release profile来自定义构建

• 在http://crates.io/上发布库

• 通过workspace组织大工程

• 从http://crates.io/来安装库

• 使用自定义命令拓展cargo

通过release profile来自定义构建

release profile

• release profile

• 是预定义的

• 可自定义：可使用不同的配置，对代码编译拥有更多的控制

• 每个profile的配置都独立于其他的profile

• cargo主要的两个profile：

• dev profile：适用于开发，cargo build

• release profile：适用于发布，cargo build --release

发布crate到crates.io

crates.io

• 可以通过发布来共享你的代码

• crate的注册表在http://crates.io/

• 它会分发已注册的包的源代码

• 主要托管开源的代码

文档注释

• 文档注释：用于生成文档

• 生成HTNL文档

• 显式公共API的文档注释：如何使用API

• 使用///

• 支持Markdown

• 放置在被说明条目之前

• 例子：

/// 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
}

生成HTML文档的命令

• cargo doc

• 它会运行rustcdoc工具（rust 安装包自带）

• 把生成的HTML文档放在target/doc文档下

• cargo doc --open

• 构建当前crate的文档（也包含crate依赖项的文档）

• 在浏览器打开文档

常用章节

• # Example

• 其他常用的章节

• Panics:函数可能发生panic的场景

• Errors: 如果函数返回Result，描述可能的错误种类，以及可导致错误的条件

• Safety：如果函数处于unsafe调用，就应该解释函数unsafe的原因，以及调用者确保的使用前提

文档注释作为测试

• 示例代码块的附加值：

• 运行cargo test：将把文档注释中的示例代码作为测试来运行

• 这两个名称要一致就不会报错了

• cargo test

未包含注释的项添加文档注释

• 符号：//!

• 这类注释通常用描述crate和模块

• crate root（按惯例src/lib.rs）

• 一个模块内，将crate或模块作为一个整体进行记录

//! # Iterator2
//!
//! `Iterator2` is a collection of utilities to make performing
//! calculations more convenient.


/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = Iterator2::add_one(arg);
///
/// assert_eq!(6, answer);

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

pub use

使用pub use 导出方便使用的公共API

• 问题：crate的程序结构在开发时对于开发者很合理，但对于它的使用者不够方便

• 开发者会把程序结构分为很多层，使用者想找到这种深层结构中的某个类型很费劲

• 例如：

• 麻烦：my_crate::some_module::another_module::UsefullType;

• 方便：my_crate::UsefullType;

• 解决办法：

• 不需要重新组织内部结构代码

• 使用pub use: 可以重新导出，创建一个与内部私有结构不同的对外公共结构

• 例子：

lib.rs

//! # 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 crate
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        SecondaryColor::Green
    }
}

main.rs

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

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

运行cargo doc --open， 有：

使用pub use后：

lib.rs

//! # 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 crate
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        SecondaryColor::Green
    }
}

main.rs

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

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

创建并设置Crates.io账号

• 发布crate前，需要在crates.io创建账号并获得API token

• 运行命令：cargo login [你的API token]

• 通知cargo，你的API Token存储在本地~/.cargo/credentials

• API token可以在http://crates.io/进行撤销

• package的name要独一无二

为新的crate添加元数据

• 在发布crate之前，需要在Cargo.toml的【package】区域为crate添加一些元素数据：

• crate需要唯一的名称：name

• description：一两句话即可，会出现在crate搜索的结果里

• license：需提供许可证标识值（可到http://spdx.org/licenses/查找）

• 可指定多个license：用OR

• version

• author

• 发布：cargo publish命令

发布到crates.io

• crate一旦发布，就是永久性的：该版本无法覆盖，代码无法删除

• 目的：依赖于该版本的项目可继续正常工作

发布已存在crate的新版本

• 修改crate后，需要先修改Cargo.toml里面的version值，再重新发布

• 参照http://semver.org/ 来使用你的语义版本

• 再执行cargo publish进行发布

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

• 不可以删除crate之前的版本

• 但可以防止其他项目把它作为新的依赖：yank（撤回）一个crate版本

• 防止新项目依赖于该版本

• 已经存在项目可继续将其作为依赖（并可下载）

• yank意味着：

• 所有已经产生Cargo.lock的项目都不会中断

• 任何将来产生的Cargo.lock文件都不会使用被yank的版本

• 命令：

• yank一个版本（不会删除任何代码）：cargo yank --vers 1.0.1

• 取消yank：cargo yank --vers 1.0.1 --undo

cargo 工作空间

创建工作空间

• 有多种方式来组建工作空间，例：1个二进制crate，2个库crate

• 二进制crate：main函数，依赖于其它两个库crate

• 其中一个库crate提供add_one函数

• 其中一个库crate提供add_two函数

• 先创建Cargo.toml

[workspace]

members = [
    "adder"
]

• 再在add目录里cargo new adder

• 指定运行用参数p

main.rs

use add_one;


fn main() {
    let num = 10;
    println!(
        "Hello, world!  {} plus one is {}!",
        num,
        add_one::add_one(num)
    );
}

在工作空间中依赖外部crate

• 工作空间只有一个Cargo.lock文件，在工作空间的顶层目录

• 保证工作空间内所有crate使用的依赖的版本都相同

• 工作空间内所有crate相互兼容

为工作空间添加测试

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


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

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

安装二进制crate

从CRATES.IO安装crate

cargo install

使用自定义命令拓展cargo

总结

这章因为过年走亲戚，都没怎么学，过年所学甚少，还是要多管管自己的嘴，少吃点，该自律起来了。