KMP AGP 9.0 移行

Android Gradle Plugin 9.0 では、Android アプリケーションプラグインと Kotlin Multiplatform プラグインが同じモジュール内で互換性を失います。このスキルは移行をガイドします。

ステップ 0: プロジェクトの分析

変更を加える前に、プロジェクト構造を理解してください：

1. settings.gradle.kts (または .gradle) を読んですべてのモジュールを見つける
2. 各モジュールについて、その build.gradle.kts を読んでどのプラグインが適用されているかを確認する
3. プロジェクトが Gradle バージョンカタログ (gradle/libs.versions.toml) を使用しているかを確認する。存在する場合は、AGP/Gradle/Kotlin のバージョンについて読む。存在しない場合は、build.gradle.kts ファイル (通常はルートの buildscript {} または plugins {} ブロック) から直接バージョンを見つける。このガイドのすべての例を適宜調整してください — バージョンカタログの例は alias(libs.plugins.xxx) を使用しますが、直接使用は id("plugin.id") version "x.y.z" を使用します
4. gradle/wrapper/gradle-wrapper.properties から Gradle バージョンを読む
5. gradle.properties で既存の回避策がないか確認する (android.enableLegacyVariantApi)
6. org.jetbrains.kotlin.android プラグインの使用を確認する — AGP 9.0 には組み込みの Kotlin が含まれ、このプラグインは削除する必要があります
7. org.jetbrains.kotlin.kapt プラグインの使用を確認する — 組み込み Kotlin と互換性がなく、KSP または com.android.legacy-kapt に移行する必要があります
8. AGP 9.0 と互換性がない可能性のあるサードパーティプラグインを確認する (以下の「プラグイン互換性」セクションを参照)

Bash が利用可能な場合、このスキルのディレクトリから scripts/analyze-project.sh を実行して、構造化されたサマリーを取得します。

各モジュールを分類する

各モジュールについて、そのタイプを決定します：

現在のプラグイン	移行パス
kotlin.multiplatform + com.android.library	パス A — ライブラリプラグインスワップ
kotlin.multiplatform + com.android.application	パス B — 必須 Android 分割
kotlin.multiplatform と 1 つのモジュール内の複数のプラットフォーム エントリポイント	パス C — 完全な再構成 (推奨)
com.android.application または com.android.library (KMP なし)	以下の「純粋な Android のヒント」を参照

スコープを決定する

• パス B は必須 です。KMP + Android アプリケーションプラグインを組み合わせるモジュール用
• パス C は推奨 されます。プロジェクトが複数のプラットフォーム (Android、Desktop、Web) のエントリポイントを含むモノリシックな composeApp (またはそれに類するもの) モジュールを持つ場合。これは、各プラットフォームが独自のアプリモジュールを取得する新しい JetBrains デフォルトプロジェクト構造に合わせます。
• ユーザーに確認 してください。パス B のみ (最小必須) を望むか、パス C (推奨される完全な再構成) を望むか

パス A: ライブラリモジュール移行

kotlin.multiplatform + com.android.library を適用するモジュールの場合に使用します。

完全なビフォーアフターコードは references/MIGRATION-LIBRARY.md を参照してください。

概要：

1. プラグインを置き換える: com.android.library → com.android.kotlin.multiplatform.library
2. org.jetbrains.kotlin.android プラグインを削除 する (AGP 9.0 に組み込み Kotlin サポートがあります)
3. DSL を移行する: トップレベルの android {} ブロックから kotlin { android {} } への設定を移動します：

   kotlin {
       android {
           namespace = "com.example.lib"
           compileSdk = 35
           minSdk = 24
       }
   }
   

4. ソースディレクトリ名を変更 する (モジュールが KMP レイアウトの代わりに従来の Android レイアウトを使用する場合のみ):
   • src/main → src/androidMain
   • src/test → src/androidHostTest
   • src/androidTest → src/androidDeviceTest
   • モジュールが既に src/androidMain/ を使用している場合、ディレクトリ名の変更は不要です
5. 依存関係を移動 する。トップレベルの dependencies {} から sourceSets へ：

   kotlin {
       sourceSets {
           androidMain.dependencies {
               implementation("androidx.appcompat:appcompat:1.7.0")
           }
       }
   }
   

