KMP 用の Android Gradle ライブラリ プラグインを設定する

com.android.kotlin.multiplatform.library Gradle プラグインは、Kotlin Multiplatform（KMP）ライブラリ モジュールに Android ターゲットを追加するための公式にサポートされているツールです。プロジェクト構成を簡素化し、ビルド パフォーマンスを向上させ、Android Studio との統合を改善します。

KMP 開発に com.android.library プラグインを使用することは、Android Gradle プラグイン 9.0 以降（2025 年第 4 四半期）で非推奨となり、オプトインが必要となる Android Gradle プラグイン API に依存しています。これらの API は、Android Gradle プラグイン 10.0（2026 年後半）で削除される予定です。

このプラグインを適用するには、Android-KMP プラグインを適用するセクションを参照してください。以前の API から移行する必要がある場合は、移行ガイドを確認してください。

AGP 9.0 以降への移行については、JetBrains が KMP アプリ向けに作成したエージェント スキルを使用できます。Android Studio でスキルを使用する方法について詳しくは、スキルを使用してエージェント モードを拡張するをご覧ください。AI の結果は完全に予測できるものではないことにご注意ください。

主な機能と相違点

Android-KMP プラグインは KMP プロジェクト専用に調整されており、標準の com.android.library プラグインとはいくつかの重要な点で異なります。

• 単一バリアント アーキテクチャ: プラグインは単一バリアントを使用し、プロダクト フレーバーとビルドタイプのサポートを削除します。これにより、構成が簡素化され、ビルド パフォーマンスが向上します。

• KMP 向けに最適化: このプラグインは KMP ライブラリ向けに設計されており、共有 Kotlin コードと相互運用性に重点を置いています。Android 固有のネイティブ ビルド、AIDL、RenderScript のサポートは省略されています。

• デフォルトで無効になっているテスト: ビルド速度を向上させるため、単体テストとデバイス（インストルメンテーション）テストの両方がデフォルトで無効になっています。必要に応じて有効にできます。

• 最上位の Android 拡張機能がない: 構成は Gradle KMP DSL 内の android ブロックで処理され、一貫した KMP プロジェクト構造が維持されます。最上位の android 拡張機能ブロックはありません。

• オプトイン Java コンパイル: Java コンパイルはデフォルトで無効になっています。android ブロックで withJava() を使用して有効にします。これにより、Java コンパイルが不要な場合のビルド時間が短縮されます。

Android-KMP ライブラリ プラグインのメリット

Android-KMP プラグインには、KMP プロジェクトに次のようなメリットがあります。

• ビルドのパフォーマンスと安定性の向上: KMP プロジェクト内のビルド速度を最適化し、安定性を高めるように設計されています。KMP ワークフローに重点を置くことで、ビルド プロセスがより効率的で信頼性の高いものになります。

• IDE 統合の強化: KMP Android ライブラリを使用する際のコード補完、ナビゲーション、デバッグ、全体的なデベロッパー エクスペリエンスが向上します。

• プロジェクト構成の簡素化: このプラグインは、ビルド バリアントなどの Android 固有の複雑さを排除することで、KMP プロジェクトの構成を簡素化します。これにより、よりクリーンで保守しやすいビルドファイルが作成されます。以前は、KMP プロジェクトで com.android.library プラグインを使用すると、androidAndroidTest などのわかりにくいソースセット名が作成されることがありました。この命名規則は、標準の KMP プロジェクト構造に精通しているデベロッパーにとっては直感的ではありませんでした。

サポートされていない機能の回避策

com.android.library プラグインとの KMP 統合と比較すると、com.android.kotlin.multiplatform.library プラグインには一部の機能がありません。サポートされていない機能の回避策は次のとおりです。

