Rust编程语言入门之cargo、crates.io

cargo、crates.io本章内容

• 通过 release profile 来自定义构建
• 在https://crates.io/上发布库
• 通过 workspaces 组织大工程
• 从 https://crates.io/来安装库
• 使用自定义命令扩展 cargo

一、通过 release profile 来自定义构建release profile （发布配置）

• release profile：
  • 是预定义的
  • 可自定义：可使用不同的配置，对代码编译拥有更多的控制
• 每个 profile 的配置都独立于其它的 profile
• cargo 主要的两个 profile：
  • dev profile：适用于开发，cargo build
  • release profile：适用于发布，cargo build –release

自定义 profile

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

[package]name = "closure"version = "0.1.0"edition = "2021"# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html[dependencies][profile.dev]opt-level = 1[profile.release]opt-level = 3

执行

closure on  master [?] is ? 0.1.0 via ? 1.67.1 took 2.9s ➜ cargo build   Compiling closure v0.1.0 (/Users/qiaopengjun/rust/closure)    Finished dev [optimized + debuginfo] target(s) in 0.16sclosure on  master [?] is ? 0.1.0 via ? 1.67.1 ➜ 

• 对于每个配置的默认值和完整选项，请参见：https://doc.rust-lang.org/cargo/

二、发布 crate 到 crates.io （1）Crates.io

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

文档注释

• 文档注释：用于生成文档
  • 生成 HTML 文档
  • 显式公共 API 的文档注释：如何使用API
  • 使用 ///
  • 支持 Markdown
  • 放置在被说明条目之前

生成 HTML 文档的命令

• cargo doc
  • 它会运行 rustdoc 工具（Rust 安装包自带）
  • 把生成的 HTML 文档放在 target/doc 目录下
• cargo doc –open：
  • 构建当前crate的文档（也包含 crate 依赖项的文档）
  • 在浏览器打开文档

/// 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}

运行

closure on  master [?] is ? 0.1.0 via ? 1.67.1 ➜ cargo doc   Documenting closure v0.1.0 (/Users/qiaopengjun/rust/closure)    Finished dev [optimized + debuginfo] target(s) in 0.39sclosure on  master [?] is ? 0.1.0 via ? 1.67.1 ➜ cargo doc --open    Finished dev [optimized + debuginfo] target(s) in 0.00s     Opening /Users/qiaopengjun/rust/closure/target/doc/closure/index.htmlclosure on  master [?] is ? 0.1.0 via ? 1.67.1 ➜ cargo doc --open Documenting closure v0.1.0 (/Users/qiaopengjun/rust/closure)    Finished dev [optimized + debuginfo] target(s) in 0.41s     Opening /Users/qiaopengjun/rust/closure/target/doc/closure/index.htmlclosure on  master [?] is ? 0.1.0 via ? 1.67.1 

常用章节

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

文档注释作为测试

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

/// Adds one to the number given./// /// # Examples/// /// ```/// let arg = 5;/// let answer = closure::add_one(arg);/// /// assert_eq!(6, answer);/// ```pub fn add_one(x: i32) -> i32 {    x + 1}

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

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

//! # Closure Crate//! //! `closure` is a collection of utilities to make performance//! calculations more convenient./// Adds one to the number given./// /// # Examples/// /// ```/// let arg = 5;/// let answer = closure::add_one(arg);/// /// assert_eq!(6, answer);/// ```pub fn add_one(x: i32) -> i32 {    x + 1}

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

• 问题：crate 的程序结构在开发时对于开发者很合理，但对于它的使用者不够方便
  • 开发者会把程序结构分为很多层，使用者想找到这种深层结构中的某个类型很费劲
• 例如：
  • 麻烦：my_crate::some_module::another_module::UsefulType;
  • 方便：my_crate::UsefulType;
• 解决办法：
  • 不需要重新组织内部代码结构
  • 使用pub use：可以重新导出，创建一个与内部私有结构不同的对外公共结构

