Skip to content

Kotlin Multiplatform プロジェクト構造の基本 ​

Kotlin Multiplatform を使用すると、異なるプラットフォーム間でコードを共有できます。この記事では、共有コードの制約、コード内の共有部分とプラットフォーム固有部分を区別する方法、およびその共有コードが動作するプラットフォームを指定する方法について説明します。

また、共通コード、ターゲット、プラットフォーム固有および中間ソースセット、テストの統合など、Kotlin Multiplatform プロジェクトのセットアップに関するコアコンセプトについても学びます。これらは、将来マルチプラットフォームプロジェクトをセットアップする際に役立ちます。

ここで紹介するモデルは、Kotlin が実際に使用しているモデルと比較して簡略化されています。ただし、この基本的なモデルで大半のケースには十分対応できます。

共通コード ​

共通コード(Common code) とは、異なるプラットフォーム間で共有される Kotlin コードのことです。

シンプルな「Hello, World」の例を見てみましょう。

kotlin
fun greeting() {
    println("Hello, Kotlin Multiplatform!")
}

プラットフォーム間で共有される Kotlin コードは、通常 commonMain ディレクトリに配置されます。コードファイルの配置場所は、そのコードがどのプラットフォーム向けにコンパイルされるかに影響するため重要です。

Kotlin コンパイラはソースコードを入力として受け取り、結果としてプラットフォーム固有のバイナリのセットを生成します。マルチプラットフォームプロジェクトをコンパイルする場合、同じコードから複数のバイナリを生成できます。たとえば、コンパイラは同じ Kotlin ファイルから JVM の .class ファイルとネイティブ実行可能ファイルを生成できます。

共通コード

すべての Kotlin コードがすべてのプラットフォーム向けにコンパイルできるわけではありません。コードが別のプラットフォーム向けにコンパイルできない場合、Kotlin コンパイラによって共通コード内でプラットフォーム固有の関数やクラスを使用できないよう制限されます。

たとえば、共通コードから java.io.File の依存関係を使用することはできません。これは JDK の一部ですが、共通コードは JDK クラスが利用できないネイティブコードにもコンパイルされるためです。

未解決のJava参照

共通コードでは、Kotlin Multiplatform ライブラリを使用できます。これらのライブラリは、異なるプラットフォーム上で異なる方法で実装できる共通の API を提供します。この場合、プラットフォーム固有の API は追加機能として機能し、そのような API を共通コード内で使用しようとするとエラーになります。

たとえば、kotlinx.coroutines はすべてのターゲットをサポートする Kotlin Multiplatform ライブラリですが、fun CoroutinesDispatcher.asExecutor(): Executor のように kotlinx.coroutines の並行プリミティブを JDK の並行プリミティブに変換するプラットフォーム固有の部分も含まれています。この追加の API 部分は commonMain では利用できません。

利用可能な Kotlin Multiplatform ライブラリを探すには、klibs.io を参照してください。

ターゲット ​

ターゲット(Targets)は、Kotlin が共通コードをコンパイルする対象のプラットフォームを定義します。これらは、たとえば JVM、JS、Android、iOS、Linux などです。先ほどの例では、共通コードを JVM とネイティブのターゲット向けにコンパイルしていました。

Kotlin ターゲット(Kotlin target) は、コンパイルターゲットを記述する識別子です。生成されるバイナリの形式、利用可能な言語構造、および許可される依存関係を定義します。

ターゲットはプラットフォームと呼ばれることもあります。サポートされているターゲットの完全なリストについては、サポートされているターゲットのリストを参照してください。

Kotlin に対し特定のターゲット向けにコードをコンパイルするよう指示するには、まずターゲットを宣言する必要があります。Gradle では、kotlin {} ブロック内の事前定義された DSL 呼び出しを使用してターゲットを宣言します。

kotlin
kotlin {
    jvm() // JVMターゲットを宣言
    iosArm64() // 64ビットiPhoneに対応するターゲットを宣言
}

このようにして、各マルチプラットフォームプロジェクトはサポートするターゲットのセットを定義します。ビルドスクリプトでのターゲット宣言の詳細については、階層的プロジェクト構造セクションを参照してください。

jvm と iosArm64 ターゲットが宣言されると、commonMain 内の共通コードはこれらのターゲット向けにコンパイルされます。

ターゲット