• ビルド バリアント

  ビルドタイプとプロダクト フレーバーはサポートされていません。これは、新しいプラグインが単一バリアント アーキテクチャを使用しているためです。これにより、構成が簡素化され、ビルドのパフォーマンスが向上します。

  ビルド バリアントが必要な場合は、com.android.library プラグインを使用して独立した Android ライブラリ モジュールを別途作成し、そのモジュール内でビルドタイプとプロダクト フレーバーを構成してから、Kotlin Multiplatform ライブラリの androidMain ソースセットから標準のプロジェクト依存関係として使用することをおすすめします。詳しくは、Android ライブラリを作成するとビルド バリアントを構成するをご覧ください。

• データ バインディングとビュー バインディング

  これらは、Android ビューシステムと XML レイアウトに密接に結び付いた、Android 固有の UI フレームワーク機能です。新しい Android-KMP ライブラリ プラグインでは、Compose Multiplatform などのマルチプラットフォーム フレームワークを使用して UI を処理することをおすすめします。データ バインディングとビュー バインディングは、共有可能なライブラリではなく、最終的な Android アプリの実装の詳細と見なされます。

• ネイティブ ビルドのサポート

  新しいプラグインは、Android ターゲット用の標準 AAR を生成することに重点を置いています。Kotlin Multiplatform でのネイティブ コードの統合は、KMP 独自のネイティブ ターゲット（androidNativeArm64 や androidNativeX86 など）と C 相互運用機能によって直接処理されます。ネイティブ C/C++ コードを含める必要がある場合は、Android 固有の externalNativeBuild メカニズムを使用するのではなく、共通またはネイティブのソースセットの一部として定義し、kotlin ブロック内で C 相互運用を構成する必要があります。

  また、externalNativeBuild を介してネイティブ ビルドのサポートが必要な場合は、ネイティブ コードを統合できる独立した com.android.library モジュールを作成し、Kotlin Multiplatform ライブラリ プロジェクトの androidMain ソースセットからその独立したライブラリを使用することをおすすめします。詳細については、Android ライブラリを作成するとプロジェクトに C および C++ コードを追加するをご覧ください。

• BuildConfig クラス

  BuildConfig 機能は、マルチバリアント環境で最も役立ちます。新しい Kotlin マルチプラットフォーム ライブラリ プラグインはバリアントに依存せず、ビルドタイプとプロダクト フレーバーをサポートしていないため、この機能は実装されていません。代わりに、BuildKonfig プラグインまたは同様のコミュニティ ソリューションを使用して、すべてのターゲットのメタデータを生成することをおすすめします。

前提条件

com.android.kotlin.multiplatform.library プラグインを使用するには、プロジェクトが次の最小バージョン以上に構成されている必要があります。

• Android Gradle プラグイン（AGP）: 8.10.0
• Kotlin Gradle プラグイン（KGP）: 2.0.0

既存のモジュールに Android-KMP プラグインを適用する

既存の KMP ライブラリ モジュールに Android-KMP プラグインを適用する手順は次のとおりです。

1. バージョン カタログでプラグインを宣言します。バージョン カタログの TOML ファイル（通常は gradle/libs.versions.toml）を開き、プラグイン定義セクションを追加します。

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "9.2.0"
   kotlin = "KOTLIN_VERSION"
   
   [plugins]
   kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
   android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "androidGradlePlugin" }
   

2. ルート ビルドファイルでプラグイン宣言を適用します。プロジェクトのルート ディレクトリにある build.gradle.kts ファイルを開きます。apply false を使用して、プラグイン エイリアスを plugins ブロックに追加します。これにより、プラグインのロジックをルート プロジェクト自体に適用することなく、すべてのサブプロジェクトでプラグイン エイリアスを使用できるようになります。

   Kotlin

   // Root build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

   Groovy

   // Root build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform) apply false
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library) apply false
   }

