build.rs 构建脚本 ​

核心概念 ​

build.rs 是 Cargo 的构建脚本(build script),在编译项目的 src/ 代码之前自动运行。它是一个独立的 Rust 程序,编译后由 Cargo 执行。构建脚本的典型用途包括:编译 C/C++ 源文件、生成 Rust 代码、查找系统库、设置编译时环境变量等。

构建脚本通过 println!("cargo::...") 向 Cargo 输出指令,这些指令控制编译行为、传递信息给项目代码、设置重新运行条件等。构建脚本使用 [build-dependencies] 中的依赖,这些依赖与项目的运行时依赖是完全独立的。

rust
// 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 指令 ​

rust
// 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输出警告

构建脚本可用的环境变量 ​

rust
// 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");
}

代码生成 ​

rust
// 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");
}
rust
// src/main.rs
// 引入构建脚本生成的代码
include!(concat!(env!("OUT_DIR"), "/generated.rs"));

fn main() {
    println!("构建时间: {}", BUILD_TIME);
    println!("目标平台: {}", BUILD_TARGET);
    println!("构建配置: {}", BUILD_PROFILE);
}

基本示例 ​

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

[build-dependencies]
cc = "1.0"
rust
// 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");
}
c
// src/native/math.c
int fast_add(int a, int b) {
    return a + b;
}

int fast_multiply(int a, int b) {
    return a * b;
}
rust
// 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 代码生成。