Rust 使用bindgen

bindgen 是一个用于从 C/C++ 头文件自动生成 Rust 绑定的工具。它允许开发者在 Rust 代码中无缝地使用现有的 C/C++ 库，从而充分利用这些库提供的功能。本章将详细介绍如何在 Rust 项目中集成和使用 bindgen。

安装 bindgen

首先，你需要安装 bindgen 工具。由于 bindgen 是一个命令行工具，你可以通过 cargo 直接安装它：

cargo install bindgen

如果你希望将 bindgen 集成到你的 Rust 项目中，可以通过 Cargo.toml 文件添加 bindgen 作为构建依赖项：

[build-dependencies]
bindgen = "0.59"

创建 Rust 项目

接下来，创建一个新的 Rust 项目。你可以使用 cargo new 命令来创建：

cargo new my_project --bin
cd my_project

创建 C/C++ 头文件

为了演示 bindgen 的使用，我们先创建一个简单的 C 头文件。假设我们有一个名为 example.h 的头文件，内容如下：

// www.javascriptcn.com code example
// example.h
#ifndef EXAMPLE_H
#define EXAMPLE_H

#ifdef __cplusplus
extern "C" {
#endif

void say_hello(const char* name);

#ifdef __cplusplus
}
#endif

#endif // EXAMPLE_H

这个头文件定义了一个简单的函数 say_hello，用于接收一个字符串参数并打印一条问候消息。

生成绑定代码

现在，我们需要使用 bindgen 生成 Rust 绑定代码。你可以通过以下命令生成绑定：

bindgen example.h -o src/bindings.rs

这会生成一个名为 bindings.rs 的文件，其中包含了从 example.h 自动生成的 Rust 绑定代码。

修改 Cargo.toml

为了让 Rust 项目能够找到生成的绑定代码，你需要修改 Cargo.toml 文件，添加对生成文件的引用：

[lib]
crate-type = ["cdylib"]

[dependencies]

这里我们设置 crate 类型为 cdylib，表示这是一个可以被外部语言调用的动态库。

编写 Rust 代码

接下来，我们需要编写一些 Rust 代码来使用生成的绑定。在 src/main.rs 文件中，我们可以这样写：

// www.javascriptcn.com code example
#[path = "src/bindings.rs"]
mod bindings;

use std::ffi::CString;
use std::os::raw::c_char;

fn main() {
    let hello = CString::new("world").unwrap();
    unsafe {
        bindings::say_hello(hello.as_ptr());
    }
}

这里我们使用了 unsafe 块来调用生成的绑定代码中的 say_hello 函数。

编译和运行项目

现在，你可以编译并运行你的项目了：

cargo build
cargo run

你应该会在控制台看到类似 Hello, world! 的输出。

高级用法

自定义绑定生成选项

bindgen 提供了许多选项来定制生成的绑定代码。例如，你可以通过命令行或 Cargo.toml 来指定哪些函数、结构体或枚举应该被包括或排除。例如：

bindgen example.h \
    --whitelist-function "^say_" \
    --whitelist-type "^ExampleType$" \
    --output src/bindings.rs

这将只生成以 say_ 开头的函数和名为 ExampleType 的类型相关的绑定代码。

使用 bindgen 作为构建脚本

你也可以将 bindgen 集成到项目的构建脚本中。在 build.rs 文件中，你可以这样写：

// www.javascriptcn.com code example
fn main() {
    bindgen::Builder::default()
        .header("example.h")
        .whitelist_function("^say_")
        .generate()
        .expect("Unable to generate bindings")
        .write_to_file("src/bindings.rs")
        .expect("Couldn't write bindings!");
}

然后，在 Cargo.toml 中添加：

[build-dependencies]
bindgen = "0.59"

这样，每次构建时，都会自动重新生成绑定代码。

通过以上步骤，你已经成功地将 C/C++ 库与 Rust 项目结合在一起，并利用 bindgen 自动生成了必要的绑定代码。希望这个教程对你有所帮助！