Rust(十四)-cargo,crates.io

木吾木同
325 阅读5分钟

通过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]区域，在里面覆盖默认配置的子集
        [profile.dev]
  opt-level = 0

  [profile.release]
  opt-level = 3

在crates.io/上发布库

  • crates.io
    • 可以通过发布包来共享你的代码
    • crate的注册表在 crates.io/
      • 它会分发已注册的包的源代码
      • 主要托管开源的代码
  • 文档注释
    • 文档注释： 用于生成文档
      • html文档
      • 显式公共api的文档注释：如何使用api
      • 使用 ///
      • 支持markdown
      • 放置在被说明条目之前
      • cargo doc
      /// 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
}
    • 生成html文档的命令
      • cargo doc
        • 它会运行rustdoc工具（Rust安装包自带）
        • 把生成的html文档放在target/doc 目录下
      • cargo doc --open
  • 常用章节
    • #Examples
    • 其它常用的章节
      • Panics: 函数可能发生panic的场景
      • Errors: 如果函数返回Result,描述可能的错误种类， 以及可导致错误的条件
      • Safety: 如果函数处于unsafe调用，就应该解释函数unsafe的原因， 以及调用者确保的使用前提。
  • 文档注释作为测试
    • 示例代码块的附加值
      • 运行cargo test：将把文档注释中的示例代码作为测试运行
      • 例子
  • 为包含注释的项添加文档注释
    • 符号： //！
    • 这类注释通常用描述crate和模块
      • crate root (按惯例src/lib.rs)
      • 一个模块内，将crate或模块作为一个整体进行记录

pub use

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

创建并设置crates.io账号

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

为新的crate添加元数据

  • 在发布crate之前，需要在cargo.toml的[package]区域为crate添加一些元数据：
    • crate 需要要唯一的名称：name
    • description: 一两句话即可，会出现在crate搜索的结果里
    • license： 需要供许可证标识值（可到spdx.org/licenses/ 查找）
      • 可指定多个license: 用OR
      • version
      • author
    • 发布：cargo publish 命令
  • 发布到crates.io
    • crate 一旦发布，就是永久性的：该版本无法覆盖，代码无法删除
      • 目的：依赖于该版本的项目可继续正常工作
  • 发布已存在carte的新版本
  • 使用cargo yank 从 crates.io撤回版本
    • 不可以删除carte之前的版本
    • 但可以防止其它项目把它作为新的依赖：yank(撤回) 一个crate版本
      • 防止新项目依赖于该版本
      • 已经存在项目可继续将其作为依赖（并可下载）
    • yank意味着：
      • 所有已经产生cargo.lock的项目都不会中断
      • 任何将来生成的cargo.lock文件都不会使用被yank的版本
    • 命令：
      • yank 一个版本（不会删除任何代码）：cargo yank --vers 1.0.1
      • 取消yank： cargo yank --vers 1.0.1 --undo

cargo 工作空间（workspaces）

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

创建工作空间

  • 有多种方式来组建工作空间例：1个二进制crate,2个库crate
    • 二进制cate:main函数，依赖于其它2个库crate
    • 其中1个库crate提供add_one函数
    • 另外1个库crate提供add_two函数
  • 在工作空间中依赖外部crate
    • 工作空间只有一个cargo.lock文件，在工作空间的顶层目录
      • 保证工作空间内所有crate使用的依赖的版本都相同
      • 工作空间内所有crate相互兼容
  • 为工作空间添加测试

从crates.io安装二进制crate

  • 命令： cargo install
  • 来源：crates.io
  • 限制：只能安装具有二进制目标（binary target）的 crate
  • 二进制目标 binary target: 是一个可运行

使用自定义命令扩展cargo

  • 从CRATES.IO安装二进制crate
    • 命令：cargo install
    • 来源： crate.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中
  • 使用自定义命令扩展cargo
    • cargo被设计成可以使用子命令来扩展
    • 例：如果$PATH中的某个二进制是cargo-something，你可以像子命令一样运行：
      • cargo something
    • 类似这样的自定义命令可以通过该命令列出：cargo --list
    • 优点：可使用cargo install来安装扩展，像内置工具一样来运行
avatar
文章
阅读
粉丝