《Rust权威指南》 第14章 进一步认识cargo和crates.io

使用发布配置来定制构建

在Cargo.toml文件的[profile.*]区域可以定义构建选项
默认是

[profile.dev]
opt-level = 0

[profile.release]
opt-level = 3

• opt-level是编译器优化级别，最低是0，最高是3
• 上面的意思是，默认下使用cargo buld做的是最低的优化；cargo build --release做的是最高的优化

将包发布到crates.io

编写有用的文档注释

• 使用三斜线///为紧随注释后的条目编写文档注释，接受markdown语法，使用cargo doc可以基于注释在target/doc目录下生成HTML文档

• 使用//!为包裹当前注释的外部条目添加文档

  • 该方式通常适用于为包的根文件(mian.rs lib.rs)添加注释

• 运行cargo test时，会对文档注释的实例代码(被```包裹)继续测试，也就是除了单元测试、集成测试外最后一个测试区域：文档测试

使用pub use导出合适的公共API

使用pub use重新导出部分条目，从而建立一套和内部结构不同的对外结构
这是因为，开发包和使用包是两个不同的场景

• 开发包时，可能会为了较好的组织代码构造一个比较复杂的树结构
• 使用包时，使用者可能只会使用到部分的公共API，却不得不使用类似包名::A::B::C::D::f()这样的语法
• 此时在包开发时就使用pub use来重新组织对外结构，是一种好做法

创建crates.io账户

访问crates.io并使用github账户登录
访问账户设置页面获取API令牌

使用

cargo login 令牌

为包添加元数据

即Cargo.toml文件的[package]区域

• 包的名称（唯一）
• 描述
• 许可协议
• 版本信息
• 作者信息

发布

使用cargo publish将包发布到crate.io
注意：已经上传的版本无法被覆盖，对应的代码也不能被删除

发布已有包的新版本

修改Cargo.toml文件中[package]区域下的version字段，并重新运行cargo publish

撤回版本

使用

cargo yank --vers 版本号

将当前包的特定版本撤回。
撤回的影响是，对那些依赖这个包的其它包

• 已经产生Cargo.lock的，没有什么影响
• 未产生Cargo.lock的，不再能依赖于这个版本

Cargo 工作空间

管理多个相互关联且需要协同开发的包

• 创建一个作为工作空间的目录
• 在该目录下创建Cargo.toml文件，然后键入

[workspace]

members = [
    "adder","add_one"
]

• 在[workspace]的members字段内，允许我们以包的路径来为工作空间添加成员
• 在add目录下运行下面的指令将包添加进去

cargo new adder
cargo new add_one --lib

到此为止，整个工作空间的文件结构类似于

在工作空间中创建包之间的依赖

比如：让adder包依赖于add_one包

• 首先在adder/Cargo.toml中的[dependencies]区域添加包add_one的路径

  [dependencies]
  
  add_one ={ path = "../add_one"}
  

• 当adder包需要使用add_one包的内容时，只需要use add_one

依赖外部包

• 在需要引入外部包的那些包的toml文件的[dependencies]区域引入即可
• 但是Cargo.lock文件只存在于工作空间的根目录，这保证了工作空间中所有包对外部的依赖是一致的，且同名的外部包只被下载编译一次