rust-bindgen：让 Rust 调用 C 库变成一行命令的事

rust-bindgen 在 GitHub 上收获了 5,199 个 Star。

Rust 官方维护这个项目。它的功能很明确：读入 C 或 C++ 的头文件，自动输出 Rust 的 FFI 绑定代码。

1、它解决什么问题

在 Rust 里调用 C 库，传统方式需要手写 extern "C" 声明和结构体定义。一个中等规模的 C 库可能有几百个函数和几十个结构体，手工翻译既耗时又容易出错。

bindgen 把这件事自动化了。给它一个头文件，它直接生成对应的 Rust 代码，包括结构体、枚举、函数签名和类型映射。

举个例子，假设有这段 C 头文件：

c 复制代码

typedef struct Doggo {
    int many;
    char wow;
} Doggo;

void eleven_out_of_ten_majestic_af(Doggo* pupper);

bindgen 会生成这样的 Rust 代码：

rust 复制代码

#[repr(C)]
pub struct Doggo {
    pub many: ::std::os::raw::c_int,
    pub wow: ::std::os::raw::c_char,
}

extern "C" {
    pub fn eleven_out_of_ten_majestic_af(pupper: *mut Doggo);
}

字段类型自动映射到 std::os::raw 下的对应类型，结构体加上 #[repr(C)] 保证内存布局一致，函数声明放入 extern "C" 块。这些都不用手写。

2、它怎么做到的

bindgen 底层依赖 libclang 解析 C/C++ 头文件。clang 完成词法分析、类型推导和宏展开后，bindgen 把得到的 AST 翻译成 Rust 语法树，最后输出为 Rust 源码。

这个设计让它能处理大多数 C 代码，以及一部分 C++ 特性（模板和重载函数除外）。

生成的代码兼容当前 Rust 版本，最低支持 Rust 1.70.0。

3、怎么用

命令行方式：

bash 复制代码

bindgen input.h -o output.rs

作为库集成到 build.rs：

rust 复制代码

use bindgen::Builder;

let bindings = Builder::default()
    .header("input.h")
    .generate()
    .expect("Unable to generate bindings");

bindings
    .write_to_file("src/bindings.rs")
    .expect("Couldn't write bindings!");

还可以通过环境变量控制行为，比如 BINDGEN_EXTRA_CLANG_ARGS 可以传入额外的 clang 参数，在交叉编译场景下指定 sysroot 或 include 路径。

4、适合谁用

写系统级 Rust 项目、需要对接现有 C 库的开发者。比如操作系统内核、嵌入式固件、数据库客户端、图形渲染层这些场景，C 生态积累深厚，直接复用比重新实现更实际。

做 FFI 封装库的维护者也会需要它。把一个 C 库包装成 *-sys crate 时，bindgen 是标准工具链的一部分。

5、局限

bindgen 能处理 C++，但能力有限。模板实例化、函数重载、异常处理这些特性它无法直接映射到 Rust。遇到复杂的 C++ API，通常需要写一层 C 包装器，再让 bindgen 处理包装后的头文件。

宏定义中的复杂逻辑也可能翻译得不完整，需要事后手动调整。

总之，bindgen 是 Rust FFI 开发的基础设施。它的价值不是提供了多炫目的功能，而是把一项机械、重复且容易出错的工作变成了自动化的流程。对于需要频繁对接 C 代码的 Rust 项目，这个工具能省下大量时间。