[build-dependencies]
核心概念
[build-dependencies] 段声明构建脚本(build.rs)中使用的依赖。构建脚本在编译项目代码之前运行,通常用于编译 C/C++ 代码、生成绑定、设置环境变量等。构建脚本需要的 crate 放在 [build-dependencies] 中,它们不会被链接到最终产物,也不会在项目的 src/ 代码中可用。
[build-dependencies]
cc = "1.0" # 编译 C/C++ 源文件
bindgen = "0.69" # 自动生成 C 库的 Rust 绑定
built = "0.7" # 收集构建时信息
pkg-config = "0.3" # 查找系统库三种依赖段对比
| 依赖段 | 可用范围 | 编译进产物 | 传递给下游 |
|---|---|---|---|
[dependencies] | src/、测试、示例 | 是 | 是 |
[dev-dependencies] | 测试、示例、基准 | 否 | 否 |
[build-dependencies] | build.rs | 否 | 否 |
与 build.rs 配合使用
# Cargo.toml
[package]
name = "my-project"
version = "0.1.0"
edition = "2024"
build = "build.rs" # 指定构建脚本
[build-dependencies]
cc = "1.0" # 用于编译 C 代码// build.rs — 构建脚本
// 这个文件在编译 src/ 代码之前运行
fn main() {
// 使用 cc crate 编译 C 源文件
// cc::Build::new()
// .file("src/native/helper.c")
// .compile("helper");
// 告诉 Cargo 当 build.rs 变化时重新运行
println!("cargo::rerun-if-changed=build.rs");
println!("cargo::rerun-if-changed=src/native/");
// 设置环境变量供 src/ 代码使用
println!("cargo::rustc-env=BUILD_TIME={}", chrono_like_now());
}
fn chrono_like_now() -> String {
"2026-03-26".to_string()
}// src/main.rs — 使用构建脚本设置的值
fn main() {
// 通过 env! 读取 build.rs 设置的环境变量
let build_time = env!("BUILD_TIME");
println!("构建时间: {}", build_time);
}常见的构建依赖
[build-dependencies]
# C/C++ 编译
cc = "1.0" # 编译 C/C++ 文件
cmake = "0.1" # CMake 集成
# FFI 绑定生成
bindgen = "0.69" # C 头文件 → Rust 绑定
# 系统库查找
pkg-config = "0.3" # pkg-config 查询
vcpkg = "0.2" # Windows vcpkg 集成
# 构建信息
built = "0.7" # 收集 git hash、编译器版本等
vergen = "8" # 生成版本信息
# 代码生成
prost-build = "0.12" # Protobuf 代码生成
tonic-build = "0.11" # gRPC 代码生成基本示例
[package]
name = "build-demo"
version = "0.1.0"
edition = "2024"
build = "build.rs"
[build-dependencies]
built = "0.7"// build.rs
fn main() {
// 简单的构建脚本示例
// 生成构建信息到 OUT_DIR
// built::write_built_file().expect("构建信息生成失败");
// 设置链接搜索路径
// println!("cargo::rustc-link-search=native=/usr/local/lib");
// println!("cargo::rustc-link-lib=static=mylib");
// 条件编译标志
if cfg!(target_os = "windows") {
println!("cargo::rustc-cfg=windows_build");
}
println!("cargo::rerun-if-changed=build.rs");
}// src/main.rs
fn main() {
#[cfg(windows_build)]
println!("这是 Windows 构建");
#[cfg(not(windows_build))]
println!("这不是 Windows 构建");
}常见问题
问题一:build-dependencies 中的 crate 能在 src/ 中用吗?
不能。[build-dependencies] 的 crate 只在 build.rs 中可用。build.rs 是一个独立的编译单元,与项目代码分开编译。
问题二:没有 build.rs 还需要 build-dependencies 吗?
不需要。[build-dependencies] 只对 build.rs 有意义。如果项目没有构建脚本,这个段会被忽略。
问题三:build-dependencies 和 dependencies 可以有同一个 crate 吗?
可以。它们是完全独立的依赖树,互不影响。同一个 crate 可以同时出现在两个段中,甚至版本不同也可以。
问题四:build.rs 怎么与 src/ 代码通信?
通过 println!("cargo::rustc-env=KEY=VALUE") 设置环境变量,src/ 代码用 env!("KEY") 读取。也可以生成文件到 OUT_DIR,src/ 代码用 include! 或 include_str! 引入。
适用场景
- 编译本地 C/C++ 代码:cc、cmake
- 生成 FFI 绑定:bindgen
- Protobuf/gRPC 代码生成:prost-build、tonic-build
- 嵌入构建信息:git hash、编译时间
- 查找系统库:pkg-config
注意事项
- 只在 build.rs 中可用,不能在 src/ 代码中使用
- 不会编译进最终产物
- 不会传递给下游依赖者
- build.rs 需要在
[package]中用build = "build.rs"声明 - 通过
cargo::rerun-if-changed控制重新运行条件
总结
[build-dependencies] 声明构建脚本 build.rs 中使用的依赖。这些依赖只在构建脚本运行时可用,不会编译进最终产物,也不能在项目的 src/ 代码中使用。常见用途包括编译 C/C++ 代码(cc)、生成 FFI 绑定(bindgen)、Protobuf 代码生成(prost-build)和收集构建信息(built)。构建脚本通过 println!("cargo::...") 指令与 Cargo 和项目代码通信。