どのコードが特定のターゲット向けにコンパイルされるかを理解するには、ターゲットを Kotlin ソースファイルに付けられたラベルと考えることができます。Kotlin はこれらのラベルを使用して、コードのコンパイル方法、生成するバイナリ、およびそのコードで許可される言語構造と依存関係を決定します。

プロジェクトに単一のターゲット(JVM など)しかない場合、共通コードから適切な可視性を持つターゲット固有のシンボルにアクセスできます。 ただし、2つ目のターゲットを追加した瞬間に、ターゲット固有のシンボルは共通コードから利用できなくなります。 マイグレーションやその他の中間的なプロジェクト状態の際には、この制限に注意してください。

greeting.kt ファイルを .js にもコンパイルしたい場合は、JS ターゲットを宣言するだけで済みます。すると commonMain のコードには JS ターゲットに対応する追加の js ラベルが付き、Kotlin に対して .js ファイルを生成するよう指示します。

ターゲットラベル

これが、宣言されたすべてのターゲット向けにコンパイルされる共通コードに対する Kotlin コンパイラの仕組みです。プラットフォーム固有のコードの記述方法については、ソースセットを参照してください。

ソースセット ​

Gradle ソースセット(Gradle source set) は、独自のターゲット、依存関係、コンパイラオプションを持つソースファイルの集合です。これは、マルチプラットフォームプロジェクトでコードを共有するための主な方法です。

マルチプラットフォームプロジェクト内の各ソースセットは以下の特徴を持ちます。

  • 特定のプロジェクト内で一意の名前を持つ。
  • ソースファイルとリソースのセットを含み、通常はソースセットの名前を持つディレクトリに格納される。
  • このソースセットのコードがコンパイルされるターゲットのセットを指定する。これらのターゲットは、このソースセットで利用可能な言語構造や依存関係に影響を与える。
  • 独自の依存関係とコンパイラオプションを定義する。

Kotlin Multiplatform は、事前定義されたソースセットを多数提供しています。その1つが commonMain であり、すべてのマルチプラットフォームプロジェクトに存在し、宣言されたすべてのターゲット向けにコンパイルされます。

Kotlin Multiplatform プロジェクトでは、src 内のディレクトリとしてソースセットを操作します。 たとえば、commonMain、iosMain、および androidMain ソースセットを持つ shared モジュールは、次のような構造になります。

共有ソース

共有モジュールが Android ライブラリとしてビルドされる場合、共通の Kotlin コードは Kotlin/JVM として扱われます。iOS フレームワークとしてビルドされる場合、共通の Kotlin は Kotlin/Native として扱われます。

共通Kotlin、Kotlin/JVM、Kotlin/Native

Gradle スクリプトでは、kotlin.sourceSets {} ブロック内で名前を指定してソースセットにアクセスします。

kotlin
kotlin {
    // ターゲットの宣言:
    // …

    // ソースセットの宣言:
    sourceSets {
        commonMain {
            // commonMainソースセットの設定
        }
    }
}

commonMain の他に、他のソースセットはプラットフォーム固有または中間のいずれかになります。

プラットフォーム固有のソースセット ​

共通コードのみを持つことは便利ですが、常に可能であるとは限りません。commonMain のコードは宣言されたすべてのターゲット向けにコンパイルされるため、Kotlin ではそこでプラットフォーム固有の API を使用することは許可されていません。

ネイティブおよび JS ターゲットを持つマルチプラットフォームプロジェクトでは、commonMain 内の次のコードはコンパイルされません。

kotlin
// commonMain/kotlin/common.kt
// 共通コードではコンパイルされません
fun greeting() {
    java.io.File("greeting.txt").writeText("Hello, Multiplatform!")
}

解決策として、Kotlin はプラットフォーム固有のソースセット(プラットフォームソースセットとも呼ばれます)を作成します。各ターゲットには、そのターゲット専用にコンパイルされる対応するプラットフォームソースセットがあります。たとえば、jvm ターゲットには、JVM 専用にコンパイルされる対応する jvmMain ソースセットがあります。Kotlin では、これらのソースセットでプラットフォーム固有の依存関係(たとえば jvmMain での JDK)を使用することが許可されています。

kotlin
// jvmMain/kotlin/jvm.kt
// `jvmMain` ソースセットではJavaの依存関係を使用できます
fun jvmGreeting() {
    java.io.File("greeting.txt").writeText("Hello, Multiplatform!")
}

特定のターゲットへのコンパイル ​

