Kotlin/Native в качестве фреймворка Apple – учебник

Создание библиотеки Kotlin

Компилятор Kotlin/Native может сгенерировать фреймворк для macOS и iOS из кода Kotlin. Созданный фреймворк содержит все необходимые объявления и двоичные файлы для его использования с Objective-C и Swift. Лучший способ понять эти техники – попробовать их самим. Сначала создадим небольшую библиотеку Kotlin и используем её из программы Objective-C.

Создайте файл hello.kt с содержимым библиотеки:

package example

object Object {
  val field = "A"
}

interface Interface {
  fun iMember() {}
}

class Clazz : Interface {
  fun member(p: Int): ULong? = 42UL
}

fun forIntegers(b: Byte, s: UShort, i: Int, l: ULong?) { }
fun forFloats(f: Float, d: Double?) { }

fun strings(str: String?) : String {
  return "That is '$str' from C"
}

fun acceptFun(f: (String) -> String?) = f("Kotlin/Native rocks!")
fun supplyFun() : (String) -> String? = { "$it is cool!" }

Хотя можно использовать командную строку, напрямую или в сочетании со скриптовым файлом (например, .sh или .bat файл), такой подход не масштабируется для больших проектов с сотнями файлов и библиотек. Поэтому лучше использовать компилятор Kotlin/Native с системой сборки, так как она помогает загружать и кэшировать двоичные файлы и библиотеки компилятора Kotlin/Native с транзитивными зависимостями и запускать компилятор и тесты. Kotlin/Native может использовать систему сборки Gradle через плагин kotlin-multiplatform.

Мы рассмотрели основы настройки совместимого с IDE проекта с Gradle в учебнике Простой пример приложения Kotlin/Native. Пожалуйста, ознакомьтесь с ним, если вам нужны подробные первые шаги и инструкции о том, как создать новый проект Kotlin/Native и открыть его в IntelliJ IDEA. В этом учебнике мы рассмотрим расширенные способы взаимодействия с C, связанные с использованием Kotlin/Native и многоплатформенной сборки с Gradle.

Сначала создайте папку проекта. Все пути в этом учебнике будут относительными к этой папке. Иногда может потребоваться создать недостающие директории перед добавлением новых файлов.

Используйте следующий файл сборки Gradle:

plugins {
    kotlin("multiplatform") version "1.6.20"
}

repositories {
    mavenCentral()
}

kotlin {
  macosX64("native") {
    binaries {
      framework {
        baseName = "Demo"
      }
    }
  }
}

tasks.wrapper {
  gradleVersion = "6.7.1"
  distributionType = Wrapper.DistributionType.ALL
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.6.20'
}

repositories {
    mavenCentral()
}

kotlin {
  macosX64("native") {
    binaries {
      framework {
        baseName = "Demo"
      }
    }
  }
}

wrapper {
  gradleVersion = "6.7.1"
  distributionType = "ALL"
}

Переместите файл исходного кода в папку src/nativeMain/kotlin внутри проекта. Это стандартный путь для исходного кода при использовании плагина kotlin-multiplatform. Используйте следующий блок для настройки проекта с целью генерации динамической или общей библиотеки:

binaries {
  framework {
    baseName = "Demo"
  }  
}

Вместе с macOS X64, Kotlin/Native поддерживает macos arm64 и iOS arm32, arm64 и X64 цели. Вы можете заменить macosX64 соответствующими функциями, как показано в таблице:

Запустите задачу linkNative Gradle для сборки библиотеки в IDE или вызовом следующей командной строки:

./gradlew linkNative

В зависимости от варианта, сборка генерирует фреймворк в папки build/bin/native/debugFramework и build/bin/native/releaseFramework. Давайте посмотрим, что внутри.

Заголовочные файлы сгенерированного фреймворка

Каждый из созданных фреймворков содержит заголовочный файл в <Framework>/Headers/Demo.h. Заголовки не зависят от целевой платформы (по крайней мере, в Kotlin/Native v.0.9.2). Он содержит определения для нашего кода Kotlin и несколько объявлений для всего Kotlin.

NS_ASSUME_NONNULL_BEGIN

@interface KotlinBase : NSObject
- (instancetype)init __attribute__((unavailable));
+ (instancetype)new __attribute__((unavailable));
+ (void)initialize __attribute__((objc_requires_super));
@end;

@interface KotlinBase (KotlinBaseCopying) <NSCopying>
@end;

__attribute__((objc_runtime_name("KotlinMutableSet")))
__attribute__((swift_name("KotlinMutableSet")))
@interface DemoMutableSet<ObjectType> : NSMutableSet<ObjectType>
@end;

__attribute__((objc_runtime_name("KotlinMutableDictionary")))
__attribute__((swift_name("KotlinMutableDictionary")))
@interface DemoMutableDictionary<KeyType, ObjectType> : NSMutableDictionary<KeyType, ObjectType>
@end;

@interface NSError (NSErrorKotlinException)
@property (readonly) id _Nullable kotlinException;
@end;

__attribute__((objc_runtime_name("Kotlin__TYPE__")))
__attribute__((swift_name("Kotlin__TYPE__")))
@interface Demo__TYPE__ : DemoNumber
- (instancetype)initWith__TYPE__:(__CTYPE__)value;
+ (instancetype)numberWith__TYPE__:(__CTYPE__)value;
@end;

NS_ASSUME_NONNULL_BEGIN

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Object")))
@interface DemoObject : KotlinBase
+ (instancetype)alloc __attribute__((unavailable));
+ (instancetype)allocWithZone:(struct _NSZone *)zone __attribute__((unavailable));
+ (instancetype)object __attribute__((swift_name("init()")));
@property (readonly) NSString *field;
@end;