3. KMP ライブラリ モジュールのビルドファイルでプラグインを適用します。KMP ライブラリ モジュールの build.gradle.kts ファイルを開き、plugins ブロック内のファイルの先頭でプラグインを適用します。

   Kotlin

   // Module-specific build.gradle.kts file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

   Groovy

   // Module-specific build.gradle file
   
   plugins {
      alias(libs.plugins.kotlin.multiplatform)
   
      // Add the following
      alias(libs.plugins.android.kotlin.multiplatform.library)
   }

4. Android KMP ターゲットを構成します。Kotlin Multiplatform ブロック（kotlin）を構成して、Android ターゲットを定義します。kotlin ブロック内で、android を使用して Android ターゲットを指定します。

   Kotlin

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              sourceSetTreeName = "test"
          }
   
          compilerOptions.configure {
              jvmTarget.set(
                  org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
              )
          }
      }
   
      sourceSets {
          androidMain {
              dependencies {
                  // Add Android-specific dependencies here
              }
          }
          getByName("androidHostTest") {
              dependencies {
              }
          }
   
          getByName("androidDeviceTest") {
              dependencies {
              }
          }
      }
      // ... other targets (JVM, iOS, etc.) ...
   }

   Groovy

   kotlin {
      android {
          namespace = "com.example.kmpfirstlib"
          compileSdk = 33
          minSdk = 24
   
          withJava() // enable java compilation support
          withHostTestBuilder {}.configure {}
          withDeviceTestBuilder {
              it.sourceSetTreeName = "test"
          }
   
          compilerOptions.options.jvmTarget.set(
              org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
          )
      }
   
      sourceSets {
          androidMain {
              dependencies {
              }
          }
          androidHostTest {
              dependencies {
              }
          }
          androidDeviceTest {
              dependencies {
              }
          }
      }
      // ... other targets (JVM, iOS, etc.) ...
   }

5. 変更を適用する。プラグインを適用して kotlin ブロックを構成したら、Gradle プロジェクトを同期して変更を適用します。

以前のプラグインから移行する

このガイドでは、以前の com.android.library プラグインから com.android.kotlin.multiplatform.library プラグインに移行する方法について説明します。

1. ソースを移動する

以前のプラグインでは、src/androidMain、src/androidHostTest、src/androidDeviceTest に加えて、src/main、src/test、src/androidTest のソースセットを使用できました。新しいプラグインは後者のソース ディレクトリのみを使用するため、ソースを src/main から src/androidMain、src/test から src/androidHostTest、src/androidTest から src/androidDeviceTest に移動する必要があります。

2. カスタム ソース ディレクトリとリソース ディレクトリを構成する

標準以外のディレクトリにソースまたはリソースがある場合は、以前は sourceSets ブロックを使用して構成していました。新しいプラグインでは、androidComponents 拡張機能を使用して、静的ソース ディレクトリをバリアントに追加します。

新しいプラグインでは、addStaticSourceDirectory メソッドはソース ディレクトリの既存のリストにディレクトリを追加します。以前のプラグインでは、setSrcDirs メソッドはリストを置き換え、srcDir メソッドはリストに追加します。

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. 依存関係の宣言

一般的なタスクは、Android 固有のソースセットの依存関係を宣言することです。新しいプラグインでは、以前使用していた一般的な dependencies ブロックとは異なり、これらを sourceSets ブロック内に明示的に配置する必要があります。

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. Android リソースを有効にする

新しいプラグインでは、ビルド パフォーマンスを最適化するために、Android リソース（res フォルダ）のサポートがデフォルトで有効になっていません。これらを使用するには、オプトインする必要があります。この変更により、Android 固有のリソースを必要としないプロジェクトに、関連するビルド オーバーヘッドの負担がかからないようにします。

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. ホストとデバイスのテストを設定する

デフォルトでは、新しいプラグインは Android ホストサイド（単体）テストとデバイスサイド（計測）テストを無効にします。テスト ソースセットと構成を作成するには明示的にオプトインする必要があります。以前のプラグインでは、これらは自動的に作成されていました。