特定のターゲットへのコンパイルは、複数のソースセットに対して機能します。Kotlin がマルチプラットフォームプロジェクトを特定のターゲット向けにコンパイルするとき、そのターゲットのラベルが付けられたすべてのソースセットを収集し、それらからバイナリを生成します。

jvm、iosArm64、および js ターゲットを持つ例を考えてみましょう。Kotlin は共通コード用の commonMain ソースセットと、特定のターゲットに対応する jvmMain、iosArm64Main、および jsMain ソースセットを作成します。

特定のターゲットへのコンパイル

JVM へのコンパイル中、Kotlin は「JVM」のラベルが付いたすべてのソースセット、つまり jvmMain と commonMain を選択します。その後、それらをまとめて JVM クラスファイルにコンパイルします。

JVMへのコンパイル

Kotlin は commonMain と jvmMain を一緒にコンパイルするため、結果のバイナリには commonMain と jvmMain の両方からの宣言が含まれます。

マルチプラットフォームプロジェクトを操作する際は、次の点を覚えておいてください。

  • Kotlin に特定のプラットフォーム向けにコードをコンパイルさせたい場合は、対応するターゲットを宣言します。

  • コードを保存するディレクトリまたはソースファイルを選択するには、まずどのターゲット間でコードを共有したいかを決定します。

    • コードがすべてのターゲット間で共有される場合は、commonMain で宣言する必要があります。
    • コードが1つのターゲットのみに使用される場合は、そのターゲット用のプラットフォーム固有のソースセット(JVM の場合は jvmMain など)で定義する必要があります。
  • プラットフォーム固有のソースセットに記述されたコードは、共通ソースセットからの宣言にアクセスできます。たとえば、jvmMain のコードは commonMain のコードを使用できます。ただし、その逆は成り立ちません。commonMain は jvmMain のコードを使用できません。

  • プラットフォーム固有のソースセットに記述されたコードは、対応するプラットフォームの依存関係を使用できます。たとえば、jvmMain のコードは Guava や Spring などの Java 専用ライブラリを使用できます。

中間ソースセット ​

シンプルなマルチプラットフォームプロジェクトには、通常、共通コードとプラットフォーム固有コードのみが含まれます。 commonMain ソースセットは、宣言されたすべてのターゲット間で共有される共通コードを表します。jvmMain などのプラットフォーム固有のソースセットは、それぞれのターゲット向けにのみコンパイルされるプラットフォーム固有コードを表します。

実際には、よりきめ細かなコード共有が必要になることがよくあります。

すべての最新の Apple デバイスと Android デバイスをターゲットにする必要がある例を考えてみましょう。

kotlin
kotlin {
    android()
    iosArm64()   // 64ビットiPhoneデバイス
    macosArm64() // 最新のApple Silicon搭載Mac
    watchosArm64() // 最新の64ビットApple Watchデバイス
    tvosArm64()  // 最新のApple TVデバイス  
}

そして、すべての Apple デバイス向けに UUID を生成する関数を追加するためのソースセットが必要です。

kotlin
import platform.Foundation.NSUUID

fun randomUuidString(): String {
    // Apple固有のAPIにアクセスしたい
    return NSUUID().UUIDString()
}

この関数を commonMain に追加することはできません。commonMain は Android を含む宣言されたすべてのターゲット向けにコンパイルされますが、platform.Foundation.NSUUID は Android では利用できない Apple 固有の API であるためです。commonMain で NSUUID を参照しようとすると、Kotlin はエラーを表示します。

このコードを Apple 固有の各ソースセット(iosArm64Main、macosArm64Main、watchosArm64Main、tvosArm64Main)にコピー&ペーストすることもできます。しかし、このようにコードを重複させることはエラーが発生しやすいため推奨されません。

この問題を解決するために、中間ソースセット(Intermediate source sets) を使用できます。中間ソースセットとは、プロジェクト内のすべてではなく、一部のターゲット向けにコンパイルされる Kotlin ソースセットです。中間ソースセットは、階層ソースセット(hierarchical source sets)または単に階層(hierarchies)と呼ばれることもあります。

Kotlin は、デフォルトでいくつかの中間ソースセットを作成します。この特定のケースでは、結果のプロジェクト構造は次のようになります。

中間ソースセット

ここで、下部にある色付きのブロックはプラットフォーム固有のソースセットです。わかりやすくするためにターゲットラベルは省略されています。

