[build-dependencies] ​

核心概念 ​

[build-dependencies] 段声明构建脚本(build.rs)中使用的依赖。构建脚本在编译项目代码之前运行,通常用于编译 C/C++ 代码、生成绑定、设置环境变量等。构建脚本需要的 crate 放在 [build-dependencies] 中,它们不会被链接到最终产物,也不会在项目的 src/ 代码中可用。

toml
[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 配合使用 ​

toml
# Cargo.toml
[package]
name = "my-project"
version = "0.1.0"
edition = "2024"
build = "build.rs"     # 指定构建脚本

[build-dependencies]
cc = "1.0"             # 用于编译 C 代码
rust
// 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()
}
rust
// src/main.rs — 使用构建脚本设置的值
fn main() {
    // 通过 env! 读取 build.rs 设置的环境变量
    let build_time = env!("BUILD_TIME");
    println!("构建时间: {}", build_time);
}

常见的构建依赖 ​

toml
[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 代码生成

基本示例 ​

toml
[package]
name = "build-demo"
version = "0.1.0"
edition = "2024"
build = "build.rs"

[build-dependencies]
built = "0.7"
rust
// 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");
}
rust
// 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 和项目代码通信。