【跟小嘉学 Rust 编程】十四、关于 Cargo 和 Crates.io

系列文章目录

【跟小嘉学 Rust 编程】一、Rust 编程基础
【跟小嘉学 Rust 编程】二、Rust 包管理工具使用
【跟小嘉学 Rust 编程】三、Rust 的基本程序概念
【跟小嘉学 Rust 编程】四、理解 Rust 的所有权概念
【跟小嘉学 Rust 编程】五、使用结构体关联结构化数据
【跟小嘉学 Rust 编程】六、枚举和模式匹配
【跟小嘉学 Rust 编程】七、使用包(Packages)、单元包(Crates)和模块(Module)来管理项目
【跟小嘉学 Rust 编程】八、常见的集合
【跟小嘉学 Rust 编程】九、错误处理(Error Handling)
【跟小嘉学 Rust 编程】十一、编写自动化测试
【跟小嘉学 Rust 编程】十二、构建一个命令行程序
【跟小嘉学 Rust 编程】十三、函数式语言特性：迭代器和闭包
【跟小嘉学 Rust 编程】十四、关于 Cargo 和 Crates.io

前言

到目前为止，我们讲解了 Cargo 的最基本的特性来构建、运行、测试代码，但是它可以为我们做更多的事情。本章节讲解 Cargo 更高级的特性，例如：

1. 通过 release profile 来自定义构建
2. 在 crates.io 上发布库文件
3. 通过 workspaces 组织大工程
4. 从 crates.io 来安装库
5. 使用自定义命令扩展 cargo

主要教材参考 《The Rust Programming Language》

---

一、发布配置(Release profile)

1.1、发布配置(Release profile)

发布配置(Release profile) 是 预定义的，也可以自定义(可以使用不同的配置) 对代码编译拥有更多的控制。每个Profile的配置都独立于其他的Profile。

Cargo 主要两个 Profile：

• dev profile：适用于开发(开发环境)， cargo build
• release profile：适用于发布(生产环境)，cargo build --release

1.2、自定义 profile

针对每个 profile，Cargo 都提供了默认的配置，如果想自定义 xxx profile 的配置，可以在 cargo.toml 里面添加 [profile.xxx] 区域，在里面覆盖默认配置的子集。

[profile.dev]
opt-level = 0[profile.release]
opt-level = 3

opt-level 参数表示优化级别，编译时间比较久。针对每个配置的默认值和完整选项，可以参考 profile

二、发布 crates.io

2.1、crates.io

可以通过发布包来共享你的代码，crate 的注册表 在 crates.io 上，它会分发已注册的包的源代码，主要托管开源的代码。

2.2、文档注释

2.2.1、文档注释介绍

文档注释用于生成HTML文档，显式公共 API的文档注释（如何使用API），使用 /// 来表示 支持markdown 语法。

使用 cargo doc 可以生成文档，它会运行 rustdoc 工具，把生成的HTML文档放在 target/doc 目录下。

使用 cargo doc --open 可以打开生成的文档。

2.2.2、常用章节

• Examples：示例代码
• Panics：函数可能发生 panic 的场景
• Errors：如果函数返回 Result，描述可能的错误种类，以及可导致错误的条件
• Safety：如果函数处于 unsafe 调用，就可以解释函数 unsafe 的原因，以及调用者确保使用的前提。

2.2.3、文档注释作为测试

示例代码块的附加值：运行 cargo test 可以把文档注释中的示例代码作为测试来运行。

2.2.4、为包含注释的项添加文档注释

• 符号：//!
• 此类注释通常用于描述 crate 和模块：
  • crate root (按照惯例 src/lib.rs)
  • 一个模块内，将 crate 或模块作为一个整体进行记录

2.3、pub use

使用 pub use 导出方便使用的公共 API。

2.4、发布 crate 步骤

一旦发布，就是永久性，该版本无法覆盖，代码无法删除，目的：依赖于该版本的项目可继续正常工作

1、创建并设置 crate.io 账号，并且获得 api token

2、 运行命令： cargo login [api token]，通知 cargo ，你的 api token 存储在本地 ～/.cargo/credentials

3、发布之前需要 在 [package] 上设置元数据。

• crate 需要唯一的名称：name
• description：一两句话即可
• license：需要提供许可证的标识值(可以在 http://spdx.org/licenses/ 查找)。
• version：可以参照 http://semver.org 来使用你的语义版本
• author

4、发布：使用 cargo publish 命令

5、使用 cargo yank 撤回版本：

• 不可以删除 crate 之前的版本
• 但是可以防止其他项目把它作为新的依赖，但是已经存在的项目可以继续作为依赖

三、Cargo 工作空间(Workspaces)

3.1、工作空间

Cargo 工作空间，帮助管理多个相互关联需要协同开发的 crate。cargo 工作空间就是一套共享同一个 cargo.lock和输出文件夹的包。

3.2、创建工作空间

[workspace]
members = ["adder"
]

运行 ：cargo run -p 二进制crate

3.3、在工作空间依赖外部 crate

工作空间只有一个 cargo.lock，在工作空间的顶层目录，保证工作空间内所有 crate 的使用的依赖的版本都相同，工作空间内所有 crate 相互兼容。

四、安装 二进制 crate

• 命令 cargo install

• 来源：crates.io

• 限制：只能安装具有二进制目标（binary target）的crate

  • 二进制目标 （binary target）是一个可运行的程序，由 src/main.rs 或其他被指定为二进制文件的crate 生成

• 通常在 README 里面有关于 crate 的描述

  • 拥有 binary target
  • 拥有 library target
  • 两者兼备

• cargo install 安装的二进制目录存在根目录的bin文件夹

• 如果你使用 rustup 安装的 rust 没有任何自定义配置，那么二进制文件将存放在 $HOME/.cargo/bin。

五、使用自定义命令扩展 cargo

• cargo 被设计成可以使用自命令扩展
• 如果$PATH中的某个二进制文件是 cargo-something，你可以像子命令一样运行：cargo something。
• 类似这样的自定义命令可以通过该命令列出：cargo --list
• 优点：可以使用cargo install 来安装扩展，像内置工具一样来使用。

总结

以上就是今天要讲的内容