Rust FFI 编程-cbindgen 使用示例

在上一篇中，我们整体介绍了 cbindgen 工具。本文将会示例如何使用 cbindgen 为我们之前写的 Rust 示例库 生成头文件。主要内容包括：

生成的头文件和之前的对比

为 C API 增加枚举类型，并生成头文件

使用 cbindgen.toml

我们知道可以通过 cbindgen.toml 这个配置文件，给 cbindgen 工具配置各种行为参数来生成头文件。示例库提供了 C API，那我们首先在示例库的根目录下创建一个 cbindgen.toml ，并且试试只配置以下一行内容：

language="C"

然后执行以下命令：

cbindgen--configcbindgen.toml--crateexample_03--outputexample_03_header.h

我们可以看到，在根目录下生成了一个 example_03_header.h 的头文件。跟我们之前手动编写的头文件进行对比：

#include

#include

#include

#include

多了以上这几行  文件，这是 cbindgen 工具的默认行为，它会默认导入这些 C/C++ 标准库。我们如果不需要导入这些库时，可以通过增加以下配置内容：

no_includes=true

再执行生成命令后，这时我们可以看到这个头文件和我们之前手动编写的基本一样。

这时，如果我们想要在导出的头文件中类型统一加个前缀，比如：，可以在 cbindgen.toml 增加以下配置：

[export]

prefix="capi_"

增加枚举类型

为了演示 cbindgen 工具对 enum 枚举类型的支持，我们为示例增加个枚举类型，代码如下：

#[repr(C)]

#[derive(Debug)]

pubenumgender{

BOY,

GIRL,

}

同时，相应地修改函数中的一些代码：

#[no_mangle]

pubextern"C"fnstudent_alice() -> *mutstudent {

letmutinit_char_array: [c_char;20] = [;20];

for(dest, src)ininit_char_array.iter_mut().zip(b"Alice\0".iter()) {

*dest = *srcas_;

}

letscores = [92.5,87.5,90.0];

letalice = student {

num:1asc_int,

total:280,

name: init_char_array,

scores,

gender: gender::GIRL,

};

Box::into_raw(Box::new(alice))

}

这时，通过 cbindgen 工具生成头文件，我们可以看出新的头文件能正确地包含我们新增的枚举类型：

typedefenum{

BOY,

GIRL,

} capi_gender;

对于枚举类型中的变体，如果我们希望更符合 C 的风格，可以在 cbindgen.toml 中配置以下内容：

[enum]

rename_variants="SnakeCase"

这个规则是针对枚举类型的变体进行重命名，主要的值包括（引用自 cbindgen 的文档）：

#possible values (that actuallydosomething):

#*"CamelCase": MyVariant => myVariant

#*"SnakeCase": MyVariant => my_variant

#*"ScreamingSnakeCase": MyVariant => MY_VARIANT

#*"QualifiedScreamingSnakeCase": MyVariant => ENUM_NAME_MY_VARIANT

#*"LowerCase": MyVariant => myvariant

#*"UpperCase": MyVariant => MYVARIANT

#*"None": apply no renaming

执行 cbindgen 后，可以看到头文件枚举部分的定义变为：

typedefenum{

boy,

girl,

} capi_gender;

小结

综上所述，我们演示了对于之前的 Rust 示例库，如何通过配置 cbindgen.toml 使用 cbindgen 生成头文件。

完整示例代码在 Github：https://github.com/lesterli/rust-practice/tree/master/ffi/example_03

hyper 的C API 也是通过 cbinggen 来生成头文件的，有兴趣的可以通过此链接围观。

https://github.com/hyperium/hyper/commit/b1cec5c2104e3b2ceb2148c8dcbfecbfcdc91517#diff-06402fdf0de1ac57a0fc84d328a68836f41eedf61764d4d35f11889db149ac42