build.rs 构建脚本
核心概念
build.rs 是 Cargo 的构建脚本(build script),在编译项目的 src/ 代码之前自动运行。它是一个独立的 Rust 程序,编译后由 Cargo 执行。构建脚本的典型用途包括:编译 C/C++ 源文件、生成 Rust 代码、查找系统库、设置编译时环境变量等。
构建脚本通过 println!("cargo::...") 向 Cargo 输出指令,这些指令控制编译行为、传递信息给项目代码、设置重新运行条件等。构建脚本使用 [build-dependencies] 中的依赖,这些依赖与项目的运行时依赖是完全独立的。
// build.rs — 一个基本的构建脚本
fn main() {
// 告诉 Cargo 当 build.rs 本身改变时重新运行
println!("cargo::rerun-if-changed=build.rs");
// 设置环境变量,src/ 代码可以通过 env!() 读取
println!("cargo::rustc-env=APP_VERSION=0.1.0");
// 设置条件编译标志
println!("cargo::rustc-cfg=has_feature_x");
// 添加链接搜索路径
// println!("cargo::rustc-link-search=native=/usr/local/lib");
// 链接本地库
// println!("cargo::rustc-link-lib=static=mylib");
}Cargo 指令
// build.rs 通过 println! 向 Cargo 发送指令
// Rust 1.77+ 使用 cargo:: 前缀(替代旧的 cargo: 前缀)
fn main() {
// === 重新运行条件 ===
// 当指定文件变化时重新运行 build.rs
println!("cargo::rerun-if-changed=build.rs");
println!("cargo::rerun-if-changed=src/native/");
println!("cargo::rerun-if-changed=wrapper.h");
// 当环境变量变化时重新运行
println!("cargo::rerun-if-env-changed=MY_CONFIG");
// === 设置环境变量 ===
// src/ 代码中通过 env!("KEY") 或 option_env!("KEY") 读取
println!("cargo::rustc-env=BUILD_PROFILE={}", std::env::var("PROFILE").unwrap());
println!("cargo::rustc-env=TARGET={}", std::env::var("TARGET").unwrap());
// === 条件编译标志 ===
println!("cargo::rustc-cfg=custom_flag");
println!("cargo::rustc-cfg=platform=\"desktop\"");
// 代码中用 #[cfg(custom_flag)] 或 #[cfg(platform = "desktop")]
// === 链接库 ===
// println!("cargo::rustc-link-lib=static=foo"); // 静态链接 libfoo.a
// println!("cargo::rustc-link-lib=dylib=bar"); // 动态链接 libbar.so
// println!("cargo::rustc-link-lib=framework=CoreFoundation"); // macOS 框架
// === 链接搜索路径 ===
// println!("cargo::rustc-link-search=native=/usr/local/lib");
// println!("cargo::rustc-link-search=dependency=/path/to/deps");
// === 传递给依赖的元数据 ===
// println!("cargo::metadata=key=value");
// === 编译器参数 ===
// println!("cargo::rustc-flags=-l static=foo");
// === 输出警告 ===
println!("cargo::warning=这是构建时的警告信息");
}| 指令 | 说明 |
|---|---|
rerun-if-changed=PATH | 文件变化时重新运行 |
rerun-if-env-changed=VAR | 环境变量变化时重新运行 |
rustc-env=KEY=VALUE | 设置编译时环境变量 |
rustc-cfg=FLAG | 设置条件编译标志 |
rustc-link-lib=LIB | 链接库 |
rustc-link-search=PATH | 添加搜索路径 |
warning=MSG | 输出警告 |
构建脚本可用的环境变量
// Cargo 在运行 build.rs 时会设置一系列环境变量
fn main() {
// CARGO_MANIFEST_DIR:Cargo.toml 所在目录
let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
// OUT_DIR:构建脚本的输出目录(用于生成文件)
let out_dir = std::env::var("OUT_DIR").unwrap();
// TARGET:编译目标三元组
let target = std::env::var("TARGET").unwrap();
// HOST:主机三元组
let host = std::env::var("HOST").unwrap();
// PROFILE:构建配置(debug 或 release)
let profile = std::env::var("PROFILE").unwrap();
// CARGO_PKG_VERSION:当前包版本
let version = std::env::var("CARGO_PKG_VERSION").unwrap();
// CARGO_PKG_NAME:当前包名
let name = std::env::var("CARGO_PKG_NAME").unwrap();
// NUM_JOBS:并行任务数
let jobs = std::env::var("NUM_JOBS").unwrap_or_else(|_| "1".to_string());
println!("cargo::warning=构建 {} v{} for {} ({})",
name, version, target, profile);
println!("cargo::warning=输出目录: {}", out_dir);
println!("cargo::rerun-if-changed=build.rs");
}代码生成
// build.rs 可以在 OUT_DIR 中生成代码文件
// src/ 代码用 include! 引入
use std::env;
use std::fs;
use std::path::Path;
fn main() {
let out_dir = env::var("OUT_DIR").unwrap();
let dest_path = Path::new(&out_dir).join("generated.rs");
// 生成一些常量
let code = format!(
r#"
pub const BUILD_TIME: &str = "{}";
pub const BUILD_TARGET: &str = "{}";
pub const BUILD_PROFILE: &str = "{}";
"#,
"2026-03-26",
env::var("TARGET").unwrap(),
env::var("PROFILE").unwrap(),
);
fs::write(&dest_path, code).unwrap();
println!("cargo::rerun-if-changed=build.rs");
}// src/main.rs
// 引入构建脚本生成的代码
include!(concat!(env!("OUT_DIR"), "/generated.rs"));
fn main() {
println!("构建时间: {}", BUILD_TIME);
println!("目标平台: {}", BUILD_TARGET);
println!("构建配置: {}", BUILD_PROFILE);
}基本示例
# Cargo.toml
[package]
name = "build-demo"
version = "0.1.0"
edition = "2024"
build = "build.rs"
[build-dependencies]
cc = "1.0"// build.rs — 编译 C 代码
fn main() {
// 使用 cc crate 编译 C 文件
cc::Build::new()
.file("src/native/math.c") // C 源文件
.opt_level(2) // 优化级别
.compile("native_math"); // 输出库名
// 告诉 Cargo 当 C 文件变化时重新编译
println!("cargo::rerun-if-changed=src/native/math.c");
println!("cargo::rerun-if-changed=build.rs");
}// src/native/math.c
int fast_add(int a, int b) {
return a + b;
}
int fast_multiply(int a, int b) {
return a * b;
}// src/main.rs
// 声明 C 函数
extern "C" {
fn fast_add(a: i32, b: i32) -> i32;
fn fast_multiply(a: i32, b: i32) -> i32;
}
fn main() {
unsafe {
println!("3 + 4 = {}", fast_add(3, 4));
println!("3 * 4 = {}", fast_multiply(3, 4));
}
}常见问题
问题一:build.rs 的输出文件放在哪里?
OUT_DIR 环境变量指向构建脚本的输出目录,通常在 target/ 下的某个路径。不要在 src/ 中生成文件,应该始终使用 OUT_DIR。
问题二:build.rs 什么时候会重新运行?
默认每次编译都运行。用 rerun-if-changed 指令可以控制只在特定文件变化时重新运行。如果任何一条 rerun-if-changed 指向的文件变化了,build.rs 就会重新运行。
问题三:build.rs 可以读取 Cargo.toml 的内容吗?
不能直接解析 Cargo.toml,但 Cargo 会把 [package] 中的关键信息通过环境变量传递给 build.rs,如 CARGO_PKG_NAME、CARGO_PKG_VERSION 等。
问题四:build.rs 失败了怎么办?
如果 build.rs 的 main 函数返回非零退出码(通过 process::exit 或 panic),Cargo 会停止编译并显示错误信息。cargo::warning 指令只输出警告,不会中断编译。
适用场景
- 编译本地代码:C/C++/汇编文件编译(cc crate)
- 代码生成:在 OUT_DIR 中生成 Rust 源文件
- FFI 绑定:通过 bindgen 生成 C 库绑定
- 构建信息嵌入:Git hash、编译时间等
- 系统库检测:通过 pkg-config 查找系统库
- Protobuf/gRPC:生成 .proto 文件的 Rust 代码
注意事项
- build.rs 在
src/代码之前编译和运行 - 使用
[build-dependencies]声明构建脚本的依赖 - 生成文件应放在
OUT_DIR中,不要放在src/ rerun-if-changed控制重新运行的条件- 新语法用
cargo::前缀(1.77+),旧语法用cargo: - build.rs 是独立编译的,不能使用
[dependencies]中的 crate
总结
build.rs 是 Cargo 的构建脚本,在编译项目代码之前运行。它通过 println!("cargo::...") 向 Cargo 发送指令:rerun-if-changed 控制重新运行条件,rustc-env 设置环境变量,rustc-cfg 设置条件编译标志,rustc-link-lib 链接库。构建脚本使用 [build-dependencies] 中的依赖,生成的文件放在 OUT_DIR 中,项目代码用 include! 引入。常见用途包括编译 C 代码(cc)、生成 FFI 绑定(bindgen)、嵌入构建信息和 Protobuf 代码生成。