Cargo.toml

# ============================================================
#  Cargo.toml  — 一个全面、标准的 Rust 项目配置文件（带注释）
# ============================================================

# -----------------------------------------------------------------
#  [package]  包的元信息（所有发布到 crates.io 的字段）
# -----------------------------------------------------------------
[package]
name = "gowater"                          # 包名（也作为默认二进制名称）
version = "0.1.0"                         # 语义化版本号
edition = "2021"                          # Rust 版本规范（2015/2018/2021/2024）
resolver = "2"                            # 依赖解析器版本（2021 版默认即 "2"，可省略）
description = "一个带有详细注释的示例项目"   # 项目简短描述
license = "MIT OR Apache-2.0"             # SPDX 标识符，发布必备
repository = "https://github.com/user/gowater"  # 源码仓库
homepage = "https://example.com/gowater"  # 项目主页
documentation = "https://docs.rs/gowater" # 文档地址（通常由 docs.rs 自动生成）
readme = "README.md"                      # 自述文件
keywords = ["demo", "example", "tutorial"] # 关键词，最多 5 个
categories = ["command-line-utilities"]   # 分类，必须来自 crates.io 已有列表
build = "build.rs"                        # 构建脚本（如果存在）
# links = "myclib"                        # 若链接到 C 库，声明库名，防止冲突

# -----------------------------------------------------------------
#  [dependencies]  运行时依赖
# -----------------------------------------------------------------
[dependencies]
# 最简写法：版本字符串，等同于 version = "1.0"
anyhow = "1.0"

# 带 features 的依赖，且声明为可选（只有启用相关 feature 时才会编译）
serde = { version = "1.0", features = ["derive"], optional = true }

# 禁用默认 features，手动开启所需的特性，减少编译体积
tokio = { version = "1", default-features = false, features = [
    "rt-multi-thread",
    "macros",
], optional = true }

# 本地路径依赖（同仓库内的其他 crate）
# my-local-lib = { path = "../my-local-lib" }

# Git 仓库依赖（通过分支、标签或 commit 锁定版本）
# regex = { git = "https://github.com/rust-lang/regex", branch = "master" }

# -----------------------------------------------------------------
#  [dev-dependencies]  开发依赖（仅在测试、示例、基准测试时编译）
# -----------------------------------------------------------------
[dev-dependencies]
tempfile = "3"                              # 创建临时文件/目录
criterion = { version = "0.5", features = ["html_reports"] }  # 基准测试框架

# -----------------------------------------------------------------
#  [build-dependencies]  构建依赖（仅在 build.rs 中使用）
# -----------------------------------------------------------------
[build-dependencies]
cc = "1.0"                                  # 编译 C/C++ 代码

# -----------------------------------------------------------------
#  平台特定依赖
# -----------------------------------------------------------------
# 仅在类 Unix 系统（Linux、macOS 等）编译
[target.'cfg(unix)'.dependencies]
libc = "0.2"

# 仅在 Windows 系统编译
[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3", features = ["winuser", "processthreadsapi"] }

# -----------------------------------------------------------------
#  [features]  可选特性标志
# -----------------------------------------------------------------
[features]
# 默认开启的特性（当用户不指定 --no-default-features 时生效）
default = ["full"]

# “完整”特性集合，会激活 serde 和 tokio 两个可选依赖
full = ["serde", "tokio"]

# 额外功能：基于 full 再加上 anyhow 的 backtrace 子特性
extra = ["full", "anyhow/backtrace"]

# 实验性特性，暂不关联任何依赖，仅作为标记使用
unstable = []

# -----------------------------------------------------------------
#  [profile.*]  编译配置
# -----------------------------------------------------------------
# 开发模式（cargo build / cargo run 默认使用）
[profile.dev]
opt-level = 0          # 不优化，追求编译速度
debug = true           # 生成完整的调试符号
overflow-checks = true # 开启整数溢出检查（帮助捕获 bug）
incremental = true     # 启用增量编译（默认已开启）

# 发布模式（cargo build --release）
[profile.release]
opt-level = 3          # 最高优化级别（可能增加编译时间）
debug = false          # 不生成调试信息
strip = true           # 剔除符号表，减小二进制体积
lto = true             # 启用链接时优化（进一步缩小体积、提升性能）
codegen-units = 1      # 单代码生成单元，利于优化（编译可能变慢）
panic = "abort"        # panic 时直接终止进程，避免 unwind 开销

# 基准测试模式（cargo bench）
[profile.bench]
opt-level = 3
debug = false
lto = true

# -----------------------------------------------------------------
#  [patch]  补丁：临时覆盖 crates.io 上的依赖
# -----------------------------------------------------------------
# 可把上游某个 crate 替换为自己的修复版本，适合本地调试或紧急修复
# [patch.crates-io]
# serde = { git = "https://github.com/serde-rs/serde", branch = "hotfix" }