rust学习十四.1、编译和发布单元包Crate

本文简要介绍如何编译和发布单元包(crate)。

很可惜的是，找了一会，没有发现可以发布到除了Crates.io之外的地方。可能是我没有找到，也可能仅仅是因为我本人仅是初学者。希望国内的大学和其它机构能够创建那么一个国内的库，避免哪天封禁后，无处可去。

本文对应相关书籍的第十四章节的第1，2子章节。

发布一个单元包的大概过程：

配置库的构建选项等
给代码添加友好的注释
注册Crates.io的账号，并获得令牌和设置邮件。实际是GitHub账户
编译代码（可跳过）
使用cargo login登录
使用cargo publish发布

一、配置构建选项等

主要工作是修改Cargo.toml。

示例配置：

[package]
# 名称- 如果要发布，则必须是唯一
name = "minigrep"
# 版本 -这个可以自己定义
version = "0.1.0"
# 发行版-这个不允许定。截止2024/12 ,只允许 2015,2018,2021,2024
edition = "2021"
description ="一个从文本文件中查找字符的命令行工具。只支持utf8编码的文件"
#许可说明
license = "MIT OR Apache-2.0"

[dependencies]

# 配置说明-开发
[profile.dev]
# 优化级别，默认是0，对于发行是3。此值越小表示优化程度越低。
# 优化越多，编译时间越长
opt-level = 0

# 配置说明-发布
[profile.release]
opt-level = 3

package -包说明

name - 包名称，必须有的。不可在crates.io内重复。先到先得。没有测试过是否可以使用中文，理论上应该可以
vesion -版本，必须有
edition -发行版，必须有，截止2024/12 ,只允许 2015,2018,2021,2024
description - 描述，必须有
license - 许可，必须有。如果不希望个性化的，就简单的按照书本要求的即可。据说这里采用的是linux的spdx符号.

profile.xxx - 分类配置说明

可以不配置，因为默认情况下，开发的时候，采用0级别，发布的时候采用3级别。

opt-level 介于 [0,3], 越大编译花费时间越长，理论上可执行结果性能更好.

其它配置

暂不论，据作者所言，后面的章节还会继续讨论这个问题。所以，我本人也会再以后就cargo这个工具专门编写有关日记。

另外为了发布后好看一点，建议在Cargo.toml同级别目录中创建一个README.md

二、给代码添加友好的注释

重点：

有三种注释，分别是 ///，//!, /**/
注释的部分遵循markdown语法。所以要修改显示布局、样式等等，只需要遵循markdown语法即可
使用 cargo doc --open 确认下效果

///和/**/效果是一样的，看个人习惯

//! 会展示稍微不一样的内容，效果相当于一个序言，概述等

如果要添加代码块，则用··· (波浪线~下那个字符)即可.

示例：

//! minigrep
//! 这是一个单元包概述
//! minigrep 是一个命令行程序，它允许用户搜索文本文件内容。

/// 参数配置结构体
#[derive(Debug)]
pub struct Config {
    /// 被搜索的文件名，可以是全路径（含文件名），也可以不含路径的文件名
    pub file_name: String,
    /// 从被搜索的文件中查找的字符串
    pub target: String,
    /// 是否显示帮助信息.仅当用户输入的第一个参数为 --help 时，该值为 true
    pub show_help: bool,
}

/**
 * 处理参数的模块 <br>
 * 包括 build、is_too_big,show_help
 */
pub mod config {
    use super::Config;
    use std::env;
    use std::fs;
    use std::path::Path;

    /// **构建一个参数配置结构体** <br>
    /// **args** 参数列表 ,数组类型，非空。第一个表示程序路径，第二个为target_name,第三个为file_path <br>
    /// 返回： 参数配置结构体<br>
    /// 异常:   如果参数异常则返回错误信息<br>
    /// 例子：
    /// ```
    /// use std::env;
    /// use minigrep::{config,search};
    /// fn main() {
    ///   let args: Vec<String> = env::args().collect();
    ///   let con=config::build(&args).unwrap_or_else(|err|{
    ///       eprintln!("程序异常:{}",err);
    ///       std::process::exit(1);
    ///     });
    /// }
    /// ```