5分钟速读之Rust权威指南(二十三)Cargo

246 阅读3分钟

Cargo & crates.io

Cargo相当于前端的npm命令行工具,crates.io相当于www.npmjs.com/

使用cargo构建项目

开发时构建:

cargo build

发布时构建,添加—release参数:

cargo build --release

配置Cargo.toml

Cargo.toml相当于前端的package.json,里边存放的项目的配置信息

opt-level控制了Rust在编译时会对代码执行何种程度的优化,0-3之间:

# 开发环境默认配置
[profile.dev]
opt-level = 0
# 发布环境默认配置
[profile.build]
opt-level = 3

编写有用的文档注释

使用三斜杠注释编写文档,支持markdown语法:

// src/lib.rs

/// 两数相加
/// # Example
/// ```
/// let a = 1;
/// let b = 2;
/// assert_eq!(3, my_crates::add(a, b))
/// ```
pub fn add(a: i32, b: i32) -> i32 {
  a + b
}

本地预览文档:

cargo doc --open

2021-04-08_7.00.26.png

常用的文档注释区域

  • Example: 对使用方法举例
  • Errors: 函数返回Result作为结果时,这个区域指可能出现的错误和原因
  • Safety: 当函数使用了unsafe关键字(后面会介绍)时,这个区域会指出当前函数不安全的原因,以及调用者应当确保的使用前提。
  • Panics: 指出可能出现panic的场景

将文档用做测试

当使用cargo test命令做测试时,文档中的Example也被会当做测试

# cargo test
# ...
Doc-tests my_crates
running 1 test
test src/lib.rs - add (line 3) ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.67s

为整个包编写的文档

使用//!来为整个包编写文档

//! # My Crates
//!
//! 一系列工具集合,
//! 用于数学操作

/// 两数相加
/// ...

预览查看:

2021-04-08_7.14.59.png

使用pub use来导出合适的公共API

当我们使用一个包时,当包的内部组织结构很复杂,我们需要了解其组织方式和路径,才能正确的引用,想想一下JS中的 export {} from 'xxx',例如使用下面这个库:

// src/lib.rs
//! # 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::Orange
  }
}

使用时需要了解其具体路径:

// src/main.rs
use art::kinds::PrimaryColor;
use art::utils::mix;

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

如果使用包的组织更加复杂,开发者体验会非常不好:

use some_lib::utils::common::safe::add

使用pub use重新组织包的对外暴露方式:

// src/lib.rs
pub mod kinds {
  // ...
}
pub mod utils {
  // ...
}

// 重新组织导出结构
pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

使用时:

// src/main.rs
use art::PrimaryColor; // 直接引用需要的内容
use art::mix;

fn main() {
  // ...
}

创建 Crates.io 账号

发布包需要有crates.io账号,首先在crates.io/me/创建token,执行login命令,cargo将会自动创建~/.cargo/credentials 文件中用于记录登录信息:

# login
cargo login abcdefghijklmnopqrstuvwxyz012345

为包前加元数据

元数据指的是一些关于包的基本信息:

[package]
name = "package_name" # 独一无二的名字
description = "package description" # 包的描述
license = "MIT" # 许可协议
version = "0.1.0" # 包版本
authors = ["author <author@vipkid.com.cn>"]

发布到crates.io

使用命令将包发布:

cargo publish

这一操作是永久性的。已经上传的版本将无法被覆盖,对应的代码也不能被删除。


撤销某个版本:

cargo yank --vers 1.0.1

对于使用者的项目来说,所有已经产生Cargo.lock的项目将不会受到撤回操作的影响,而未来所有产生的新Cargo.lock文件将不会再使用已经撤回的版本。


取消撤回操作:

cargo yank --vers 1.0.1 --undo