Skip to main content

C14 Cargo 和 Crate.io 的更多内容

https://doc.rust-lang.org/book/ch14-00-more-about-cargo.html

本章讲一些 Cargo 的高级功能:

  1. 自定义编译配置
  2. 发布包到 crates.io
  3. 通过 workspace 管理大型项目
  4. 依赖 crates.io 上面的库
  5. 使用自定义指令扩展 Cargo

更多 Cargo 的高级用法, 还可以参考这个文档.

自定义 Release 编译配置​

Rust 中编译配置是预定义的, 它里面的选项可自定义. 这样开发者可编译过程进行精细控制.

Cargo 有两个主要编译配置:

  • dev: 当运行 cargo build 时, 这个配置用于开发.
  • release: 当运行 cargo build --release, 这个配置用于发布.

当在 Cargo.toml 中添加 [profile.*](其中 * 可以是 dev 或 release)后, 即可在此部分中对二者的配置进行修改. 比如修改二者对应不同的 opt-level:

[profile.dev]
opt-level = 0

[profile.release]
opt-level = 2

opt-level 用来控制 Rust 对生成代码的优化等级, 范围从 0~3. dev 的默认为 0, 而 release 的默认为 3. 关于可用的编译配置项, 详见官方文档.

发布自己的 crate 到 Crates.io​

首先需要为自己的代码提供注释, Rust 中代码注释的语法如下所示(即在注释中使用 /// 且语法为 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
}

若要提供文档注释:

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

以 //! 开头的行即文档注释, 用来提供对某个 mod 或整个 crate 的文档(根据所在位置的不同).

使用 pub use 提供公共 API: 在 crate 顶层, 若想将 pub api 在 lib.rs 中暴露给外界, 可以使用 pub use 将某个 path 中的 pub 部分暴露出去.

一条有用的命令: cargo doc --open 可在本地生成所有文档并进行查看(仅本地代码和三方依赖的文档), 若想生成标准库的文档.

代码中写好文档且有良好组织的 API, 下一步就是发布.

发布步骤:

  1. 注册 crate.io 账号
  2. cargo login
  3. 为自己的 crate 提供元数据信息(包名/描述/crate版本/Rust版本/协议等等), 用于 crate.io 展示
  4. 使用 cargo publish 进行发布.

若想发布一个新版本, 修改版本号后, 重新 cargo publish.

若想标记一个版本被废弃, 使用 cargo yank, 如 cargo yank --vers 1.0.1. 若想取消, 则 cargo yank --vers 1.0.1 --undo

Cargo workspace​

Cargo workspace 用于管理大型工程, 在其中可以包含多个 package, 这些 package 的公共配置可以在顶层 Cargo.toml 中写, 而每个 package 可以有自己的 Cargo.toml.

要定义 workspace:

  1. 建立目录
  2. 添加包
  3. 添加顶层 Cargo.toml: 
    # 表明这个是 workspace 的顶层配置
    [workspace]

    # workspace 包含的所有 package 目录名
    members = [
        "adder", "mylib", "my_exec"
    ]
  4. 继续添加 package, 并将其名称加入到顶层 Cargo.toml.

通过上述即创建了一个 workspace.

需要注意的是, workspace 的 Cargo.lock 文件也位于顶层, 每个包中没有单独的. 这样可以保证所有的包依赖版本都能统一, 避免依赖冲突, 这样 workspace 中的各个 crate 都能互相兼容.

在 workspace 中的一个 crate 依赖另外一个, 只需要在对应的 Cargo.toml 中添加另外一个的路径即可.

要想在 workspace 中运行某个 package 内的测试, 可以使用 cargo test -p xxx 即可, 不添加 -p 则是运行所有的测试.

使用 cargo install 安装命令行工具​

目前已经有许多实用 rust 命令行工具, 可以通过 cargo install 安装到本地使用, 比如 cargo install ripgrep.

自定义 cargo 命令​

若自己有名为 cargo-something 的命令行程序在 $PATH 中存在, 则可以通过 cargo something 的方式运行该命令行程序, 就好像这个程序是 cargo 的子命令那样.

要列出所有的自定义命令, 可以使用 cargo --list.

Cargo 通过上述方式进行自我扩展, 而这些扩展也是通过 cargo install 来安装, 非常方便, 体现 Cargo 的优秀设计.