Kotlin/NativeをAppleフレームワークとして使用する – チュートリアル

DANGER

Objective-Cライブラリのインポートは実験的です。

cinteropツールによってObjective-Cライブラリから生成されたすべてのKotlin宣言には、@ExperimentalForeignApiアノテーションが必要です。

Kotlin/Nativeに同梱されているネイティブプラットフォームライブラリ（Foundation、UIKit、POSIXなど）は、一部のAPIでのみオプトインが必要です。

Kotlin/Nativeは、Swift/Objective-Cとの双方向の相互運用性を提供します。KotlinコードでObjective-Cのフレームワークとライブラリを使用することも、Swift/Objective-CコードでKotlinモジュールを使用することもできます。

Kotlin/Nativeには、事前にインポートされた一連のシステムフレームワークが付属しており、既存のフレームワークをインポートしてKotlinから使用することも可能です。このチュートリアルでは、独自のフレームワークを作成し、macOSおよびiOS上のSwift/Objective-CアプリケーションからKotlin/Nativeコードを使用する方法を学習します。

このチュートリアルでは、以下のことを行います。

Kotlinライブラリを作成し、フレームワークにコンパイルする
生成されたSwift/Objective-C APIコードを調べる
Objective-Cからフレームワークを使用する
Swiftからフレームワークを使用する

コマンドラインを使用して、Kotlinフレームワークを直接、またはスクリプトファイル（.shや.batファイルなど）で生成できます。ただし、このアプローチは、数百のファイルやライブラリを持つ大規模なプロジェクトにはスケールしにくいです。ビルドシステムを使用すると、Kotlin/Nativeコンパイラのバイナリと推移的依存関係を持つライブラリのダウンロードとキャッシュ、およびコンパイラとテストの実行により、プロセスが簡素化されます。 Kotlin/Nativeは、Kotlin Multiplatformプラグインを介してGradleビルドシステムを使用できます。

NOTE

Macを使用し、iOSまたはその他のAppleターゲット向けアプリケーションを作成および実行したい場合は、まずXcode Command Line Toolsをインストールし、起動して、ライセンス条項に同意する必要があります。

Kotlinライブラリを作成する

TIP

Kotlin/Nativeプロジェクトの作成方法とIntelliJ IDEAでの開き方に関する詳細な最初のステップと手順については、Kotlin/Native入門チュートリアルを参照してください。

Kotlin/Nativeコンパイラは、KotlinコードからmacOSおよびiOS用のフレームワークを生成できます。作成されたフレームワークには、Swift/Objective-Cで使用するために必要なすべての宣言とバイナリが含まれています。

まず、Kotlinライブラリを作成しましょう。

src/nativeMain/kotlinディレクトリに、ライブラリの内容を含むlib.ktファイルを作成します。

kotlin

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!" }

build.gradle(.kts) Gradleビルドファイルを次のように更新します。

kotlin

    plugins {
        kotlin("multiplatform") version "2.1.21"
    }
    
    repositories {
        mavenCentral()
    }
    
    kotlin {
        iosArm64("native") {
            binaries {
                framework {
                    baseName = "Demo"
                }
            }
        }
    }
    
    tasks.wrapper {
        gradleVersion = "8.10"
        distributionType = Wrapper.DistributionType.ALL
    }
    ```
```groovy [Groovy]
    plugins {
        id 'org.jetbrains.kotlin.multiplatform' version '2.1.21'
    }
    
    repositories {
        mavenCentral()
    }
    
    kotlin {
        iosArm64("native") {
            binaries {
                framework {
                    baseName = "Demo"
                }
            }
        }
    }
    
    wrapper {
        gradleVersion = "8.10"
        distributionType = "ALL"
    }
    ```
:::

    `binaries {}`ブロックは、動的ライブラリまたは共有ライブラリを生成するようにプロジェクトを構成します。

    Kotlin/Nativeは、iOS用の`iosArm64`、`iosX64`、および`iosSimulatorArm64`ターゲット、ならびにmacOS用の`macosX64`と`macosArm64`ターゲットをサポートしています。したがって、`iosArm64()`をターゲットプラットフォームに対応するGradle関数に置き換えることができます。

    | ターゲットプラットフォーム/デバイス | Gradle関数       |
    |------------------------|-----------------------|
    | macOS x86_64           | `macosX64()`          | 
    | macOS ARM64            | `macosArm64()`        |
    | iOS ARM64              | `iosArm64()`          | 
    | iOS Simulator (x86_64) | `iosX64()`            |
    | iOS Simulator (ARM64)  | `iosSimulatorArm64()` |

    他のサポートされているAppleターゲットについては、[Kotlin/Nativeターゲットサポート](native-target-support.md)を参照してください。

3. IDEで`linkDebugFrameworkNative` Gradleタスクを実行するか、ターミナルで次のコンソールコマンドを使用してフレームワークをビルドします。

   ```bash
   ./gradlew linkDebugFrameworkNative