//! # Art//! //! A library for modeling artistic concepts.pub mod kinds {    /// The primary colors according to the RYB color model.    pub enum PrimaryColor {        Red,        Yellow,        Blue,    }    /// The secondary colors according to the RYB color model.    pub enum SecondaryColor {        Orange,        Green,        Purple,    }}pub mod utils {    use crate::kinds::*;    /// Combines two primary colors in equal amounts to create    /// a secondary color.    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {        SecondaryColor::Green    }}

src/main.rs 文件

use art::kinds::PrimaryColor;use art::utils::mix;fn main() {    let red = PrimaryColor::Red;    let yellow = PrimaryColor::Yellow;    mix(red, yellow);}

优化之后：

src/lib.rs 文件

//! # Art//! //! A library for modeling artistic concepts.pub use self::kinds::PrimaryColor;pub use self::kinds::SecondaryColor;pub use self::utils::mix;pub mod kinds {    /// The primary colors according to the RYB color model.    pub enum PrimaryColor {        Red,        Yellow,        Blue,    }    /// The secondary colors according to the RYB color model.    pub enum SecondaryColor {        Orange,        Green,        Purple,    }}pub mod utils {    use crate::kinds::*;    /// Combines two primary colors in equal amounts to create    /// a secondary color.    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {        SecondaryColor::Green    }}

src/main.rs 文件

// use art::kinds::PrimaryColor;// use art::utils::mix;use art::PrimaryColor;use art::mix;fn main() {    let red = PrimaryColor::Red;    let yellow = PrimaryColor::Yellow;    mix(red, yellow);}

四、发布 crate 到 crates.io（2）创建并设置 Crates.io 账号

• 发布 crate 前，需要在 crates.io 创建账号并获得 API token
• 运行命令：cargo login [你的 API token]
  • 通知 cargo，你的 API token 存储在本地 ~/.cargo/credentials
• API token 可以在https://crates.io/进行撤销

为新的crate 添加元数据

• 在发布crate之前，需要在 Cargo.toml 的 [package] 区域为 crate 添加一些元数据：
  • crate 需要唯一的名称：name
  • description：一两句话即可，会出现在 crate 搜索的结果里
  • license：需提供许可证标识值（可到 http://spdx.org/licenses/查找）
    • 可指定多个 license：用 OR
  • version
  • author
• 发布：cargo publish 命令

rust_tutorials on  master [?] via ? 1.67.1 ➜ cargo login --registry crates-io               please paste the token found on https://crates.io/me belowciopLk54SDAxB200gA4jk85abcdefgabcabc # token       Login token for `crates-io` savedrust_tutorials on  master [?] via ? 1.67.1 took 1m 27.6s ➜ rust_tutorials on  master [?] via ? 1.67.1 took 2.0s ➜ cargo publish --registry crates-io --allow-dirty    Updating crates.io index

发布到 Crates.io

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

发布已存在 crate 的新版本

• 修改 crate 后，需要先修改 Cargo.toml 里面的version 值，再进行重新发布
• 参照http://semver.org/来使用你的语义版本
• 再执行 cargo publish 进行发布

使用 cargo yank 从 Crates.io 撤回版本

• 不可以删除 crate 之前的版本
• 但可以防止其它项目把它作为新的依赖：yank（撤回）一个 crate 版本
  • 防止新项目依赖于该版本
  • 已经存在项目可继续将其作为依赖（并可下载）
• yank 意味着：
  • 所有已经产生 Cargo.lock 的项目都不会中断
  • 任何将来生成的 Cargo.lock 文件都不会使用被 yank 的版本
• 命令：
  • yank 一个版本（不会删除任何代码）：cargo yank –vers 1.0.1
  • 取消 yank：cargo yank –vers 1.0.1 –undo

五、Cargo 工作空间Cargo 工作空间（Workspaces）

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

创建工作空间

