Cargo 除了可以编译、运行、测试程序项目之外,还可以针对程序项目进进程式建构(build)时的细节调整、将不同程序项目组合成相同的工作空间(Workspace),还能搭配 crates.io 来使用,利用程序项目的相依关系快速取得 crates.io 上的套件,或是反过来将我们开发完成的函数库发布到 crates.io 上。

修改程序建构的方式

Cargo 有两种主要的程序建构模式,分别是运行 cargo build 指令的开发(dev)模式,和运行 cargo build --release 指令用来正式发布程序时使用的发布(release)模式。在先前的章节中,我们知道加上 --release 参数之后输出的程序就会透过编译器进行一些优化,并且移除掉开发阶段时用来调试(debug)的功能和消息,确保正式版本的程序能在最佳状态下运作(高性能、小体积)。

透过在 Cargo.toml 设置档中定义 [profile.dev] 或 [profile.release] 区块的方式,我们可以覆写掉开发模式或是发布模式预设的程序建构参数。

举例来说,影响着编译时程序优化程度的设置项目为 opt-level,设置值数值范围在 0~3 之间(包含 0 和 3),数值 0 表示不作优化,数值愈高表示优化程度愈高。0 和 1 适合用在开发模式,2 和 3 适合用在发布模式。开发模式的优化程度默认值为 0,发布模式的优化程度默认值为 3,如果要将开发模式的优化程度改为 1,发布模式的优化程度改为 2,可以在 Cargo.toml 设置档中添加以下内容:

[profile.dev]
opt-level = 1

[profile.release]
opt-level = 2

opt-level 另外还可以设置为 s 或 z。s 可以让编译器以小体积为优先来编译程序;z 可以让编译器尝试编译出比 s 还要更小的程序。

发布 crate 到 crates.io

将自己写的函数库开放源代码到 crates.io,提供给其它 Rust 开发者使用前,应先替函数库准备好 API 文档,不然没有人会用。Rust 编程语言有提供文档注解,单行的话,一般注解是以 // 开头,而文档注解是以 /// 开头,支持 Markdown 语法。

举例来说:

/// Adds two to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(7, adder::add_two(five));
/// ```
pub fn add_two(a: i32) -> i32 {
    if a < 0 {
        panic!("`a` shoud not smaller than zero, but `a` = {a}");
    }

    a + 2
}

接着运行 cargo doc 指令,就可以替这个程序项目产生出网页版文档了!网页会保存在 target 目录的 doc 目录下。

如果想要在网页版文档产生出来之后直接用浏览器打开,可以替 cargo doc 指令加上 --open 参数。产生出来的网页如下:

cargo doc 产生的网页版文档首页

add_two 函数的文档与范例

Examples 是我们透过 Markdown 语法的 Heading 1 所产生出来的区块,区块名称可以自行随便定义。而范例程序的部份使用 Markdown 的 ``` 语法,除了能在网页中有代码高亮的效果之外,在使用 cargo test 指令测试程序项目的时候还可以测试文档注解内写的范例程序。

cargo test 测试文档中的范例程序

Doc-tests 的部份就是写在文档注解内的范例程序,如此一来就可以确认程序文档中的范例程序是否是正确的。

除了函数可以加上文档注解之外,整个 crate 也可以加上文档注解,但就不是使用 ///,而是 //!。举例来说:

//! # Adder
//!
//! `adder` is a project that we used for practicing Rust.

/// Adds two to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(7, adder::add_two(five));
/// ```
pub fn add_two(a: i32) -> i32 {
    if a < 0 {
        panic!("`a` shoud not smaller than zero, but `a` = {a}");
    }

    a + 2
}

如此一来,在文档的网页中就会多出 crate 的说明。

文档网页中多出的 crate 说明

如果要使用多行注解,/// 可以改成 /**(开头)和 */(结尾),//! 可以改成 /*!(开头)和 */(结尾)。举例来说:

/*!
# Adder

`adder` is a project that we used for practicing Rust.
*/

/**
Adds two to the number given.

# Examples

```
let five = 5;

assert_eq!(7, adder::add_two(five));
```
*/
pub fn add_two(a: i32) -> i32 {
    if a < 0 {
        panic!("`a` shoud not smaller than zero, but `a` = {a}");
    }

    a + 2
}

