定义文件

导入头文件

如果一个 C 库 没有 Clang 模块, 而是由一组头文件组成, 请使用 headers 属性来指定需要导入的头文件:

导入模块

如果一个 Objective-C 库有 Clang 模块, 请使用 modules 属性指定需要导入的模块:

传递编译器和链接器选项

请使用 compilerOpts 属性向 C 编译器传递选项, 底层会使用 C 编译器分析头文件. 要向链接器传递选项, 请使用 linkerOpts, 链接器用来链接最终的可执行代码. 例如:

你也可以指定某个目标平台独有的参数, 这些参数只会被用于指定的目标平台:

通过这样的配置, 头文件在 Linux 上的会使用 -DBAR=bar -DFOO=foo1 参数进行分析, 在 macOS 上则会使用 -DBAR=bar -DFOO=foo2 参数进行分析. 注意, 定义文件的任何参数, 都可以包含共通的, 以及平台独有的两部分.

忽略指定的函数

使用 excludedFunctions 属性来指定需要忽略的函数名称列表. 如果头文件声明中的一个函数, 并不保证一定可以调用, 而且常常很难, 甚至不可能自动判断, 那么这个功能会非常有用. 你也可以使用这个属性 来绕过 interop 工具本身的 bug.

包含一个静态库

有些时候, 发布你的程序时附带上所需要的静态库, 而不是假定它在用户的环境中已经存在了, 这样会更便利一些. 如果需要在 .klib 中包含静态库, 请使用 staticLibrary 和 libraryPaths 属性:

如果指定了以上设置, cinterop 工具会在 /opt/local/lib 和 /usr/local/opt/curl/lib 目录中搜索 libfoo.a 文件, 如果找到, 就会把这个库的二进制文件包含到 klib 内.

在你的程序中使用这样的 klib, 库会被自动链接到你的程序内.

配置枚举的生成方式

使用 strictEnums 属性, 将枚举生成为 Kotlin 的枚举类型, 或使用 nonStrictEnums 属性, 生成为整数值. 如果一个枚举型在这两个属性列表中都没有包括, 那么就根据启发式方法(heuristic)来生成.

设置字符串的转换

使用 noStringConversion 属性来禁用 const char* 函数参数到 Kotlin String 的自动转换.

允许调用非指定的初始化器(non-designated initializer)

默认情况下, Kotlin/Native 编译器不允许将非指定的 Objective-C 初始化器作为 super() 构造器调用. 如果非指定的 Objective-C 初始化器在库中没有正确的标记, 那么这个行为可能会不太方便. 要禁止这个编译器检查, 请使用 disableDesignatedInitializerChecks 属性.

处理 Objective-C 的异常

默认情况下, 如果 Objective-C 的异常到达了 Objective-C 到 Kotlin 的互操作边界, 并进入到 Kotlin 代码中, 那么程序会崩溃.

要让 Objective-C 异常传播到 Kotlin 中, 请使用 foreignExceptionMode = objc-wrap 属性, 允许异常的封装. 这种情况下, Objective-C 异常会被翻译为 Kotlin 异常, 类型为 ForeignException.

帮助解决链接器错误

当一个 Kotlin 库依赖于一个 C 或 Objective-C 库时, 可能会发生链接器错误, 例如, 使用 CocoaPods 集成 的情况. 如果依赖的库在当前机器上没有安装, 在项目的构建脚本中也没有明确的配置, 就会发生 "Framework not found" 错误.

如果你是库的作者, 你可以通过自定义消息来帮助你的使用者解决链接器错误. 方法是, 在你的 .def 文件中添加 userSetupHint=message 属性, 或者向 cinterop 传递 -Xuser-setup-hint 编译器选项.

添加自定义声明

在生成绑定之前, 有时会需要向库添加自定义的 C 声明(比如, 对 宏). 你不需要为这些声明创建一个额外的头文件, 可以将它们直接包含在 .def 文件尾部, 放在一个分隔行 --- 之后:

注意, .def 文件的这部分内容会被当做头文件的一部分, 因此, 带函数体的函数应该声明为 static 函数. 这些声明的内容, 会在 headers 列表中的文件被引入之后, 再被解析.