3. Kotlin/Native与C互操作基础

在 KMP 原生平台互操作工程中，Kotlin/Native 与 C 的互操作是最底层、也最关键的一环。无论是调用系统库（如 POSIX、libc）、第三方 C 库（如 SQLite、OpenSSL），还是复用已有的 C/C++ 遗留代码，最终都要经过 cinterop 这条工具链。理解 cinterop 的工作方式，本质上就是理解“C 头文件如何变成 Kotlin 可调用的绑定”这一过程。

cinterop 工具链的定位

cinterop 是 Kotlin/Native 编译器附带的一个工具，它读取 C 头文件，生成一个 .klib 绑定库。这个 klib 里包含 Kotlin 侧的声明（函数、结构体、常量、类型别名），Kotlin 代码通过 import 引用它，编译时再链接到真正的 C 库。整个链路可以概括为：C 头文件 + .def 描述文件 → cinterop → .klib 绑定 → Kotlin 编译器 → 可执行文件/动态库。

需要强调的是，cinterop 并不“翻译”C 的实现代码，它只解析头文件中的声明。真正的函数体仍然在 C 库中，运行时通过链接器绑定。因此头文件是否完整、宏是否展开、平台差异是否处理，直接决定绑定能否生成、能否正确调用。

.def 文件：告诉 cinterop 解析什么

.def 文件是 cinterop 的输入描述，它决定“解析哪些头文件、用什么编译参数、暴露哪些符号”。一个最小可用的 def 文件通常包含三部分：

headers = sqlite3.h
package = sqlite3
compilerOpts = -I/usr/include

headers 指定要解析的头文件，可以写多个，用空格或换行分隔；package 是生成 Kotlin 声明的包名，Kotlin 侧通过 import sqlite3.* 使用；compilerOpts 传给底层 C 编译器的参数，最常见的是 -I 指定头文件搜索路径。如果头文件依赖其他头文件，cinterop 会递归解析，但需要保证搜索路径完整。

对于宏，cinterop 默认只处理简单的常量宏（如 #define SQLITE_OK 0），函数式宏和条件编译宏通常不会生成绑定。如果某个宏必须暴露，可以在 def 中显式声明，或改用 #define 常量替代。这是初学者最容易踩的坑：头文件里明明有 SQLITE_OPEN_READWRITE，Kotlin 里却找不到，往往就是宏未被解析。

头文件解析与类型映射规则

cinterop 解析头文件后，会按固定规则把 C 类型映射为 Kotlin 类型。理解这些映射，才能正确书写调用代码，尤其是涉及指针和结构体时。

指针映射是最需要留意的部分。C 的 char* 在 Kotlin 侧是 CPointer<ByteVar>?，不能直接当字符串用，需要借助 toKString() 转换；反过来，Kotlin 字符串传给 C 需要 cstr 属性或 memScoped 分配内存。结构体如果按值传递，Kotlin 侧会生成对应的 CValue<T> 或直接结构体类型，访问字段用 ptr.pointed.field 或 value.field。

生成 Kotlin 绑定的实际过程

在 Gradle 项目中，cinterop 通常通过 cinterops 块配置。以 SQLite 为例，在 build.gradle.kts 中：

kotlin {
    linuxX64 {
        compilations.getByName("main") {
            cinterops {
                create("sqlite3") {
                    defFile(project.file("src/nativeInterop/cinterop/sqlite3.def"))
                    compilerOpts("-I/usr/include")
                }
            }
        }
    }
}

执行 ./gradlew build 时，Gradle 会先调用 cinterop 生成 sqlite3.klib，再编译 Kotlin 源码。生成产物位于 build/classes/kotlin/linuxX64/main/cinterop/ 下。如果头文件路径错误或宏解析失败，这一步会直接报错，错误信息通常会指出哪个头文件找不到、哪个符号无法解析。

绑定生成后，Kotlin 侧就可以像调用普通函数一样调用 C 函数。例如打开数据库：

import sqlite3.*
import kotlinx.cinterop.*

fun openDb(path: String): CPointer<sqlite3>? = memScoped {
    val ppDb = alloc<CPointerVar<sqlite3>>()
    val rc = sqlite3_open(path, ppDb.ptr)
    if (rc != SQLITE_OK) null else ppDb.value
}

这里 sqlite3_open 的第二个参数在 C 中是 sqlite3**，映射到 Kotlin 是 CPointer<CPointerVar<sqlite3>>，所以要用 alloc<CPointerVar<sqlite3>>() 分配一个指针变量，再取 .ptr 传入。SQLITE_OK 是常量宏，cinterop 已将其映射为 Kotlin 常量，可直接比较。这个例子集中体现了类型映射、内存分配和宏处理三个要点。

常见问题与判断依据

• 找不到符号：检查 def 的 headers 是否包含该符号所在头文件，以及 compilerOpts 的 -I 路径是否正确。
• 宏未生成：函数式宏或复杂条件宏不会被解析，需改用常量或手动封装。
• 指针类型不匹配：对照类型映射表，确认 C 声明中的指针层级，Kotlin 侧需要对应层级的 CPointer 或 CPointerVar。
• 运行时崩溃：多为空指针解引用或内存已释放，检查 memScoped 作用域和 free 调用时机。

掌握 cinterop 的关键，不在于记住所有映射细节，而在于建立“头文件声明 → def 描述 → klib 绑定 → Kotlin 调用”这条链路的清晰认知。遇到问题时，沿着链路逐段排查：头文件是否存在、def 是否覆盖、类型是否匹配、内存是否安全，绝大多数互操作问题都能定位到具体环节。