• 有多种方式来组建工作空间例：1个二进制 crate，2个库 crate
  • 二进制 crate：main函数，依赖于其它2个crate
  • 其中1个库crate 提供 add_one 函数
  • 另外1个库crate 提供 add_two 函数

~/rust➜ mcd add  # mkdir add cd add~/rust/add➜ touch Cargo.toml~/rust/add via ? 1.67.1➜ c  # code .~/rust/add via ? 1.67.1➜~/rust/add via ? 1.67.1➜ cargo new adderwarning: compiling this new package may not work due to invalid workspace configurationcurrent package believes it's in a workspace when it's not:current:   /Users/qiaopengjun/rust/add/adder/Cargo.tomlworkspace: /Users/qiaopengjun/rust/add/Cargo.tomlthis may be fixable by adding `adder` to the `workspace.members` array of the manifest located at: /Users/qiaopengjun/rust/add/Cargo.tomlAlternatively, to keep it out of the workspace, add the package to the `workspace.exclude` array, or add an empty `[workspace]` table to the package's manifest.     Created binary (application) `adder` package~/rust/add via ? 1.67.1➜ cargo build   Compiling adder v0.1.0 (/Users/qiaopengjun/rust/add/adder)    Finished dev [unoptimized + debuginfo] target(s) in 0.48s~/rust/add via ? 1.67.1~/rust/add via ? 1.67.1➜ cargo new add-one --lib     Created library `add-one` package~/rust/add via ? 1.67.1➜

add-one/src/lib.rs 文件

pub fn add_one(x: i32) -> i32 {    x + 1}

adder/src/main.rs 文件

use add_one;fn main() {    let num = 10;    println!("Hello, world! {} plus one is {}", num, add_one::add_one(num));}

adder/Cargo.toml 文件

[package]name = "adder"version = "0.1.0"edition = "2021"# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html[dependencies]add-one = { path = "../add-one" }

rust/add/Cargo.toml 文件

[workspace]members = [    "adder",    "add-one",]

运行

~/rust/add via ? 1.67.1 ➜ cargo build               Compiling add-one v0.1.0 (/Users/qiaopengjun/rust/add/add-one)   Compiling adder v0.1.0 (/Users/qiaopengjun/rust/add/adder)    Finished dev [unoptimized + debuginfo] target(s) in 0.30s~/rust/add via ? 1.67.1 ➜ cargo run -p adder                    Finished dev [unoptimized + debuginfo] target(s) in 0.00s     Running `target/debug/adder`Hello, world! 10 plus one is 11~/rust/add via ? 1.67.1 ➜ 

在工作空间中依赖外部 crate

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

为工作空间添加测试

rust/add/add-one/src/lib.rs 文件

pub fn add_one(x: i32) -> i32 {    x + 1}#[cfg(test)]mod tests {    use super::*;    #[test]    fn it_works() {        assert_eq!(3, add_one(2));    }}

执行测试

~/rust/add via ? 1.67.1 ➜ cargo test           Compiling add-one v0.1.0 (/Users/qiaopengjun/rust/add/add-one)   Compiling adder v0.1.0 (/Users/qiaopengjun/rust/add/adder)    Finished test [unoptimized + debuginfo] target(s) in 0.13s     Running unittests src/lib.rs (target/debug/deps/add_one-cb079acb8d173784)running 1 testtest tests::it_works ... oktest result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s     Running unittests src/main.rs (target/debug/deps/adder-23a2e001f7410351)running 0 teststest result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s   Doc-tests add-onerunning 0 teststest result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s~/rust/add via ? 1.67.1 ➜ ~/rust/add via ? 1.67.1 ➜ cargo test -p add-one                          Finished test [unoptimized + debuginfo] target(s) in 0.00s     Running unittests src/lib.rs (target/debug/deps/add_one-cb079acb8d173784)running 1 testtest tests::it_works ... oktest result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s   Doc-tests add-onerunning 0 teststest result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s~/rust/add via ? 1.67.1 ➜ 