6. リソースを明示的に有効にする 。モジュールが Android または Compose Multiplatform リソースを使用する場合：

   kotlin {
       android {
           androidResources { enable = true }
       }
   }
   

7. Java コンパイルを有効にする 。モジュールに .java ソースファイルがある場合：

   kotlin {
       android {
           withJava()
       }
   }
   

8. テストを明示的に有効にする 。モジュールにユニットテストまたはインストルメントテストがある場合：

   kotlin {
       android {
           withHostTest { isIncludeAndroidResources = true }
           withDeviceTest {
               instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
           }
       }
   }
   

9. Compose ツーリング依存関係を更新 する：

   // 古い:
   debugImplementation(libs.androidx.compose.ui.tooling)
   // 新規:
   androidRuntimeClasspath(libs.androidx.compose.ui.tooling)
   

10. コンシューマー ProGuard ルールを明示的に公開 する (該当する場合):

    kotlin {
        android {
            consumerProguardFiles.add(file("consumer-rules.pro"))
        }
    }
    

11. サブ依存関係バリアント (Product Flavors / Build Types) を解決する: 新しい KMP Android ライブラリプラグインはシングルバリアント アーキテクチャを強制するため、複数のバリアント (たとえば debug/release ビルドタイプ、または free/paid などのプロダクトフレーバー) を公開する依存関係の解決方法を本来理解しません。localDependencySelection を使用してフォールバック動作を構成します：

    kotlin {
        android {
            localDependencySelection {
                // Android ライブラリ依存関係から使用するビルドタイプを優先順位順に決定する
                selectBuildTypeFrom.set(listOf("debug", "release"))
                
                // 依存関係に 'tier' ディメンションがある場合は、'free' フレーバーを選択する
                productFlavorDimension("tier") {
                    selectFrom.set(listOf("free"))
                }
            }
        }
    }
    

パス B: Android アプリケーション + 共有モジュール分割

kotlin.multiplatform + com.android.application を適用するモジュールの場合に使用します。これは AGP 9.0 互換性に必須です。

完全なガイドは references/MIGRATION-APP-SPLIT.md を参照してください。

概要：

1. androidApp モジュールを作成 します。独自の build.gradle.kts を使用：

   plugins {
       alias(libs.plugins.androidApplication)
       // kotlin-android を適用しないでください — AGP 9.0 に Kotlin サポートが含まれています
       alias(libs.plugins.composeMultiplatform)  // Compose を使用している場合
       alias(libs.plugins.composeCompiler)       // Compose を使用している場合
   }
   
   android {
       namespace = "com.example.app"
       compileSdk = 35
       defaultConfig {
           applicationId = "com.example.app"
           minSdk = 24
           targetSdk = 35
           versionCode = 1
           versionName = "1.0"
       }
       buildFeatures { compose = true }
   }
   
   dependencies {
       implementation(projects.shared)  // または共有モジュール名
       implementation(libs.androidx.activity.compose)
   }
   

2. Android エントリポイント コードを移動 します。src/androidMain/ から androidApp/src/main/ へ：
   • MainActivity.kt (および他の Activities/Fragments)
   • AndroidManifest.xml (アプリレベルのマニフェストで <application> とランチャー <activity> を含む) — <activity> の android:name が新しいロケーションで完全修飾クラス名を使用することを確認
   • Android Application クラス (存在する場合)
   • アプリレベルのリソース (ランチャーアイコン、テーマなど)
3. settings.gradle.kts に追加 する: include(":androidApp")
4. ルート build.gradle.kts に追加 する: apply false を使用したプラグイン宣言
5. 元のモジュールを変換 する。パス A ステップを使用してアプリケーションからライブラリへ
6. 異なる名前空間を確認 する: アプリモジュールとライブラリモジュールは異なる名前空間を持つ必要があります
7. 共有モジュールから削除 する: applicationId、targetSdk、versionCode、versionName
8. IDE 実行設定を更新 する: モジュールを古いモジュールから androidApp に変更

パス C: 完全な再構成 (推奨)

複数のプラットフォーム用のエントリポイントを含むモノリシック モジュール (通常は composeApp) がプロジェクトにある場合に使用します。これはオプションですが、新しい JetBrains デフォルトに合わせます。

