教程 - 使用 Kotlin/Native 开发动态库

创建一个 Kotlin 库

Kotlin/Native 编译器能够从 Kotlin 代码生成一个动态库. 一个动态库通常带有一个 .h 头文件, 你在 C 语言中使用它来调用编译后的代码.

我们来创建一个 Kotlin 库, 然后在一个 C 程序中使用它.

tip

关于如何创建一个新的 Kotlin/Native 项目, 并在 IntelliJ IDEA 中打开它, 详细的步骤和指南请参见 Kotlin/Native 开发入门 教程.

1. 进入 src/nativeMain/kotlin 目录, 并创建 lib.kt 文件, 包含以下库内容:

   package example
   
   object Object {
       val field = "A"
   }
   
   class Clazz {
       fun memberFunction(p: Int): ULong = 42UL
   }
   
   fun forIntegers(b: Byte, s: Short, i: UInt, l: Long) { }
   fun forFloats(f: Float, d: Double) { }
   
   fun strings(str: String) : String? {
       return "That is '$str' from C"
   }
   
   val globalString = "A global String"

2. 将你的 build.gradle(.kts) Gradle 构建文件更新为以下内容:

   Kotlin

   Groovy

   plugins {
       kotlin("multiplatform") version "2.1.0"
   }
   
   repositories {
       mavenCentral()
   }
   
   kotlin {
       macosArm64("native") {    // Apple Silicon 平台的 macOS
       // macosX64("native") {   // x86_64 平台的 macOS
       // linuxArm64("native") { // ARM64 平台的 Linux
       // linuxX64("native") {   // x86_64 平台的 Linux
       // mingwX64("native") {   // Windows
           binaries {
               sharedLib {
                   baseName = "native"       // macOS 和 Linux
                   // baseName = "libnative" // Windows
               }
           }
       }
   }
   
   tasks.wrapper {
       gradleVersion = "8.10"
       distributionType = Wrapper.DistributionType.ALL
   }

   plugins {
       id 'org.jetbrains.kotlin.multiplatform' version '2.1.0'
   }
   
   repositories {
       mavenCentral()
   }
   
   kotlin {
       macosArm64("native") {    // Apple Silicon 平台的 macOS
       // macosX64("native") {   // x86_64 平台的 macOS
       // linuxArm64("native") { // ARM64 平台的 Linux
       // linuxX64("native") {   // x86_64 平台的 Linux
       // mingwX64("native") {   // Windows
           binaries {
               sharedLib {
                   baseName = "native"       // macOS 和 Linux
                   // baseName = "libnative" // Windows
               }
           }
       }
   }
   
   wrapper {
       gradleVersion = "8.10"
       distributionType = "ALL"
   }

   • binaries {} 代码块配置项目, 生成一个动态库或共用库.

   • libnative 用作库名称, 以及生成的头文件名称前缀. 它还是头文件中所有声明的前缀.

3. 在 IDE 中运行 linkDebugSharedNative Gradle task, 或在你的终端中使用以下控制台命令, 来构建库:

   ./gradlew linkDebugSharedNative

构建会在 build/bin/native/debugShared 目录中生成库, 包含以下文件:

• macOS: libnative_api.h 和 libnative.dylib

• Linux: libnative_api.h 和 libnative.so

• Windows: libnative_api.h, libnative.def, 和 libnative.dll

tip

你也可以使用 linkNative Gradle task, 同时生成库的 debug 和 release 变体.

Kotlin/Native 编译器对所有平台生成 .h 文件时, 使用相同的规则. 我们来看看 Kotlin 库的 C API.

生成的头文件

我们来看看 Kotlin/Native 声明如何映射为 C 函数.

在 build/bin/native/debugShared 目录中, 打开 libnative_api.h 头文件. 第一部分包含标准的 C/C++ 代码头部和尾部:

#ifndef KONAN_LIBNATIVE_H
#define KONAN_LIBNATIVE_H
#ifdef __cplusplus
extern "C" {
#endif

/// 生成的代码的其它部分

#ifdef __cplusplus
}  /* extern "C" */
#endif
#endif  /* KONAN_LIBNATIVE_H */

在以上内容之后, libnative_api.h 一个代码块, 其中是共通的类型定义:

#ifdef __cplusplus
typedef bool            libnative_KBoolean;
#else
typedef _Bool           libnative_KBoolean;
#endif
typedef unsigned short     libnative_KChar;
typedef signed char        libnative_KByte;
typedef short              libnative_KShort;
typedef int                libnative_KInt;
typedef long long          libnative_KLong;
typedef unsigned char      libnative_KUByte;
typedef unsigned short     libnative_KUShort;
typedef unsigned int       libnative_KUInt;
typedef unsigned long long libnative_KULong;
typedef float              libnative_KFloat;
typedef double             libnative_KDouble;
typedef float __attribute__ ((__vector_size__ (16))) libnative_KVector128;
typedef void*              libnative_KNativePtr;

在创建的 libnative_api.h 文件中, Kotlin 对所有的声明使用 libnative_ 前缀. 下面是类型映射的完整列表:

libnative_api.h 文件的定义部分, 显示了 Kotlin 基本类型如何映射为 C 基本类型. Kotlin/Native 编译器会为每个库自动生成这些条目. 反过来的对应关系请参见 映射 C 语言的基本数据类型 教程.

在自动生成的类型定义之后, 你会看到你的库中使用的单独的类型定义:

struct libnative_KType;
typedef struct libnative_KType libnative_KType;

/// 自动生成的类型定义

typedef struct {
  libnative_KNativePtr pinned;
} libnative_kref_example_Object;
typedef struct {
  libnative_KNativePtr pinned;
} libnative_kref_example_Clazz;