想要将自己制作的函数库放到 crates.io 上,必须先登录 crates.io,并且利用以下网址来产生 API Token:

假设产生出来的 API Token 为 txDj58akNnoIoJXqzzbW4VYOoh3vgrow,运行以下指令,Cargo 就可以借由这组 API Token 来登录我们的 crates.io 帐号。

cargo login txDj58akNnoIoJXqzzbW4VYOoh3vgrow

在函数库发布前,可以替其选择一个适当的开放源代码 License 来套用。可以参考这个网站:

每个开放源代码 License 都有其专属的「辨识名称」,选定好要用的 License 之后,在我们程序项目 Cargo.toml 设置档中的 [package] 区块,可以加上 license 设置项目,来指定这个项目要套用的 License。举例来说:

[package]
name = "adder"
license = "MIT"

此外也必须加上 description 设置项目,来描述一下这个函数库的作用。

确认目前的程序项目设置无误,且可以通过测试之后,就可以使用以下指令来将我们的函数库发布或是更新到 crates.io 上了!

cargo publish

工作空间

如果我们要开发的套件很庞大,可以将其分割成多个子套件,利用工作空间组合起来使用。工作空间由多个程序项目来组成,可以使这些程序项目共享同一个 Cargo.lock 文件和输出目录。

创建一个工作空间的方式很简单,只要创建出一个空目录,并在这个空目录中添加一个 Cargo.toml 设置档,接着在设置档内添加 [workspace] 区块,将这个工作空间所包含的其它程序项目名称设置至 members 项目中。

举例来说,若我们的工作空间底下有 lib1、lib2 这两个程序项目,则 Cargo.toml 设置档的内容如下:

[workspace]
members = [
    "lib1",
    "lib2"
]

接着将程序项目加入至工作空间中,或是直接在工作空间中创建出新的程序项目。举例来说,若我们的工作空间底下有 lib1、lib2 这两个程序项目,则工作空间的文件目录结构如下:

├── Cargo.toml
├── lib1
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── lib2
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── (target)
└── (Cargo.lock)

工作空间目录中的 target 目录和 Cargo.lock 会在编译整个工作空间时自动产生出来。

安装 crates.io 上的可运行程序

除了函数库可以被发布到 crates.io 上之外,可运行的应用程序项目也是可以的。如果要直接将 crates.io 上的应用程序项目安装(下载然后编译)到自己电脑上运行,可以使用 cargo install 指令。

举例来说,如果要安装 ripgrep 这个工具型的应用程序的话,指令如下:

cargo install ripgrep

以 cargo install 安装 ripgrep

安装的可执行文件会放置在家目录中的 .cargo/bin 目录下,如果 PATH 环境变量有包含家目录中的 .cargo/bin 目录,就可以直接在终端机输入可执行文件名称来运行程序。

运行安装好的 rg 指令

扩充 Cargo 的功能

使用以下指令,可以看到目前 Cargo 所支持的命令:

cargo --list

以 cargo --list 列出支持的命令

如果要扩充 Cargo 能够使用的命令,我们可以将可执行文件命名成 cargo-something,放置在家目录中的 .cargo/bin 目录下,something 即为我们想要使用的命令名称。

举例来说,我们将 Hello World 的可执行文件命名为 cargo-hello,并存放到家目录中的 .cargo/bin 目录下。之后只要输入 cargo hello 指令就可以运行到 cargo-hello 这个文件。

以 cargo hello 运行 cargo-hello

由于 cargo install 指令会将 crates.io 上的可运行程序项目所编译出来的可执行文件也安装至家目录中的 .cargo/bin 目录下,所以在 crates.io 上以 cargo- 前缀来命名的可运行程序项目都可以直接透过 cargo install 指令,在安装之后扩充 Cargo 的功能。

总结

Cargo 是个很方便的 Rust 程序项目管理工具,除了可以用来产生、编译、运行、测试、管理程序项目,还可以帮助我们下载 crates.io 上的套件到我们的程序项目中,或是直接安装至操作系统环境。如果我们想要分享自己的程序项目至 crates.io,也可以使用 Cargo 来快速发布。

下一章节,我们将会学习指针的高级用法。

下一章:智能型指针。