__attribute__((swift_name("Interface")))
@protocol DemoInterface
@required
- (void)iMember __attribute__((swift_name("iMember()")));
@end;

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("Clazz")))
@interface DemoClazz : KotlinBase <DemoInterface>
- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
+ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
- (DemoLong * _Nullable)memberP:(int32_t)p __attribute__((swift_name("member(p:)")));
@end;

NS_ASSUME_NONNULL_BEGIN

__attribute__((objc_subclassing_restricted))
__attribute__((swift_name("LibKt")))
@interface DemoLibKt : KotlinBase
+ (void)forIntegersB:(int8_t)b s:(int16_t)s i:(int32_t)i l:(DemoLong * _Nullable)l __attribute__((swift_name("forIntegers(b:s:i:l:)")));
+ (void)forFloatsF:(float)f d:(DemoDouble * _Nullable)d __attribute__((swift_name("forFloats(f:d:)")));
+ (NSString *)stringsStr:(NSString * _Nullable)str __attribute__((swift_name("strings(str:)")));
+ (NSString * _Nullable)acceptFunF:(NSString * _Nullable (^)(NSString *))f __attribute__((swift_name("acceptFun(f:)")));
+ (NSString * _Nullable (^)(NSString *))supplyFun __attribute__((swift_name("supplyFun()")));
@end;

Сбор мусора и подсчёт ссылок

Objective-C и Swift используют подсчёт ссылок. Kotlin/Native также имеет собственную сборку мусора. Сборка мусора Kotlin/Native интегрирована с подсчётом ссылок Objective-C/Swift. Вам не нужно использовать ничего особенного для управления временем жизни экземпляров Kotlin/Native из Swift или Objective-C.

Использование кода из Objective-C

Давайте вызовем фреймворк из Objective-C. Для этого создайте файл main.m со следующим содержимым:

#import <Foundation/Foundation.h>
#import <Demo/Demo.h>

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        [[DemoObject object] field];
        
        DemoClazz* clazz = [[ DemoClazz alloc] init];
        [clazz memberP:42];
        
        [DemoLibKt forIntegersB:1 s:1 i:3 l:[DemoULong numberWithUnsignedLongLong:4]];
        [DemoLibKt forIntegersB:1 s:1 i:3 l:nil];
        
        [DemoLibKt forFloatsF:2.71 d:[DemoDouble numberWithDouble:2.71]];
        [DemoLibKt forFloatsF:2.71 d:nil];
        
        NSString* ret = [DemoLibKt acceptFunF:^NSString * _Nullable(NSString * it) {
            return [it stringByAppendingString:@" Kotlin is fun"];
        }];
        
        NSLog(@"%@", ret);
        return 0;
    }
}

Здесь вы вызываете классы Kotlin непосредственно из кода Objective-C. Класс Kotlin object имеет функцию статического метода object, которая позволяет нам получить единственный экземпляр объекта и вызывать методы Object на нём. Широко распространённый шаблон используется для создания экземпляра класса Clazz. Вы вызываете [[ DemoClazz alloc] init] в Objective-C. Вы также можете использовать [DemoClazz new] для конструкторов без параметров. Глобальные объявления из источников Kotlin находятся в области видимости класса DemoLibKt в Objective-C. Все методы преобразуются в статические методы этого класса. Функция strings преобразуется в функцию DemoLibKt.stringsStr в Objective-C, вы можете передать NSString непосредственно ей. Возвращаемое значение также видно как NSString.

Использование кода из Swift

Фреймворк, который вы скомпилировали с помощью Kotlin/Native, имеет вспомогательные атрибуты, чтобы упростить его использование с Swift. Преобразуйте предыдущий пример на Objective-C в Swift. В результате вы получите следующий код в main.swift:

import Foundation
import Demo

let kotlinObject = Object()
assert(kotlinObject === Object(), "Kotlin object has only one instance")

let field = Object().field

let clazz = Clazz()
clazz.member(p: 42)

LibKt.forIntegers(b: 1, s: 2, i: 3, l: 4)
LibKt.forFloats(f: 2.71, d: nil)

let ret = LibKt.acceptFun { "\($0) Kotlin is fun" }
if (ret != nil) {
  print(ret!)
}

Код Kotlin преобразуется в очень похожий код в Swift. Однако есть некоторые небольшие различия. В Kotlin любой object имеет только один экземпляр. Kotlin object Object теперь имеет конструктор в Swift, и мы используем синтаксис Object() для доступа к единственному экземпляру. Экземпляр всегда один и тот же в Swift, поэтому Object() === Object() верно. Имена методов и свойств переводятся как есть. Kotlin String преобразуется в Swift String также. Swift также скрывает от нас NSNumber* бокс. Мы можем передать Swift замыкание в Kotlin и вызвать Kotlin лямбда-функцию из Swift.

Дополнительную документацию по отображению типов можно найти в статье Взаимодействие с Objective-C.

Xcode и зависимости от фреймворка

Вам нужно настроить проект Xcode для использования нашего фреймворка. Настройка зависит от целевой платформы.

Следующие шаги

Kotlin/Native имеет двустороннее взаимодействие с языками Objective-C и Swift. Объекты Kotlin интегрируются с подсчетом ссылок Objective-C/Swift. Неиспользуемые объекты Kotlin автоматически удаляются. Статья Взаимодействие с Objective-C содержит дополнительную информацию об особенностях реализации взаимодействия. Конечно, можно импортировать существующий фреймворк и использовать его из Kotlin. Kotlin/Native поставляется с хорошим набором предварительно импортированных системных фреймворков.

Kotlin/Native также поддерживает взаимодействие с C. Ознакомьтесь с учебником Kotlin/Native как динамическая библиотека для этого.