完全なガイドは references/MIGRATION-FULL-RESTRUCTURE.md を参照してください。

ターゲット構造

project/
├── shared/              ← KMP ライブラリ (以前は composeApp)、純粋な共有コード
├── androidApp/          ← Android エントリポイントのみ
├── desktopApp/          ← Desktop エントリポイントのみ (desktop ターゲットが存在する場合)
├── webApp/              ← Wasm/JS エントリポイントのみ (web ターゲットが存在する場合)
├── iosApp/              ← iOS Xcode プロジェクト (通常は既に別々)
└── ...

ステップ

1. 最初にパス B を適用 する — androidApp を抽出 (AGP 9.0 では必須)
2. desktopApp を抽出 する (desktop ターゲットが存在する場合):
   • org.jetbrains.compose と application {} プラグインを使用してモジュールを作成
   • main() 関数を desktopMain から desktopApp/src/main/kotlin/ に移動
   • compose.desktop { application { ... } } 設定を desktopApp/build.gradle.kts に移動
   • shared モジュールの依存関係を追加
3. webApp を抽出 する (wasmJs/js ターゲットが存在する場合):
   • 適切な Kotlin/JS または Kotlin/Wasm 設定を使用してモジュールを作成
   • web エントリポイントを wasmJsMain/jsMain から webApp/src/wasmJsMain/kotlin/ に移動
   • ブラウザ/配布設定を webApp/build.gradle.kts に移動
   • shared モジュールの依存関係を追加
4. iOS — 通常、既に別々の iosApp ディレクトリにあります。確認：
   • フレームワークエクスポート設定 (binaries.framework) は shared モジュール内に留まる
   • Xcode プロジェクトが正しいフレームワーク パスを参照する
5. モジュール名を変更 する。composeApp から shared へ：
   • ディレクトリ名を変更
   • settings.gradle.kts include を更新
   • モジュール全体の依存関係参照を更新
6. 共有モジュールをクリーンアップ する: プラットフォーム アプリモジュールに移動されたすべてのプラットフォーム エントリポイント コードとアプリ固有の設定を削除

バリアント: ネイティブ UI

一部のプラットフォームがネイティブ UI (たとえば iOS の SwiftUI) を使用する場合、shared を以下に分割します：

• sharedLogic — すべてのプラットフォームで使用されるビジネス ロジック
• sharedUI — 共有 UI を使用するプラットフォームのみで使用される Compose Multiplatform UI

バリアント: サーバー

プロジェクトがサーバーターゲットを含む場合：

• ルートに server モジュールを追加
• すべてのクライアント モジュールを app/ ディレクトリの下に移動
• サーバーとクライアント間で共有されるコード (モデル、検証) 用の core モジュールを追加

バージョンアップデート

これらは移行パスに関係なく必須です：

1. Gradle ラッパー — 9.1.0+ に更新：

   # gradle/wrapper/gradle-wrapper.properties
   distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
   

2. AGP バージョン — 9.0.0+ に更新して、KMP ライブラリプラグインを追加します。

   バージョンカタログを使用 (gradle/libs.versions.toml):

   [versions]
   agp = "9.0.1"
   
   [plugins]
   android-kotlin-multiplatform-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }
   

   バージョンカタログなし — com.android.* プラグインバージョンを更新し、ルート build.gradle.kts に追加：

   plugins {
       id("com.android.application") version "9.0.1" apply false
       id("com.android.kotlin.multiplatform.library") version "9.0.1" apply false
   }
   

3. JDK — JDK 17+ が使用されていることを確認 (AGP 9.0 で必須)

4. SDK ビルドツール — 36.0.0 に更新：

   SDK Manager 経由でインストールするか、android { buildToolsVersion = "36.0.0" } で設定
   

5. gradle.properties をレビュー する — エラーの原因となるプロパティを削除し、変更されたデフォルトをレビュー (「Gradle プロパティのデフォルト変更」セクションを参照)

組み込み Kotlin 移行

AGP 9.0 は、すべての com.android.application および com.android.library モジュールに対して、デフォルトで組み込み Kotlin サポートを有効にします。org.jetbrains.kotlin.android プラグインはもはや不要で、適用すると競合します。

