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

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

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

ここで提示されるモデルは、Kotlinが使用するモデルと比較して簡略化されています。しかし、この基本的なモデルはほとんどの場合で十分であるはずです。

共通コード

_共通コード_は、異なるプラットフォーム間で共有されるKotlinコードです。

単純な「Hello, World」の例を考えます。

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

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

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

すべてのKotlinコードがすべてのプラットフォームにコンパイルできるわけではありません。Kotlinコンパイラは、プラットフォーム固有の関数やクラスを共通コードで使用することを防ぎます。なぜなら、このコードは異なるプラットフォームにコンパイルできないためです。

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

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

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

ターゲット

ターゲットは、Kotlinが共通コードをコンパイルするプラットフォームを定義します。これらは、たとえばJVM、JS、Android、iOS、またはLinuxである可能性があります。前の例では、共通コードをJVMとネイティブターゲットにコンパイルしました。

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

ターゲットはプラットフォームとも呼ばれます。サポートされているターゲットの完全なリストはこちらをご覧ください。

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

kotlin {
    jvm() // Declares a JVM target
    iosArm64() // Declares a target that corresponds to 64-bit iPhones
}

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

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

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

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

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

ソースセット

_Kotlinソースセット_は、独自のターゲット、依存関係、およびコンパイラオプションを持つソースファイルのセットです。これは、マルチプラットフォームプロジェクトでコードを共有する主要な方法です。

マルチプラットフォームプロジェクトの各ソースセットは次のとおりです。

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

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

Kotlin Multiplatformプロジェクトでは、src内のディレクトリとしてソースセットを操作します。 たとえば、commonMain、iosMain、jvmMainのソースセットを持つプロジェクトは、次の構造を持ちます。

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

kotlin {
    // Targets declaration:
    // …

    // Source set declaration:
    sourceSets {
        commonMain {
            // Configure the commonMain source set
        }
    }
}

commonMain以外に、他のソースセットはプラットフォーム固有または中間である場合があります。

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

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

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

// commonMain/kotlin/common.kt
// Doesn't compile in common code
fun greeting() {
    java.io.File("greeting.txt").writeText("Hello, Multiplatform!")
}

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

// jvmMain/kotlin/jvm.kt
// You can use Java dependencies in the `jvmMain` source set
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クラスファイルにコンパイルします。

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

マルチプラットフォームプロジェクトで作業する場合、次の点に注意してください。

• Kotlinに特定のプラットフォームにコードをコンパイルさせたい場合は、対応するターゲットを宣言します。
• コードを保存するディレクトリまたはソースファイルを選択するには、まずどのターゲット間でコードを共有するかを決定します。
  • コードがすべてのターゲット間で共有される場合、commonMainで宣言する必要があります。
  • コードが1つのターゲットのみに使用される場合、そのターゲットのプラットフォーム固有のソースセット（たとえば、JVMの場合はjvmMain）で定義する必要があります。
• プラットフォーム固有のソースセットで記述されたコードは、共通ソースセットからの宣言にアクセスできます。たとえば、jvmMain内のコードはcommonMainからのコードを使用できます。しかし、その逆は真ではありません。commonMainはjvmMainからのコードを使用できません。
• プラットフォーム固有のソースセットで記述されたコードは、対応するプラットフォームの依存関係を使用できます。たとえば、jvmMain内のコードは、GuavaやSpringのようなJava専用ライブラリを使用できます。

中間ソースセット

単純なマルチプラットフォームプロジェクトには、通常、共通コードとプラットフォーム固有のコードしかありません。commonMainソースセットは、宣言されたすべてのターゲット間で共有される共通コードを表します。jvmMainのようなプラットフォーム固有のソースセットは、それぞれのターゲットのみにコンパイルされるプラットフォーム固有のコードを表します。

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

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

kotlin {
    androidTarget()
    iosArm64()   // 64-bit iPhone devices
    macosArm64() // Modern Apple Silicon-based Macs
    watchosX64() // Modern 64-bit Apple Watch devices
    tvosArm64()  // Modern Apple TV devices  
}

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

import platform.Foundation.NSUUID

fun randomUuidString(): String {
    // You want to access Apple-specific APIs
    return NSUUID().UUIDString()
}

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

このコードを各Apple固有のソースセット、すなわちiosArm64Main、macosArm64Main、watchosX64Main、およびtvosArm64Mainにコピー＆ペーストすることもできます。しかし、このようにコードを複製する方法はエラーの原因となりやすいため、推奨されません。

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

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

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

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

階層型プロジェクト構造を参照して、Kotlinがデフォルトで作成および設定するすべての中間ソースセットを見つけ、デフォルトで必要とする中間ソースセットがKotlinによって提供されない場合にどうすべきかを学びましょう。

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

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

Appleデバイスとシミュレーターのターゲット

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

• デバイスターゲットは、iOSデバイスで実行できるバイナリを生成するために使用されます。現在、iOSのデバイスターゲットはiosArm64のみです。
• シミュレーターターゲットは、お使いのマシンで起動されるiOSシミュレーター用のバイナリを生成するために使用されます。Apple silicon Macコンピューターをお持ちの場合は、iosSimulatorArm64をシミュレーターターゲットとして選択してください。IntelベースのMacコンピューターをお持ちの場合は、iosX64を使用してください。

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

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

他のMac以外のAppleターゲットにも同じことが当てはまります。たとえば、Apple TV用のtvosArm64デバイスターゲットと、Apple siliconおよびIntelベースのデバイス上のApple TVシミュレーター用のtvosSimulatorArm64およびtvosX64シミュレーターターゲットがある場合、それらすべてに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タスクを使用します。

マルチプラットフォームテストの作成と実行方法については、マルチプラットフォームアプリのテストチュートリアルで学習してください。

次のステップ

• Gradleスクリプトで事前定義されたソースセットを宣言して使用する方法について詳しく学ぶ
• マルチプラットフォームプロジェクト構造の高度な概念を探求する
• ターゲットのコンパイルとカスタムコンパイルの作成について詳しく学ぶ