在 C 语言中, typedef struct { ... } TYPE_NAME 语法会声明一个结构(structure).

tip

关于这个模式的详细解释, 请参见 Stackoverflow 的这个讨论串.

从这些定义你可以看到, Kotlin 类型使用相同的模式进行映射: Object 映射为 libnative_kref_example_Object, Clazz 映射为 libnative_kref_example_Clazz. 所有的结构都仅仅包含一个指针类型的 pinned 域变量. 域变量类型 libnative_KNativePtr 在头文件的前面部分中定义为 void*.

由于 C 不支持命名空间(namespace), 因此 Kotlin/Native 编译器生成很长的名称, 以免与既有的原生项目中的其它符号发生名称冲突.

typedef struct {
  /* 服务函数. */
  void (*DisposeStablePointer)(libnative_KNativePtr ptr);
  void (*DisposeString)(const char* string);

libnative_KBoolean (*IsInstance)(libnative_KNativePtr ref, const libnative_KType* type);
libnative_KBoolean (*IsInstance)(libnative_KNativePtr ref, const libnative_KType* type);
libnative_kref_kotlin_Byte (*createNullableByte)(libnative_KByte);
libnative_KByte (*getNonNullValueOfByte)(libnative_kref_kotlin_Byte);
libnative_kref_kotlin_Short (*createNullableShort)(libnative_KShort);
libnative_KShort (*getNonNullValueOfShort)(libnative_kref_kotlin_Short);
libnative_kref_kotlin_Int (*createNullableInt)(libnative_KInt);
libnative_KInt (*getNonNullValueOfInt)(libnative_kref_kotlin_Int);
libnative_kref_kotlin_Long (*createNullableLong)(libnative_KLong);
libnative_KLong (*getNonNullValueOfLong)(libnative_kref_kotlin_Long);
libnative_kref_kotlin_Float (*createNullableFloat)(libnative_KFloat);
libnative_KFloat (*getNonNullValueOfFloat)(libnative_kref_kotlin_Float);
libnative_kref_kotlin_Double (*createNullableDouble)(libnative_KDouble);
libnative_KDouble (*getNonNullValueOfDouble)(libnative_kref_kotlin_Double);
libnative_kref_kotlin_Char (*createNullableChar)(libnative_KChar);
libnative_KChar (*getNonNullValueOfChar)(libnative_kref_kotlin_Char);
libnative_kref_kotlin_Boolean (*createNullableBoolean)(libnative_KBoolean);
libnative_KBoolean (*getNonNullValueOfBoolean)(libnative_kref_kotlin_Boolean);
libnative_kref_kotlin_Unit (*createNullableUnit)(void);
libnative_kref_kotlin_UByte (*createNullableUByte)(libnative_KUByte);
libnative_KUByte (*getNonNullValueOfUByte)(libnative_kref_kotlin_UByte);
libnative_kref_kotlin_UShort (*createNullableUShort)(libnative_KUShort);
libnative_KUShort (*getNonNullValueOfUShort)(libnative_kref_kotlin_UShort);
libnative_kref_kotlin_UInt (*createNullableUInt)(libnative_KUInt);
libnative_KUInt (*getNonNullValueOfUInt)(libnative_kref_kotlin_UInt);
libnative_kref_kotlin_ULong (*createNullableULong)(libnative_KULong);
libnative_KULong (*getNonNullValueOfULong)(libnative_kref_kotlin_ULong);

typedef struct {
  /* 使用者函数. */
  struct {
    struct {
      struct {
        struct {
          libnative_KType* (*_type)(void);
          libnative_kref_example_Object (*_instance)();
          const char* (*get_field)(libnative_kref_example_Object thiz);
        } Object;
        struct {
          libnative_KType* (*_type)(void);
          libnative_kref_example_Clazz (*Clazz)();
          libnative_KULong (*memberFunction)(libnative_kref_example_Clazz thiz, libnative_KInt p);
        } Clazz;
        const char* (*get_globalString)();
        void (*forFloats)(libnative_KFloat f, libnative_KDouble d);
        void (*forIntegers)(libnative_KByte b, libnative_KShort s, libnative_KUInt i, libnative_KLong l);
        const char* (*strings)(const char* str);
      } example;
    } root;
  } kotlin;
} libnative_ExportedSymbols;

extern libnative_ExportedSymbols* libnative_symbols(void);

在 C 中使用生成的头文件

在 C 中的使用生成的头文件非常直接. 在库目录中, 创建 main.c 文件, 包含以下代码:

#include "libnative_api.h"
#include "stdio.h"

int main(int argc, char** argv) {
    // 获得引用, 用来调用 Kotlin/Native 函数
    libnative_ExportedSymbols* lib = libnative_symbols();

    lib->kotlin.root.example.forIntegers(1, 2, 3, 4);
    lib->kotlin.root.example.forFloats(1.0f, 2.0);

    // 使用 C 和 Kotlin/Native 字符串
    const char* str = "Hello from Native!";
    const char* response = lib->kotlin.root.example.strings(str);
    printf("in: %s\nout:%s\n", str, response);
    lib->DisposeString(response);

    // 创建 Kotlin 对象实例
    libnative_kref_example_Clazz newInstance = lib->kotlin.root.example.Clazz.Clazz();
    long x = lib->kotlin.root.example.Clazz.memberFunction(newInstance, 42);
    lib->DisposeStablePointer(newInstance.pinned);

    printf("DemoClazz returned %ld\n", x);

    return 0;
}

编译并运行项目

clang main.c libnative.dylib

gcc main.c libnative.so

下一步做什么

• 学习 与 Swift/Objective-C 的互操作性

• 阅读 使用 Kotlin/Native 开发 Apple Framework 教程