如何使用 cbindgen

1. 以命令行工具的方式使用；
2. 以库的方式在 build.rs 中使用；

命令行工具方式

cargo install --force cbindgen

cbindgen --config cbindgen.toml --crate my_rust_library --output my_header.h

1. 不是任意 Rust crate 都可以，而是已经做了暴露 C API 开发的库才行。因为 cbindgen 会去扫描整个源代码，把对接的接口抽出来；
2. 可以通过 cbindgen.toml 这个配置文件，给 cbindgen 配置行为参数，参数很多，后面有参考链接。

build.rs 方式

extern crate cbindgen;

use std::env;

fn main() {
let crate_dir = env::var("CARGO_MANIFEST_DIR").unwrap();

    cbindgen::Builder::new()
      .with_crate(crate_dir)
      .generate()
      .expect("Unable to generate bindings")
      .write_to_file("bindings.h");
}

生成的结果看起来是什么样子？

// trebuchet.rs

#[repr(u8)]
enum Ammo {
    Rock,
    WaterBalloon,
    Cow,
}

#[repr(C)]
struct Target {
    latitude: f64,
    longitude: f64,
}

// notice: #[repr(rust)]
struct Trebuchet { ... }

#[no_mangle]
unsafe extern "C" fn trebuchet_new() -> *mut Trebuchet { ... }

#[no_mangle]
unsafe extern "C" fn trebuchet_delete(treb: *mut Trebuchet) { ... }

#[no_mangle]
unsafe extern "C" fn trebuchet_fire(treb: *mut Trebuchet,
                                    ammo: Ammo,
                                    target: Target) { ... }

// trebuchet.h

#include <cstdint>
#include <cstdlib>

extern "C" {

enum class Ammo : uint8_t {
    Rock = 0,
    WaterBalloon = 1,
    Cow = 2,
};

struct Trebuchet;

struct Target {
double latitude;
double longitude;
};

void trebuchet_delete(Trebuchet *treb);

void trebuchet_fire(Trebuchet *treb, Ammo ammo, Target target);

Trebuchet* trebuchet_new();

} // extern "C"

1. Ammo 有正确的大小和值；
2. Target 包含所有字段和正确的布局（字段顺序）；
3. Trebuchet 被声明为一个 opaque 结构体；
4. 所有的函数有了对应的声明。

补充

1. cbindgen 不但可以生成 C 头文件，还可以生成 C++ 的，甚至还可以生成 swift 可以用的头文件；
2. cbindgen 不是一包到底的，对 C 的支持相对成熟，对 C++ 的差一些。适当的时候，还是需要手动做很多事情的；
3. cbindgen 对 Rust 的泛型，有一定的支持；

参考链接

• 说明文档
• cbindgen.toml
• announcing-cbindgen