5 分钟速读之 Rust 权威指南（二十三）Cargo

码生笔谈

关注

发布于: 2021 年 06 月 16 日

Cargo & crates.io

Cargo 相当于前端的 npm 命令行工具，https://crates.io相当于https://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

复制代码

常用的文档注释区域

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

将文档用做测试

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

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

复制代码

为整个包编写的文档

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

//! # My Crates//!//! 一系列工具集合，//! 用于数学操作
/// 两数相加/// ...

复制代码

预览查看:

使用 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.rsuse 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.rspub mod kinds {  // ...}pub mod utils {  // ...}
// 重新组织导出结构pub use self::kinds::PrimaryColor;pub use self::kinds::SecondaryColor;pub use self::utils::mix;

复制代码

使用时：

// src/main.rsuse art::PrimaryColor; // 直接引用需要的内容use art::mix;
fn main() {  // ...}

复制代码

创建 Crates.io 账号

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

# logincargo 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

复制代码

发布于: 2021 年 06 月 16 日阅读数: 11

原文链接:【http://xie.infoq.cn/article/be9d362cd39612c11a8041994】。文章转载请联系作者。

码生笔谈

关注

欢迎关注「码生笔谈」公众号 2018.09.09 加入

前端、Rust干货分享，一起成为更好的Javascripter & Rustacean

发布

暂无评论

创作场景

5 分钟速读之 Rust 权威指南（二十三）Cargo

Cargo & crates.io

使用 cargo 构建项目

配置 Cargo.toml

编写有用的文档注释

常用的文档注释区域

将文档用做测试

为整个包编写的文档

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

创建 Crates.io 账号

为包前加元数据

发布到crates.io

码生笔谈

评论