重要: 組み込み Kotlin は KMP サポートを置き換えません。KMP ライブラリ モジュールは引き続き org.jetbrains.kotlin.multiplatform + com.android.kotlin.multiplatform.library が必要です。

ステップ 1: kotlin-android プラグインを削除

すべてのモジュールレベルおよびルートレベルのビルド ファイルから削除：

// モジュール build.gradle.kts から削除
plugins {
    // 削除: alias(libs.plugins.kotlin.android)
    // 削除: id("org.jetbrains.kotlin.android")
}

// ルート build.gradle.kts から削除
plugins {
    // 削除: alias(libs.plugins.kotlin.android) apply false
}

バージョンカタログから削除 (gradle/libs.versions.toml):

[plugins]
# 削除: kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

ステップ 2: kapt を KSP または legacy-kapt に移行

org.jetbrains.kotlin.kapt プラグインは、組み込み Kotlin と互換性がありません。

推奨: KSP に移行 — 各アノテーション プロセッサの KSP 移行ガイドを参照。

フォールバック: com.android.legacy-kapt を使用 (AGP と同じバージョン):

# gradle/libs.versions.toml
[plugins]
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "agp" }

// モジュール build.gradle.kts — kotlin-kapt を legacy-kapt に置き換え
plugins {
    // 削除: alias(libs.plugins.kotlin.kapt)
    alias(libs.plugins.legacy.kapt)
}

ステップ 3: kotlinOptions を compilerOptions に移行

純粋な Android モジュール (非 KMP) の場合、android.kotlinOptions {} をトップレベルの kotlin.compilerOptions {} に移行：

// 古い
android {
    kotlinOptions {
        jvmTarget = "11"
        languageVersion = "2.0"
        freeCompilerArgs += listOf("-Xopt-in=kotlin.RequiresOptIn")
    }
}

// 新規
kotlin {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
        optIn.add("kotlin.RequiresOptIn")
    }
}

注: 組み込み Kotlin では、jvmTarget がデフォルトで android.compileOptions.targetCompatibility になるため、既に compileOptions を設定している場合はオプションの可能性があります。

ステップ 4: kotlin.sourceSets を android.sourceSets に移行

組み込み Kotlin では、kotlin セット付きの android.sourceSets {} のみがサポートされています：

// 組み込み Kotlin ではサポートされていません:
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

// 正しい:
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

生成されたソースの場合は、Variant API を使用：

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
}

モジュール単位の移行戦略

大規模プロジェクトの場合、モジュール単位で移行：

1. グローバルに無効化: gradle.properties で android.builtInKotlin=false
2. オプトイン プラグインを適用して、移行されたモジュール単位で有効化：

   plugins {
       id("com.android.built-in-kotlin") version "AGP_VERSION"
   }
   

3. そのモジュールについてステップ 1～4 に従う
4. すべてのモジュールが移行されたら、gradle.properties から android.builtInKotlin=false とすべてのモジュールから com.android.built-in-kotlin プラグインを削除

オプション: Kotlin を持たないモジュール向けに Kotlin を無効化

Kotlin ソースがないモジュールについては、ビルド時間を節約するために組み込み Kotlin を無効化：

android {
    enableKotlin = false
}

オプトアウト (一時的)

プラグイン互換性でブロックされた場合、一時的にオプトアウト：

# gradle.properties
android.builtInKotlin=false
android.newDsl=false  # 新しい DSL オプトアウトを使用する場合も必須

警告: ユーザーにオプトアウトを望むかどうかを確認し、望む場合は、これが一時的な対策であることを思い出させてください。

プラグイン互換性

既知の互換バージョン、オプトアウト フラグ回避策、壊れたプラグインについては、references/PLUGIN-COMPATIBILITY.md の完全な互換性テーブルを参照してください。

移行する前に、プロジェクト内のすべてのプラグインをインベントリ化し、そのテーブルと照合します。回避策なしで壊れたプラグインがある場合は、ユーザーに通知します。プラグインがオプトアウト フラグを必要とする場合は、gradle.properties に追加して、一時的な回避策として記録します。

Gradle プロパティのデフォルト変更

AGP 9.0 は多くの Gradle プロパティのデフォルトを変更します。gradle.properties で明示的に設定された値が競合する可能性がないか確認します。 主要な変更：