ビルドにより、フレームワークはbuild/bin/native/debugFrameworkディレクトリに生成されます。

TIP

linkNative Gradleタスクを使用して、フレームワークのdebugおよびreleaseバリアントの両方を生成することもできます。

生成されたフレームワークヘッダー

各フレームワークのバリアントにはヘッダーファイルが含まれています。ヘッダーはターゲットプラットフォームに依存しません。ヘッダーファイルには、Kotlinコードの定義といくつかのKotlin全体にわたる宣言が含まれています。内容を見てみましょう。

Kotlin/Nativeランタイム宣言

build/bin/native/debugFramework/Demo.framework/Headersディレクトリで、Demo.hヘッダーファイルを開きます。 Kotlinランタイム宣言を見てみましょう。

objc

NS_ASSUME_NONNULL_BEGIN
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wunknown-warning-option"
#pragma clang diagnostic ignored "-Wincompatible-property-type"
#pragma clang diagnostic ignored "-Wnullability"

#pragma push_macro("_Nullable_result")
#if !__has_feature(nullability_nullable_result)
#undef _Nullable_result
#define _Nullable_result _Nullable
#endif

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

@interface DemoBase (DemoBaseCopying) <NSCopying>
@end

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

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

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

Kotlinクラスは、Swift/Objective-CにおいてNSObjectクラスを拡張するKotlinBase基底クラスを持ちます。コレクションと例外のラッパーも存在します。ほとんどのコレクションタイプは、Swift/Objective-Cの類似のコレクションタイプにマッピングされます。

Kotlin	Swift	Objective-C
List	Array	NSArray
MutableList	NSMutableArray	NSMutableArray
Set	Set	NSSet
MutableSet	NSMutableSet	NSMutableSet
Map	Dictionary	NSDictionary
MutableMap	NSMutableDictionary	NSMutableDictionary

Kotlinの数値型とNSNumber

Demo.hファイルの次の部分には、Kotlin/Nativeの数値型とNSNumber間の型マッピングが含まれています。基底クラスはObjective-CではDemoNumber、SwiftではKotlinNumberと呼ばれます。これはNSNumberを拡張します。

各Kotlinの数値型には、対応する事前定義された子クラスがあります。

Kotlin	Swift	Objective-C	単純型
`-`	`KotlinNumber`	`<Package>Number`	`-`
`Byte`	`KotlinByte`	`<Package>Byte`	`char`
`UByte`	`KotlinUByte`	`<Package>UByte`	`unsigned char`
`Short`	`KotlinShort`	`<Package>Short`	`short`
`UShort`	`KotlinUShort`	`<Package>UShort`	`unsigned short`
`Int`	`KotlinInt`	`<Package>Int`	`int`
`UInt`	`KotlinUInt`	`<Package>UInt`	`unsigned int`
`Long`	`KotlinLong`	`<Package>Long`	`long long`
`ULong`	`KotlinULong`	`<Package>ULong`	`unsigned long long`
`Float`	`KotlinFloat`	`<Package>Float`	`float`
`Double`	`KotlinDouble`	`<Package>Double`	`double`
`Boolean`	`KotlinBoolean`	`<Package>Boolean`	`BOOL/Bool`

すべての数値型には、対応する単純型から新しいインスタンスを作成するクラスメソッドがあります。また、単純値を抽出するためのインスタンスメソッドもあります。概略的には、すべてのそのような宣言は次のようになります。

objc

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

ここで、__TYPE__は単純型名の1つであり、__CTYPE__は対応するObjective-C型です（例: initWithChar(char)）。

これらの型は、ボックス化されたKotlinの数値型をSwift/Objective-Cにマッピングするために使用されます。 Swiftでは、コンストラクタを呼び出してインスタンスを作成できます（例: KotlinLong(value: 42)）。

Kotlinのクラスとオブジェクト

classとobjectがSwift/Objective-Cにどのようにマッピングされるか見てみましょう。生成されたDemo.hファイルには、Class、Interface、およびObjectの正確な定義が含まれています。

objc

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

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

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

このコードのObjective-C属性は、SwiftとObjective-Cの両方の言語からフレームワークを使用するのに役立ちます。DemoInterface、DemoClazz、DemoObjectは、それぞれInterface、Clazz、Objectのために作成されます。

Interfaceは@protocolに変換され、classとobjectの両方は@interfaceとして表現されます。Demoプレフィックスはフレームワーク名に由来します。ヌル許容の戻り値の型ULong?は、Objective-CではDemoULongに変換されます。

Kotlinのグローバル宣言

Kotlinのすべてのグローバル関数は、Objective-CではDemoLibKtに、SwiftではLibKtに変換されます。ここでDemoはkotlinc-nativeの-outputパラメータによって設定されたフレームワーク名です。

objc

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

