Cargo.toml 配置详解
Cargo.toml 是 Rust 项目的核心配置文件,使用 TOML(Tom's Obvious, Minimal Language)格式。它定义了项目的元数据、依赖关系、构建选项等关键信息。
一、基本结构
[package]
name = "my_project"
version = "0.1.0"
edition = "2021"[dependencies]
serde = "1.0.136"[dev-dependencies]
tempfile = "3.3.0"[build-dependencies]
cc = "1.0"[features]
default = ["feature1"]
feature1 = [][lib]
name = "my_lib"
crate-type = ["cdylib", "rlib"][[bin]]
name = "my_bin"
path = "src/main.rs"[profile.release]
opt-level = 3
二、核心配置部分
1. [package]
- 包元数据(必需)
[package]
name = "my_project" # 包名(必须符合crates.io命名规则)
version = "0.1.0" # 语义化版本(major.minor.patch)
edition = "2021" # Rust版本(2015/2018/2021)# 可选元数据
authors = ["Alice <alice@example.com>", "Bob <bob@example.com>"]
description = "A fantastic Rust project"
license = "MIT OR Apache-2.0" # SPDX许可证标识符
repository = "https://github.com/user/repo"
documentation = "https://docs.rs/crate"
homepage = "https://my-project.org"
keywords = ["cli", "tool", "utility"]
categories = ["command-line-utilities"]
readme = "README.md" # 指定README文件
default-run = "main" # 默认运行的二进制目标
rust-version = "1.56.0" # 最低支持的Rust版本
2. 依赖管理
常规依赖 ([dependencies]
)
[dependencies]
# 标准版本指定
serde = "1.0.136" # 兼容1.0.136的最新版本(^1.0.136)
rand = "0.8.5" # 精确版本
chrono = "=0.4.19" # 严格等于指定版本# 版本范围
reqwest = ">=0.11, <0.12" # 0.11.x系列的最新版本# Git依赖
tokio = { git = "https://github.com/tokio-rs/tokio", branch = "master" }# 路径依赖
my_utils = { path = "../my_utils" }# 启用特性
serde_json = { version = "1.0", features = ["preserve_order"] }# 重命名包
rjson = { package = "serde_json", version = "1.0" }
开发依赖 ([dev-dependencies]
)
用于测试、示例和基准测试(不包含在正式发布中)
[dev-dependencies]
tempfile = "3.3.0"
构建依赖 ([build-dependencies]
)
用于构建脚本(build.rs
)
[build-dependencies]
cc = "1.0"
3. 特性标志 ([features]
)
[features]
# 默认启用的特性
default = ["feature1", "feature2"]# 简单特性
feature1 = []
feature2 = []# 依赖其他特性的特性
extended = ["feature1", "dep:serde", "rand?/special"]# 可选依赖特性
database = ["sqlx"]
在代码中使用:
#[cfg(feature = "database")]
mod db_support;
4. 目标配置
库配置 ([lib]
)
[lib]
name = "my_lib" # 库名(默认与包名相同)
path = "src/lib.rs" # 源文件路径(默认)
crate-type = ["cdylib"] # 输出类型:rlib, dylib, cdylib, staticlib
test = true # 是否包含测试(默认true)
bench = true # 是否包含基准测试
二进制目标 ([[bin]]
)
可定义多个二进制目标:
[[bin]]
name = "main" # 可执行文件名
path = "src/main.rs" # 源文件路径
test = true # 是否参与测试
bench = true # 是否参与基准测试
doc = false # 是否生成文档[[bin]]
name = "helper"
path = "src/bin/helper.rs"
其他目标类型
# 测试目标
[[test]]
name = "integration_test"
path = "tests/integration.rs"# 示例目标
[[example]]
name = "demo"
path = "examples/demo.rs"# 基准测试目标
[[bench]]
name = "my_bench"
path = "benches/benchmark.rs"
5. 构建配置 ([build]
)
[build]
build = "build.rs" # 构建脚本路径(默认)
target-dir = "target" # 构建输出目录
rustc = "rustc" # 自定义rustc路径
rustdoc = "rustdoc" # 自定义rustdoc路径
6. 优化配置 ([profile]
)
# 开发配置
[profile.dev]
opt-level = 0 # 优化级别(0-3)
debug = true # 包含调试信息
split-debuginfo = "unpacked" # 调试信息处理方式# 发布配置
[profile.release]
opt-level = 3
lto = true # 链接时优化
codegen-units = 1 # 减少并行编译单元以优化性能
panic = "abort" # 发生panic时直接终止程序
incremental = false # 禁用增量编译
7. 工作区配置 ([workspace]
)
用于管理多个相关包:
[workspace]
members = ["crates/*","tools/helper"
]
exclude = ["old_project"]
resolver = "2" # 依赖解析器版本
default-members = ["crates/core"][workspace.dependencies]
common-dep = "0.5.3" # 工作区共享依赖
三、高级功能
补丁依赖 ([patch]
)
覆盖依赖图的特定版本:
[patch.crates-io]
serde = { git = "https://github.com/serde-rs/serde", branch = "fix-bug" }
替换依赖 ([replace]
) - 已废弃
# 已废弃 - 改用[patch]
[replace]
"serde:1.0.136" = { git = "https://github.com/serde-rs/serde" }
自定义命令别名
[alias]
b = "build"
rr = "run --release"
t = "test -- --nocapture"
四、环境变量使用
在 Cargo.toml 中使用环境变量:
[package]
description = "Project ${PROJECT_NAME} v${CARGO_PKG_VERSION}"
五、最佳实践
版本管理:
使用语义化版本控制
精确版本用于库 (
=x.y.z
)兼容版本用于应用 (
"x.y.z"
)
依赖优化:
# 避免不必要的依赖特性 tokio = { version = "1.0", default-features = false, features = ["rt"] }
3.工作区组织:
[workspace]
members = ["crates/*"]
resolver = "2"
4. 构建优化:
[profile.release]
lto = "thin"
codegen-units = 16 # 开发时加速编译
5. 条件编译:
[target.'cfg(unix)'.dependencies]
nix = "0.24"