用途
该技能面向一种特定场景:为 Kotlin Multiplatform 库编写全新的、第一方的 C/C++ 原生核心,例如自研渲染器(Vulkan、Metal)、编解码器或计算引擎,且这些原生代码此前并不存在。它帮助在编写任何 Kotlin 绑定之前,先确定原生核心的目录布局、构建系统和公共头文件形态。
它明确不适用于以下情况:已有第三方 C/C++ 库需要 Kotlin 桥接(属于 kotlin-multiplatform-jni-pro 的库优先发现阶段);为已构建好的原生代码编写 JNI/cinterop 胶水;或原生需求非常简单,用普通的 expect/actual Kotlin/Native 实现即可覆盖。
主要能力
- 推荐单一 native/ 目录、单一 CMakeLists.txt,Android NDK、iOS/Kotlin-Native cinterop、JVM/Desktop JNI 全部复用同一 CMake 工程,避免各平台构建逻辑重复与漂移。
- 在任何 Kotlin 代码出现之前先定义稳定的公共 C-ABI 头文件:native/include/ 作为契约,native/src/ 内部可自由变动。该头文件正是后续 kotlin-multiplatform-jni-pro 阶段读取的输入。
- 在真实边界上使用纯 C 类型(结构体、基本类型、不透明句柄),即使内部是 C++;STL 容器、异常和模板不跨越 JNI/cinterop 边界。
- 原生测试通过 ctest 在独立 CI 任务中运行,不并入 Kotlin 的 jvmTest。
使用方式
技能按以下步骤组织输出:推荐方案;针对具体原生核心的目录布局;公共头文件(不透明句柄、extern "C"、成对的 create/destroy);带各平台链接要求的 CMakeLists.txt;以及到 kotlin-multiplatform-jni-pro 的明确交接点。
目录布局示例:native/ 下含 CMakeLists.txt、include/<library>/<library>.h(公共 C-ABI 表面)、src/(C-ABI 入口,薄层委托给 internal/ 中的真实 C++ 实现,此处可用 STL/异常/模板)、tests/(gtest/Catch2,仅原生,不涉及 JVM/Kotlin)。
公共头文件要点:使用 extern "C" 块即使实现是 C++,使符号可被 JNI 动态加载和 Kotlin/Native cinterop 的 .def 解析调用;使用不透明指针句柄而非按值传递含 C++ 成员的结构体;每个 _create 配对 _destroy;头文件中使用 C 的 uint8_t 等无符号类型在部分场景(像素格式、位标志、校验和)是合适的,但 Kotlin/Native cinterop 会直接映射为 UByte/UShort/UInt/ULong,而 JNI 没有无符号基本类型,需按 jni-pro 的类型映射参考转换;尺寸、索引、数组长度建议保持有符号,符合 Kotlin 官方指导。
CMake 要点:一个 project、C++20、add_library SHARED、target_include_directories 暴露 include;Android 分支链接 NDK 的 vulkan、android、log,其他平台通过 find_package(Vulkan) 链接 Vulkan::Vulkan;enable_testing() 并 add_subdirectory(tests)。
各平台接入:Android 在库模块 build.gradle.kts 中配置 externalNativeBuild 指向该 CMakeLists;iOS/Kotlin-Native 构建静态库并用 .def 文件指向 include/;Desktop/JVM 构建共享库并通过 System.loadLibrary 加载。
交接:当公共头文件编译通过且函数稳定后,将其作为 kotlin-multiplatform-jni-pro 阶段 0 的输入,此后从 Kotlin 侧将其视为只读第三方库。头文件稳定前不要开始写 external fun 声明。
适用场景
需要为 KMP 库新建自研原生渲染器、编解码器或计算引擎;需要在写 Kotlin 绑定前先确定原生目录、构建与头文件形态;需要为原生核心建立独立于 Kotlin 测试套件的测试。
限制与注意事项
技能提示需检查当前项目固定的 NDK 版本与 Kotlin/Native cinterop 文档,不要沿用旧版 CMake 最低版本或 .def 文件形态。常见反模式包括:头文件未稳定就写 JNI/cinterop 胶水;在 extern "C" 边界暴露 STL 类型或异常;按值传递含 C++ 成员函数或虚函数的结构体;按平台复制 CMake 逻辑;缺少原生侧测试覆盖;以及把头文件产出当作完成而跳过 kotlin-multiplatform-jni-pro。
相关技能:kotlin-multiplatform-jni-pro(下一步,负责桥接与内存安全、类型映射);kotlin-multiplatform-expect-actual(原生需求简单时替代);kotlin-multiplatform-library-publishing(含原生核心的库仍走常规发布流程);kotlin-multiplatform-api-mimicry(原生核心之上需要模仿的高层 Kotlin API 形态)。
版本记录
2026-07-31:新增公共头文件中 C 无符号整数类型的说明,并标注尺寸/索引应保持有符号。2026-07-31:初始发布。