KotlinのStringとObjective-CのNSString*は透過的にマッピングされます。同様に、KotlinのUnit型はvoidにマッピングされます。プリミティブ型は直接マッピングされます。非ヌル許容のプリミティブ型は透過的にマッピングされます。ヌル許容のプリミティブ型は、表に示されているようにKotlin<TYPE>*型にマッピングされます。高階関数acceptFunFとsupplyFunの両方が含まれており、Objective-Cブロックを受け入れます。

型マッピングの詳細については、Swift/Objective-Cとの相互運用を参照してください。

ガベージコレクションと参照カウント

SwiftとObjective-Cは自動参照カウント（ARC）を使用します。Kotlin/Nativeには独自のガベージコレクターがあり、これはSwift/Objective-C ARCとも統合されています。

使用されていないKotlinオブジェクトは自動的に削除されます。SwiftまたはObjective-CからKotlin/Nativeインスタンスのライフタイムを制御するための追加のステップは必要ありません。

Objective-Cからコードを使用する

Objective-Cからフレームワークを呼び出してみましょう。フレームワークディレクトリに、以下のコードを含むmain.mファイルを作成します。

objc

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

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        [DemoObject.shared 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;
    }
}

ここでは、Objective-CコードからKotlinクラスを直接呼び出しています。Kotlinオブジェクトは、<オブジェクト名>.sharedクラスプロパティを使用します。これにより、オブジェクトの唯一のインスタンスを取得し、そのオブジェクトのメソッドを呼び出すことができます。

Clazzクラスのインスタンスを作成するために、一般的なパターンが使用されています。Objective-Cでは[[ DemoClazz alloc] init]を呼び出します。パラメータのないコンストラクタには[DemoClazz new]も使用できます。

Kotlinソースからのグローバル宣言は、Objective-CではDemoLibKtクラスの下にスコープされます。すべてのKotlin関数は、そのクラスのクラスメソッドに変換されます。

strings関数はObjective-CでDemoLibKt.stringsStr関数に変換されるため、NSStringを直接渡すことができます。戻り値もNSStringとして表示されます。

Swiftからコードを使用する

生成されたフレームワークには、Swiftでの使用を容易にするヘルパー属性が含まれています。前のObjective-Cの例をSwiftに変換してみましょう。

フレームワークディレクトリに、以下のコードを含むmain.swiftファイルを作成します。

swift

import Foundation
import Demo

let kotlinObject = Object.shared

let field = Object.shared.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宣言は1つのインスタンスしか持ちません。この単一のインスタンスにアクセスするには、Object.shared構文を使用します。

Kotlinの関数名とプロパティ名はそのまま翻訳されます。KotlinのStringはSwiftのStringに変換されます。SwiftはNSNumber*のボックス化も隠蔽します。SwiftのクロージャをKotlinに渡し、SwiftからKotlinのラムダ関数を呼び出すこともできます。

型マッピングの詳細については、Swift/Objective-Cとの相互運用を参照してください。

フレームワークをiOSプロジェクトに接続する

これで、生成されたフレームワークを依存関係としてiOSプロジェクトに接続できます。セットアップしてプロセスを自動化する方法は複数あります。最適な方法を選択してください。

基本型

ビルダー

Spring

Spring Boot を使用して RESTful Web サービスとデータベースを作成する

Java から Kotlin への移行ガイド

C 相互運用

Objective-C 相互運用

メモリ管理

参照とヒント

JS プラットフォーム向け Kotlin

Gradle

Dokka の実行

出力形式

Kotlin/NativeをAppleフレームワークとして使用する – チュートリアル

Kotlinライブラリを作成する

生成されたフレームワークヘッダー

Kotlin/Nativeランタイム宣言

Kotlinの数値型とNSNumber

Kotlinのクラスとオブジェクト

Kotlinのグローバル宣言

ガベージコレクションと参照カウント

Objective-Cからコードを使用する

Swiftからコードを使用する

フレームワークをiOSプロジェクトに接続する

次のステップ

Spring Boot を使用して RESTful Web サービスとデータベースを作成する

Kotlin/NativeをAppleフレームワークとして使用する – チュートリアル ​

Kotlinライブラリを作成する ​

生成されたフレームワークヘッダー ​

Kotlin/Nativeランタイム宣言 ​

Kotlinの数値型とNSNumber ​

Kotlinのクラスとオブジェクト ​

Kotlinのグローバル宣言 ​

ガベージコレクションと参照カウント ​

Objective-Cからコードを使用する ​

Swiftからコードを使用する ​

フレームワークをiOSプロジェクトに接続する ​

次のステップ ​

Kotlin/NativeをAppleフレームワークとして使用する – チュートリアル

Kotlinライブラリを作成する

生成されたフレームワークヘッダー

Kotlin/Nativeランタイム宣言

Kotlinの数値型とNSNumber

Kotlinのクラスとオブジェクト

Kotlinのグローバル宣言

ガベージコレクションと参照カウント

Objective-Cからコードを使用する

Swiftからコードを使用する

フレームワークをiOSプロジェクトに接続する

次のステップ