Kotlin/Native в виде динамической библиотеки — руководство

Служебные функции среды выполнения

Структура libnative_ExportedSymbols определяет все функции, предоставляемые Kotlin/Native и вашей библиотекой. Для имитации пакетов в ней активно используются вложенные анонимные структуры. Префикс libnative_ образован от имени библиотеки.

libnative_ExportedSymbols содержит в заголовочном файле несколько вспомогательных функций:

typedef struct {
  /* Service functions. */
  void (*DisposeStablePointer)(libnative_KNativePtr ptr);
  void (*DisposeString)(const char* string);

Эти функции работают с объектами Kotlin/Native. Функция DisposeStablePointer вызывается для освобождения ссылки на объект Kotlin, а функция DisposeString — для освобождения строки Kotlin, которая в C имеет тип char*.

Следующая часть файла libnative_api.h содержит объявления структур для функций среды выполнения:

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);

Функцию IsInstance можно использовать, чтобы проверить, является ли объект Kotlin (на который ссылается указатель .pinned) экземпляром типа. Фактический набор сгенерированных операций зависит от того, как используются типы.

Функции вашей библиотеки

Рассмотрим отдельные объявления структур, используемые в вашей библиотеке. Поле libnative_kref_example имитирует структуру пакетов в вашем коде Kotlin с префиксом libnative_kref.:

typedef struct {
  /* User functions. */
  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;

В коде используются объявления анонимных структур. Здесь struct { ... } foo объявляет поле во внешней структуре анонимного типа, у которого нет имени.

Поскольку C также не поддерживает объекты, для имитации семантики объектов используются указатели на функции. Указатель на функцию объявляется как RETURN_TYPE (* FIELD_NAME)(PARAMETERS).

Поле libnative_kref_example_Clazz представляет Clazz из Kotlin. Доступ к libnative_KULong осуществляется через поле memberFunction. Единственное отличие состоит в том, что memberFunction принимает ссылку thiz в качестве первого параметра. Поскольку C не поддерживает объекты, указатель thiz передаётся явно.

В поле Clazz (то есть libnative_kref_example_Clazz_Clazz) находится конструктор, который служит функцией-конструктором для создания экземпляра Clazz.

Доступ к объекту Kotlin object Object осуществляется как к libnative_kref_example_Object. Функция _instance возвращает единственный экземпляр объекта.

Свойства преобразуются в функции. Префиксы get_ и set_ используются в именах функций-геттеров и функций-сеттеров соответственно. Например, доступное только для чтения свойство globalString из Kotlin преобразуется в функцию get_globalString в C.

Глобальные функции forFloats, forIntegers и strings преобразуются в указатели на функции в анонимной структуре libnative_kref_example.

Точка входа

Теперь, когда вы знаете, как создаётся API, можно перейти к начальной точке — инициализации структуры libnative_ExportedSymbols. Рассмотрим заключительную часть файла libnative_api.h:

extern libnative_ExportedSymbols* libnative_symbols(void);

Функция libnative_symbols позволяет открыть доступ из нативного кода к библиотеке Kotlin/Native. Это точка входа для доступа к библиотеке. Имя библиотеки используется как префикс имени функции.

macOS

Чтобы скомпилировать код C и связать его с динамической библиотекой, перейдите в каталог библиотеки и выполните следующую команду:

clang main.c libnative.dylib

Компилятор создаст исполняемый файл с именем a.out. Запустите его, чтобы выполнить код Kotlin из библиотеки C.

Linux

Чтобы скомпилировать код C и связать его с динамической библиотекой, перейдите в каталог библиотеки и выполните следующую команду:

gcc main.c libnative.so

Компилятор создаст исполняемый файл с именем a.out. Запустите его, чтобы выполнить код Kotlin из библиотеки C. В Linux необходимо добавить . в LD_LIBRARY_PATH, чтобы приложение загружало библиотеку libnative.so из текущей папки.

Windows

Сначала необходимо установить компилятор Microsoft Visual C++, поддерживающий целевую платформу x64_64.

Проще всего установить Microsoft Visual Studio на компьютере с Windows. Во время установки выберите необходимые компоненты для работы с C++, например Разработка классических приложений на C++.

В Windows динамические библиотеки можно подключить, сгенерировав статическую библиотеку-обёртку, или вручную с помощью функции LoadLibrary либо аналогичных функций Win32API.

Воспользуемся первым вариантом и создадим статическую библиотеку-обёртку для libnative.dll:

1. Вызовите lib.exe из набора инструментов, чтобы создать статическую библиотеку-обёртку libnative.lib, которая автоматизирует использование DLL в коде:

   lib /def:libnative.def /out:libnative.lib
   

2. Скомпилируйте main.c в исполняемый файл. Добавьте сгенерированный файл libnative.lib в команду сборки и запустите её:

   cl.exe main.c libnative.lib
   

   Команда создаст файл main.exe, который можно запустить.