プロパティ	古いデフォルト	新しいデフォルト	アクション
android.uniquePackageNames	false	true	各ライブラリが一意の名前空間を持つことを確認
android.enableAppCompileTimeRClass	false	true	R フィールドの switch を if/else にリファクタリング
android.defaults.buildfeatures.resvalues	true	false	必要な場所で resValues = true を有効化
android.defaults.buildfeatures.shaders	true	false	必要な場所でシェーダーを有効化
android.r8.optimizedResourceShrinking	false	true	R8 キープルールをレビュー
android.r8.strictFullModeForKeepRules	false	true	キープルールを明示的に更新
android.proguard.failOnMissingFiles	false	true	無効な ProGuard ファイル参照を削除
android.r8.proguardAndroidTxt.disallowed	false	true	proguard-android-optimize.txt のみを使用
android.r8.globalOptionsInConsumerRules.disallowed	false	true	ライブラリ コンシューマー ルールから グローバルオプションを削除
android.sourceset.disallowProvider	false	true	androidComponents で Sources API を使用
android.sdk.defaultTargetSdkToCompileSdkIfUnset	false	true	targetSdk を明示的に指定
android.onlyEnableUnitTestForTheTestedBuildType	false	true	デフォルト以外のビルドタイプをテストする場合のみ

エラーの原因となる可能性がある以下のプロパティをチェックして削除：

• android.r8.integratedResourceShrinking — 削除、常にオン
• android.enableNewResourceShrinker.preciseShrinking — 削除、常にオン

純粋な Android のヒント

AGP 9.0 にアップグレードする非 KMP Android モジュールの場合、上記の「組み込み Kotlin 移行」ステップに従ってから、「Gradle プロパティのデフォルト変更」テーブルをレビューしてください。追加の変更：

• 新しい DSL インターフェイスをレビュー — BaseExtension は削除。CommonExtension または特定の拡張タイプを使用
• Java デフォルトが Java 8 から Java 11 に変更 — compileOptions がこれを反映していることを確認

検証

移行後、チェックリストで検証します。主要なチェック：

1. ./gradlew build がエラーなしで成功
2. すべてのプラットフォーム ターゲットが正常にビルド (Android、xcodebuild 経由の iOS、Desktop、JS/Wasm)
3. ./gradlew :shared:allTests と Android ユニットテストが成功
4. KMP モジュール内に com.android.library または com.android.application がない
5. AGP 9.0 モジュール内に org.jetbrains.kotlin.android がない
6. ソースセットが正しい名前を使用 (androidMain、androidHostTest、androidDeviceTest)
7. Variant API または DSL について非推奨警告がない

一般的な問題

詳細は references/KNOWN-ISSUES.md を参照してください。主要な落とし穴：

KMP ライブラリ プラグイン問題

• BuildConfig がライブラリ モジュール内で利用不可 — DI/AppConfiguration インターフェイスを使用するか、BuildKonfig または gradle-buildconfig-plugin をコンパイル時定数に使用
• ビルドバリアントがない — シングルバリアント アーキテクチャ。コンパイル時定数は BuildKonfig/gradle-buildconfig-plugin フレーバーを使用できるが、バリアント固有の依存関係/リソース/署名はアプリ モジュールに移動する必要あり
• NDK/JNI は新しいプラグイン内ではサポートされていない — 別の com.android.library モジュールに抽出
• Compose リソースが androidResources { enable = true } なしでクラッシュ
• コンシューマー ProGuard ルールが新しい DSL 内で consumerProguardFiles.add(file(...)) に移行されないと静かに削除
• KSP は AGP 9.0 互換性に バージョン 2.3.1+ が必須

AGP 9.0 一般問題

• BaseExtension が削除 — 古い DSL タイプを使用する規約プラグインは、CommonExtension を使用するように書き換える必要あり
• Variant API が削除 — applicationVariants、libraryVariants、variantFilter は androidComponents に置き換え
• 規約プラグイン は再ファクタリングが必要 — 古い android {} 拡張ヘルパーは廃止

リファレンス ファイル

• DSL リファレンス — 旧→新 DSL マッピング並行表示
• バージョン マトリックス — AGP/Gradle/KGP/Compose/IDE 互換性
• プラグイン互換性 — サードパーティプラグイン ステータスと回避策