Rust Lang Book Ch.14 Crates.io
Profiles
Cargo有两大主要的profiles：dev和release。
例如，可以在Cargo.toml里自定义：
[profile.dev] opt-level = 0 [profile.release] opt-level = 3
Publish crate to Crates.io
与一般的两个反斜杠的注释不同，三个反斜杠///就是documentation comments，即用于生成html文档的注释。兼容markdown语法。
示例：
/// 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
}
使用cargo doc之后，会调用rustdoc工具，生成如下文档在target/doc文件夹里：
//!也是文档注释的一种，其文档记录的对象是包含这些//!注释的对象而不是跟在///之后的对象。
比如以下代码在src/lib.rs中：
//! # My Crate //! //! `my_crate` is a collection of utilities to make performing certain //! calculations more convenient. /// Adds one to the number given. // --snip--
能生成针对包含这些注释的my_crate的文档：
pub fn add_two(x: i32) -> i32 {
//! Adds two to the number given
//! ```
//! let arg = 5;
//! let answer = my_crate::add_two(arg);
//!
//! assert_eq!(7, answer);
//! ```
x + 2
}
生成如下文档
cargo doc --open会立刻构建当前crate和其依赖的crate的文档，并且在浏览器打开。
cargo test时也会测试文档的注释。
常用的Sections:
1. Example
2. Panics: 描述会发生panic的场景
3. Errors: 描述会发生的错误，错误发生的条件，处理错误的建议等
4. Safety: 如果该函数是unsafe的，那就需要解释为什么这个函数是unsafe，并且需要描述其中调用者需要保持住的所有的不变量
发布Crate之前的注意事项
1. 如果public API的结构很复杂，比如use my_crate::some_module::another_module::UsefulType，可以通过re-exporting的方式来化简调用格式。pub use my_crate::some_module::another_module::UsefulType
发布
设置Crates.io账号：
1. 在https://crates.io/me/ 注册并且获取API key
2. cargo login <APIKey>
3. 设置package的name,license, version, author, description, edtion, homepack等信息，如果名称和别的crate重复了，在publish时会有提醒。
4. cargo publish
当有新的版本准备发布时，可以用SemVer的格式来写版本号，然后发布
如果某个版本不应该继续发布时，可以使用cargo yank -vers <版本号> 来让这个版本不能继续被新的项目使用，旧的项目当然不能强制撤掉
cargo yank --vers 1.0.1 cargo yank --vers 1.0.1 --undo #撤销yank
Cargo Workspace
为了方便管理，可以用一个workspace来管理一些共享相同Cargo.lock和输出文件夹的packages。在workspace的根目录下，需要放一个Cargo.toml，里面不用[package]，而是放[workspace]，workspace底下的member是一个包含packages的名称的字符串数组。
示例：
Cargo.toml
[workspace]
members = [
"adder",//a binary package
"add-one",//a library package
"add-two",
]
├── Cargo.lock ├── Cargo.toml ├── add-one │ ├── Cargo.toml │ └── src │ └── lib.rs//cargo new add-one --lib ├── adder │ ├── Cargo.toml │ └── src │ └── main.rs └── target
在依赖其他库的库中，在dependencies就可以使用相对路径来确认其他被依赖的package的位置：
adder/Cargo.toml
[dependencies]
add-one = { path = "../add-one" }
注意在顶层的Cargo.toml加了外部依赖包也没用，要在真正使用的crate对应的Cargo.toml中再次引用一次，不过Cargo会保证每个外部包只下载一次，而且版本尽量兼容。
cargo run和cargo test都可以通过-p来指定要对哪个package进行操作。不过cargo publish没有，必须要进入到要发布的crate的目录下。
cargo install
能够下载binary crate到本地，可以当作工具运行。此外，如果binary的名字叫做cargo-sth，那就可以直接运行cargo sth这个指令来调用对应的工具，达到自定义cargo命令的作用。