このオプトイン モデルは、プロジェクトがスリムな状態を維持し、実際に使用しているビルド ロジックとソースセットのみが含まれていることを確認するのに役立ちます。

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. Java ソースのコンパイルを有効にする

KMP ライブラリで Android ターゲットの Java ソースをコンパイルする必要がある場合は、新しいプラグインでこの機能を明示的に有効にする必要があります。これは、プロジェクトの依存関係ではなく、プロジェクト内に直接配置された Java ファイルのコンパイルを有効にするものです。Java と Kotlin コンパイラの JVM ターゲット バージョンを設定する方法も変更されます。

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. androidComponents を使用してビルド バリアントを操作する

androidComponents 拡張機能は、ビルド アーティファクトをプログラムで操作するために引き続き使用できます。Variant API の多くは変更されていませんが、プラグインは単一のバリアントのみを生成するため、新しい AndroidKotlinMultiplatformVariant インターフェースはより制限されています。

そのため、ビルドタイプとプロダクト フレーバーに関連するプロパティは、バリアント オブジェクトで使用できなくなります。

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. Android ライブラリの依存関係のバリアントを選択する

KMP ライブラリは Android 用の単一バリアントを生成します。ただし、複数のバリエーション（free/paid プロダクト フレーバーなど）がある標準の Android ライブラリ（com.android.library）に依存している場合があります。プロジェクトがその依存関係からバリアントを選択する方法を制御することは、一般的な要件です。

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

9. Compose プレビューの依存関係を追加する

通常、内部ツールが最終的な公開アーティファクトに漏洩しないように、特定のライブラリをローカル開発環境にスコープ設定する必要があります。新しい KMP Android プラグインでは、開発依存関係をリリースコードから分離するために使用されるビルドタイプ アーキテクチャが削除されるため、このことが課題になります。

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. KMP Android ターゲットの JVM ターゲットを構成する

KMP Android プラグインは android.compilerOptions.jvmTarget を使用して JVM ターゲットを設定します。これは Java と Kotlin の両方に適用されるため、純粋な Android プロジェクトの個別の compileOptions ブロックと kotlinOptions ブロックと比較して構成が簡素化されます。

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. コンシューマー保持ルールを公開

KMP ライブラリでコンシューマー向けの keep ルール（R8 の ProGuard ルールなど）を配布する必要がある場合は、新しいプラグインで明示的に公開を有効にする必要があります。以前は、コンシューマー向けの keep ルールは指定されていればデフォルトで公開されていました。

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. ライブラリを Maven に公開する

他のプロジェクトで使用するために KMP ライブラリを Maven に公開する場合は、新しい Android-KMP プラグインを使用しているか、レガシー プラグインを使用しているかによってプロセスが異なります。

プラグイン API リファレンス

新しいプラグインの API サーフェスは com.android.library と異なります。新しい DSL とインターフェースの詳細については、次の API リファレンスをご覧ください。

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Android-KMP ライブラリ プラグインの既知の問題

新しい com.android.kotlin.multiplatform.library プラグインを適用する際に発生する可能性のある既知の問題は次のとおりです。

• 新しい android-KMP プラグインを使用すると Compose プレビューが失敗する

  • Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 と Android Gradle Plugin 9.0.0-alpha13 で修正済み

• com.android.kotlin.multiplatform.library プラグインを使用した Compose Multiplatform プレビューでの NullPointerException

  • Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 と Android Gradle Plugin 9.0.0-alpha13 で修正済み

• KMP が共通のコンパイル依存関係の解決を構成キャッシュに保存し、逆シリアル化時にエラーが発生する（Android のみ）

  • Kotlin Gradle Plugin 2.3.0-Beta2 で修正

• androidLibrary ターゲットの計測済み sourceSetTree をサポート

  • Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 と Android Gradle Plugin 9.0.0-alpha13 で修正済み