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
常用的文档注释区域
- 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
//!
//! 一系列工具集合,
//! 用于数学操作
/// 两数相加
/// ...
预览查看:
使用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