appleMain ブロックは、Apple 固有のターゲット向けにコンパイルされるコードを共有するために Kotlin によって作成された中間ソースセットです。appleMain ソースセットは Apple ターゲット向けにのみコンパイルされます。そのため、Kotlin では appleMain で Apple 固有の API を使用することが許可されており、ここに randomUUID() 関数を追加できます。

Kotlin がデフォルトで作成およびセットアップするすべての中間ソースセットを確認し、必要な中間ソースセットがデフォルトで提供されていない場合の対処法については、階層的プロジェクト構造を参照してください。

特定のターゲットへのコンパイル中、Kotlin はそのターゲットのラベルが付いたすべての中間ソースセットを含むソースセットを取得します。したがって、iosArm64 プラットフォームターゲットへのコンパイル時には、commonMain、appleMain、および iosArm64Main ソースセットに記述されたすべてのコードが結合されます。

ネイティブ実行可能ファイル

一部のソースセットにソースが含まれていなくても問題ありません。たとえば、iOS 開発では、通常、iOS シミュレータ用ではなく iOS デバイス専用のコードを提供する必要はありません。そのため、iosArm64Main が使用されることは稀です。

Appleデバイスおよびシミュレータターゲット ​

Kotlin Multiplatform を使用して iOS モバイルアプリケーションを開発する場合、通常は iosMain ソースセットを使用します。これは ios ターゲット用のプラットフォーム固有のソースセットと思われるかもしれませんが、単一の ios ターゲットというものは存在しません。ほとんどのモバイルプロジェクトには、少なくとも2つのターゲットが必要です。

  • デバイスターゲット:iOS デバイス上で実行可能なバイナリを生成するために使用されます。現在、iOS 用のデバイスターゲットは iosArm64 の1つのみです。
  • シミュレータターゲット:マシン上で起動された iOS シミュレータ用のバイナリを生成するために使用されます。Apple Silicon Mac をお使いの場合は、シミュレータターゲットとして iosSimulatorArm64 を選択します。

iosArm64 デバイスターゲットのみを宣言した場合、ローカルマシン上でアプリケーションやテストを実行およびデバッグすることはできません。

iOS デバイス用とシミュレータ用の Kotlin コードは通常同じであるため、iosArm64Main や iosSimulatorArm64Main などのプラットフォーム固有のソースセットは通常空になります。これらすべてでコードを共有するために、iosMain 中間ソースセットのみを使用できます。

同じことが、Mac 以外の他の Apple ターゲットにも当てはまります。たとえば、Apple TV 用の tvosArm64 デバイスターゲットと、Apple Silicon デバイス上の Apple TV シミュレータ用の tvosSimulatorArm64 シミュレータターゲットがある場合、それらすべてに対して tvosMain 中間ソースセットを使用できます。

テストとの統合 ​

実際のプロジェクトでは、メインのプロダクションコードと並行してテストも必要になります。そのため、デフォルトで作成されるすべてのソースセットには Main と Test のサフィックスが付いています。Main にはプロダクションコードが含まれ、Test にはそのコード用のテストが含まれます。これらの間の接続は自動的に確立され、テストは追加の設定なしで Main コードによって提供される API を使用できます。

Test に対応するソースセットも、Main と同様のソースセットです。たとえば、commonTest は commonMain に対応するもので、宣言されたすべてのターゲット向けにコンパイルされるため、共通のテストを作成できます。jvmTest などのプラットフォーム固有のテストソースセットは、プラットフォーム固有のテスト(JVM 固有のテストや JVM API を必要とするテストなど)を記述するために使用されます。

共通テストを記述するためのソースセットを用意するだけでなく、マルチプラットフォーム対応のテストフレームワークも必要です。Kotlin は、@kotlin.Test アノテーションや assertEquals、assertTrue などのさまざまなアサーションメソッドを備えたデフォルトの kotlin.test ライブラリを提供しています。

各プラットフォームの通常のテストのように、それぞれのソースセットにプラットフォーム固有のテストを記述できます。メインコードと同様に、各ソースセットにプラットフォーム固有の依存関係を持たせることができます(例: JVM 用の JUnit、iOS 用の XCTest)。特定のターゲットに対してテストを実行するには、<targetName>Test タスクを使用します。

マルチプラットフォームテストの作成および実行方法については、マルチプラットフォームアプリのテストチュートリアルを参照してください。

次のステップ ​