Файл определения

Импорт заголовочных файлов

Если библиотека C не содержит модуля Clang, а состоит из набора заголовочных файлов, используйте свойство headers, чтобы указать заголовочные файлы для импорта:

headers = curl/curl.h

headerFilter = SomeLibrary/**

excludeFilter = SomeLibrary/time.h

Импорт модулей

Если библиотека Objective-C содержит модуль Clang, используйте свойство modules, чтобы указать модуль для импорта:

modules = UIKit

Задание имени пакета

Используйте свойство package, чтобы задать префикс пакета для сгенерированного API Kotlin:

package = png

Если это свойство не задано, компилятор создает объявления в корневом пакете.

Передача параметров компилятора и компоновщика

Используйте свойство compilerOpts для передачи параметров компилятору C, который используется для анализа заголовочных файлов. Для передачи параметров компоновщику, который используется для компоновки конечных исполняемых файлов, используйте linkerOpts. Например:

compilerOpts = -DFOO=bar
linkerOpts = -lpng

Также можно указать параметры для конкретной цели, которые применяются только к этой цели:

compilerOpts = -DBAR=bar
compilerOpts.linux_x64 = -DFOO=foo1
compilerOpts.macos_x64 = -DFOO=foo2

В этой конфигурации заголовочные файлы анализируются с помощью -DBAR=bar -DFOO=foo1 в Linux и -DBAR=bar -DFOO=foo2 в macOS. Обратите внимание, что у любого параметра файла определения могут быть общая часть и часть для конкретной платформы.

Игнорирование определенных функций

Используйте свойство excludedFunctions, чтобы указать список имен функций, которые нужно игнорировать. Это может быть полезно, если нет гарантии, что объявленную в заголовочном файле функцию можно вызвать, а определить это автоматически сложно или невозможно. Это свойство также можно использовать для обхода ошибки в самом механизме взаимодействия.

Включение статической библиотеки

Иногда удобнее поставлять статическую библиотеку вместе с продуктом, чем полагаться на то, что она доступна в среде пользователя. Чтобы включить статическую библиотеку в .klib, используйте свойства staticLibrary и libraryPaths:

headers = foo.h
staticLibraries = libfoo.a
libraryPaths = /opt/local/lib /usr/local/opt/curl/lib

При наличии приведенного выше фрагмента инструмент cinterop ищет libfoo.a в /opt/local/lib и /usr/local/opt/curl/lib и, если находит, включает бинарный файл библиотеки в klib.

При использовании в программе klib такого типа библиотека компонуется автоматически.

Настройка генерации перечислений

Используйте свойство strictEnums, чтобы сгенерировать перечисления как перечисления Kotlin, или nonStrictEnums, чтобы сгенерировать их как целочисленные значения. Если перечисление не включено ни в один из этих списков, способ его генерации определяется эвристически.

Настройка преобразования строк

Используйте свойство noStringConversion, чтобы отключить автоматическое преобразование параметров функции const char* в String Kotlin.

Разрешение вызова неосновного инициализатора

По умолчанию компилятор 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».

Если вы автор библиотеки, вы можете помочь пользователям устранить ошибки компоновщика с помощью пользовательских сообщений. Для этого добавьте свойство userSetupHint=message в файл .def или передайте параметр компилятора -Xuser-setup-hint в cinterop.

Добавление пользовательских объявлений

Иногда перед созданием биндингов в библиотеку необходимо добавить пользовательские объявления C (например, для макросов). Вместо создания дополнительного заголовочного файла с этими объявлениями можно добавить их непосредственно в конец файла .def после разделительной строки, содержащей только последовательность-разделитель ---:

headers = errno.h
---

static inline int getErrno() {
    return errno;
}

Обратите внимание, что эта часть файла .def обрабатывается как часть заголовочного файла, поэтому функции с телом следует объявлять как static. Объявления анализируются после включения файлов из списка headers.