六、从 CRATES.IO 安装二进制 crate从 CRATES.IO 安装二进制 crate

• 命令：cargo install
• 来源：https://crates.io
• 限制：只能安装具有二进制目标（binary target）的 crate
• 二进制目标 binary target：是一个可运行程序
  • 由拥有 src/main.rs 或其它被指定为二进制文件的 crate 生成
• 通常：README 里有关于 crate 的描述：
  • 拥有 library target
  • 拥有 binary target
  • 两者兼备

cargo install

• cargo install 安装的二进制存放在根目录的 bin 文件夹
• 如果你用 rustup 安装的 Rust，没有任何自定义配置，那么二进制存放目录是 $HOME/.cargo/bin
  • 要确保该目录在环境变量 $PATH 中

~/rust took 2m 8.1s➜ cargo install rust_tutorials_qiao    Updating `tuna` index  Downloaded rust_tutorials_qiao v0.1.0 (registry `tuna`)  Downloaded 1 crate (759 B) in 3.43s  Installing rust_tutorials_qiao v0.1.0   Compiling rust_tutorials_qiao v0.1.0    Finished release [optimized] target(s) in 3.99s  Installing /Users/qiaopengjun/.cargo/bin/rust_tutorials_qiao   Installed package `rust_tutorials_qiao v0.1.0` (executable `rust_tutorials_qiao`)~/rust took 4.0s➜➜ rust_tutorials_qiaoHello, world!~/rust took 3.1s➜~/rust took 3.1s➜ echo $PATH  # 查看PATH环境变量

使用自定义命令扩展 cargo

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

➜ cargo --listInstalled Commands:    add                  Add dependencies to a Cargo.toml manifest file    b                    alias: build    bench                Execute all benchmarks of a local package    build                Compile a local package and all of its dependencies    c                    alias: check    check                Check a local package and all of its dependencies for errors    clean                Remove artifacts that cargo has generated in the past    clippy               Checks a package to catch common mistakes and improve your Rust code.    config               Inspect configuration values    d                    alias: doc    doc                  Build a package's documentation    fetch                Fetch dependencies of a package from the network    fix                  Automatically fix lint warnings reported by rustc    fmt                  Formats all bin and lib files of the current crate using rustfmt.    generate-lockfile    Generate the lockfile for a package    git-checkout         This command has been removed    help                 Displays help for a cargo subcommand    init                 Create a new cargo package in an existing directory    install              Install a Rust binary. Default location is $HOME/.cargo/bin    locate-project       Print a JSON representation of a Cargo.toml file's location    login                Save an api token from the registry locally. If token is not specified, it will be read from stdin.    logout               Remove an API token from the registry locally    metadata             Output the resolved dependencies of a package, the concrete used versions including overrides, in machine-readable format    miri    new                  Create a new cargo package at     owner                Manage the owners of a crate on the registry    package              Assemble the local package into a distributable tarball    pkgid                Print a fully qualified package specification    publish              Upload a package to the registry    r                    alias: run    read-manifest        Print a JSON representation of a Cargo.toml manifest.    remove               Remove dependencies from a Cargo.toml manifest file    report               Generate and display various kinds of reports    rm                   alias: remove    run                  Run a binary or example of the local package    rustc                Compile a package, and pass extra options to the compiler    rustdoc              Build a package's documentation, using specified custom flags.    search               Search packages in crates.io    t                    alias: test    test                 Execute all unit and integration tests and build examples of a local package    tree                 Display a tree visualization of a dependency graph    uninstall            Remove a Rust binary    update               Update dependencies as recorded in the local lock file    vendor               Vendor all dependencies for a project locally    verify-project       Check correctness of crate manifest    version              Show version information    yank                 Remove a pushed crate from the index~/rust

本文来自博客园，作者：QIAOPENGJUN，转载请注明原文链接：https://www.cnblogs.com/QiaoPengjun/p/17301329.html