Rust编程-crates.io

        发布配置和开发配置：

        [profile.dev]:   > cargo build

                opt-level=0

        [profile.release]: > cargo build --release 

                 opt-level=3

发布到crates.io

        文档注释：没有使用位置的限制，但最终会在target/doc/[crate]/index.html中体现出来

                文档注释有两种：/// 和//!  ,其中，/// 用于条目； //！用于lib的根

                三斜线（///），使用markdown语法来格式化内容

                可以为函数编写文档注释

                在/// 中可以使用```来定义example

                cargo doc命令，基于文档注释生成html文档；cargo doc --open 生成html文档并在浏览器里打开

                在target/doc/[crate]/index.html路径下生成HTML文档

                编写注释文档需要注意：

                        Panics区域：指出函数可能发生panic的场景

                        Errors区域：函数返回Result的时候，可能会返回Err

                        Safety区域：函数使用了unsafe关键字

注：

        cargo doc 

        cargo doc --open

        cargo test

        cargo test --doc

这些命令最终都是使用的rustdoc 或者 rustc命令

        文档注释可用作测试：

                        cargo test会在执行时将文档注释中的代码示例作为测试去运行。（这样设计的目的是为了让文档和代码功能能够保持同步），cargo test --doc 命令只会执行文档中的测试。

        包或模块文档注释：//!

                通常被用在包的根文件（也就是惯例上的 src/libs.rs ）或模块的根文件上。

                通过它们来描述外部条目的整体意图可以帮助用户理解包的组织结构。例如：

#![crate_name = "doc"]

#![...] 形式的语法用于配置整个 crate 的元数据或者启用某些特性。在这个例子中，crate_name 属性用来指定 crate 的名称，这对于文档生成和其他元数据处理非常有用。

pub use来导出公共API

        pub use来重新导出部分条目，可以让用户使用use的时候不用考虑包的内部结构。

创建crates.io账户

        crates.io上注册一个账户并获取一个API令牌（API token）

        命令登录：cargo login abcdefghijklmnopqrstuvwxyz012345 ，Cargo将你的API令牌存入～/.cargo/credentials文件中

为包添加元数据：

         在Cargo.toml 文件的[package]区域中为包添加一些元数据（metadata）。

[package]
name = "xxx"
description=""
version = "0.1.0"
authors = ["<you@example.com>"]
edition = "2018"
license = "MIT" // Linux基金会的Software Package Data Exchange（SPDX）中给出了所有可用的许可协议标识符

        SPDX文档范围之外的许可证，需要将许可协议的文本以文件形式放置在项目目录中，并使用license-file字段指定文件名称，而不需要license字段来指定。

        发布命令：cargo publish

        总结：

        发布前的准备工作：

                1. 创建账户

                2. 存储API令牌

                3. 为包选择名称等任务

                4. 指定了必要的元数据

cargo.io上移除版本

        cargo yank --vers 1.0.1

        cargo yank --vers 1.0.1 --undo // 取消撤回

 工作空间 （workspace）:

        将包拆分成多个代码包

        工作空间是由共用同一个Cargo.lock 和输出目录的一系列包所组成的。

        工作空间来创建一个项目:

                1. 创建一个文件夹：mkdir add

                2. add目录下添加cargo.toml文件

                3. add目录下添加adder二进制代码包

                        cargo new adder

                4. cargo build来构建整个工作空间

                5. target 目录用来存放所有成员的编译产出物，adder包也就没有了自己独立的target 目录

                6. 整个工作空间只在根目录下有一个Cargo.lock

                7. 调用cargo test会一次性执行工作空间中所有包的测试。

        Cargo.toml配置：

[workspace]
members = ["adder"]

        工作空间的包的相互依赖：

adder/Cargo.toml
[dependencies]
add-one = { path = "../add-one" } // 依赖内部其他包，指定path

        工作空间依赖外部包：

        整个工作空间只在根目录下有一个Cargo.lock

        确保了所有的内部包都会使用完全相同的依赖版本

        

       工作空间单元测试： 

        cargo test会一次性执行工作空间中所有包的测试。

        cargo test -p add-one 为某个包运行单元测试

cargo install：

        安装和使用二进制包

        获得其他人在crates.io上分享的工具，只能安装二进制目标（binary target）的包。

        二进制目标：包内存在src/main.rs 或其他被指定为二进制入口的文件

        库目标：本身无法单独执行但非常适合被包含在其他程序中。

        cargo install命令安装的二进制文件都会被存储在Rust安装根目录下的bin 文件夹中

        bin 的路径就是$HOME/.cargo/bin 。为了能够直接运行cargo install安装的工具程序，我们需要将该路径添加到环境变量$PATH中

        $PATH路径中存在二进制文件cargo-something，就可以通过运行cargo something来运行该二进制文件

        cargo --list可以列出所有的自定义命令