Android Gradle プラグインの DSL / API の移行スケジュール

Android Gradle プラグイン（AGP）は、Android アプリでサポートされているビルドシステムであり、さまざまなタイプのソースをコンパイルして、実際の Android デバイスまたはエミュレータ上で実行可能なアプリにまとめてリンクできます。

以下のセクションでは、AGP の DSL と API の予定されている進化について説明します。安定版リリースで新しい API が導入されると、古い API は非推奨としてマークされます。非推奨の API は、次の安定版リリースでは利用できなくなります。以降のセクションでは、AGP の各メジャー リリースで予定されている変更点について説明します。

AGP API の非推奨や削除の詳細なログについては、AGP API の更新をご覧ください。

AGP 10.0（2026 年後半）

Android Gradle プラグイン 10.0 の API の変更と最新化

AGP 10.0 では、完全に遅延した構成キャッシュ互換のビルドモデルへの移行が完了しました。このリリースは、安全でパフォーマンスの高いアーキテクチャで、以前の非遅延 API を置き換えるための数年間の取り組みの集大成です。

遅延ビルドモデルを使用する理由

以前の遅延なしビルドモデルでは、Gradle はすべての同期またはビルド呼び出し時に、すべてのプロジェクト モジュールでオブジェクトを積極的に評価し、バリアント データをクエリして、タスクを構成します。この即時評価では、実行されていないバリアントとタスクで CPU 時間とメモリが無駄になり、複雑なビルドスクリプト間で評価順序の競合が発生します。

遅延プロバイダ（Provider<T>）と最新の Variant API（androidComponents {}）を使用する完全な遅延ビルドモデルに移行することで、プロパティとタスクのワイヤリングは、アクティブなビルド実行グラフで必要な場合にのみ、オンデマンドで遅延計算されます。

このリリースで削除される以前の API は、この最新のアーキテクチャと根本的に互換性がありませんでした。これらを削除することで、AGP は Gradle 構成キャッシュとプロジェクト分離を完全にサポートできるようになり、Android Studio でのビルド速度と同期時間が大幅に改善されます。

アーキテクチャの主な違い

以前の BaseVariant API（applicationVariants.all {}）は、イーガーでタスク中心でした。これにより、構成フェーズで Gradle タスクと内部構成に直接アクセスできるようになり、最新の Gradle パフォーマンス機能が本質的に損なわれていました。

新しい Variant API（androidComponents {}）は遅延評価で、アーティファクト中心です。Gradle の Property API を広範囲に使用し、Task と TaskProvider への参照をすべて削除します。これにより、基盤となるタスク自体ではなく、入力と出力（Variant.artifacts）をクリーンに操作する必要があります。

削除および置換されるもの

以前の DSL と古い Variant API で使用されていた以前のインターフェースとクラスはすべて削除されます。ビルド スクリプトとカスタム プラグインを準備するには、次のサポート終了 API とフラグから移行します。

削除された API または機能 交換または対応が必要
タスクへの直接アクセス:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API: タスクを取得して動作を変更する代わりに、variant.artifacts を使用して、タスク間で渡される実際のファイル（アーティファクト）を追加、変更、置換します。
Eager ソース登録:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 Sources API: variant.sources.java.addGeneratedSourceDirectory(...) を使用して、カスタムタスクの出力ディレクトリを接続します。
クラスパス / 構成アクセス:
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API: バイトコードを変更または検査するには（クラスパス アクセスの最も一般的なユースケース）、AsmClassVisitorFactory を使用して variant.instrumentation.transformClassesWith(...) を使用します。
Eager プロパティの変更:
  • buildConfigField()
  • resValue()
 遅延 `MapProperty` インスタンス: variant.buildConfigFields.put(...) と variant.manifestPlaceholders.put(...) を使用します。
オプトアウト フラグ:
  • android.newDsl
  • android.builtInKotlin
 直接の代替はありません。gradle.properties からこれらのフラグを削除します。最新の DSL と組み込みの Kotlin が厳密に適用されます。
以前の Variant API 拡張機能:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 androidComponents.onVariants() に置き換えます。
バリアント フィルタリング（variantFilter ブロック） バリアント セレクタを使用して androidComponents.beforeVariants() に置き換えます。
SDK と NDK のコンポーネント:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 androidComponents.sdkComponents を使用して SDK コンポーネントにアクセスします。
テスト環境:
  • deviceProvider
  • testServer
 カスタム テストデバイスの登録を Gradle で管理されているデバイスに移行します。
廃止された登録 API:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 直接置き換えずに削除しました。
Transform API 変換を Artifacts API と AsmClassVisitorFactory に置き換えます。

すべての代替 DSL と Variant API（androidComponents {}）のインターフェースとクラスにアクセスするには、カスタム Gradle プラグインまたはビルドロジックを開発するときに、常に gradle-api アーティファクトを使用します。

移行手順

AGP 10.0 へのアップグレードをシームレスかつ予測可能なものにするには、次の移行方法を参考にしてください。

  1. AGP Upgrade Assistant を実行する: 10.0 に直接アップグレードする前に、Android Studio（Tools > AGP Upgrade Assistant）で公式の AGP Upgrade Assistant を実行します。これにより、一般的な DSL とビルド スクリプトの移行が自動化され、既存のビルド動作を維持できます。
  2. Android Studio でエージェント モードのスキルを使用する: AI アップグレード スキル（Android スキル リポジトリで利用可能な AGP アップグレード スキルなど）を活用して、Android Studio 内の複雑なビルドロジックと DSL の移行を自動化し、簡素化します。
  3. まず AGP 9.x の非推奨警告を修正する: プロジェクトを最新の AGP 9.x リリースにアップグレードし、既存の非推奨警告をすべて解決します。プロジェクトが 9.x で警告なしで動作し、android.newDsl=false や android.builtInKotlin=false に依存していない状態であれば、10.0 への移行はスムーズに行えます。
  4. サードパーティの Gradle プラグインを監査する: サードパーティのプラグインが AGP 10.0 と互換性のあるバージョンにアップグレードされていることを確認します。以前の拡張機能タイプに依存しているプラグインは、ClassCastException: ... cannot be cast to class BaseExtension などのビルドエラーを引き起こします。
  5. 公式の移行レシピを使用する: 複雑な実際の移行例と並列比較については、公式の gradle-recipes GitHub リポジトリをご覧ください。

次の比較は、以前のバリアントをすぐにクエリする方法から、androidComponents {} を使用してバリアントを遅延構成する方法に移行する方法を示しています。

以前: 以前の Variant API（AGP 10.0 で削除）

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

変更後: 最新のバリエーション API（androidComponents {}）

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

AGP 9.x で AGP 10.0 の動作をテストする方法

AGP 10.0 のリリースを待たずに、ビルド動作のテストと互換性の検証を開始できます。AGP 9.x リリースで実行している場合、gradle.properties がオプトアウトを無効にし、次の厳格な動作フラグを設定していることを確認することで、AGP 10.0 の動作を明示的に適用できます。

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

android.newDsl=true と android.builtInKotlin=true を適用することで、カスタム ビルドロジックとサードパーティのプラグインが AGP 10.0 の厳格な API 要件と完全に互換性があることを確認できます。

移行中のサブプロジェクトの選択的なオプトアウト

最新の動作をテストするためにプロジェクト全体で android.newDsl=true を有効にしたいが、特定の子プロジェクトの移行には時間がかかる場合は、AGP 9.4.0-alpha04 以降で個々のモジュールを選択的にオプトアウトできます。gradle.properties に android.newDsl.optOut を追加して、プロジェクト パスを指定します。

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

モジュールごとの Kotlin の選択的な組み込み無効化

プロジェクト全体（android.builtInKotlin=true）で Kotlin をグローバルに有効にしたいが、特定のサブプロジェクトを kotlin-android から移行する（または Kotlin コードのないモジュールの場合）には時間がかかる場合は、プロジェクト レベルではなく DSL レベルでそれらのモジュールを構成します。モジュールのビルドファイル内で enableKotlin = false を設定します。

android {
    enableKotlin = false
}

フィードバックとバグレポートのワークフロー

新しい Variant API が必要なユースケースをサポートしていることを確認します。古い API からの移行で、新しい Variant API がユースケースに対応できないという問題が発生した場合は、次の手順に沿ってフィードバックをお送りください。

  1. 既存の項目を確認する: まず、AGP 10.0 Variant API グローバル トラッキング バグで、移行を妨げる問題がすでに報告されているかどうかを確認し、問題に +1 します。
  2. 不足している API を報告する: ユースケースが固有の場合は、特定の AGP 10.0 テンプレートを使用して新しい機能リクエストを提出してください。調査とサポートを行います。

（未定）非公開の内部 AGP クラスへのアクセス権が削除されます

gradle アーティファクトへの依存関係によって、すべての内部クラスが非表示になり、gradle-api アーティファクトで使用できるインターフェースとクラスにのみコンパイル アクセス権が付与されます。これは、プラグインのコンパイルに影響します。

内部クラスにアクセスするために、手動で依存関係を追加することはできません。

AGP 9.0（2026 年 1 月）

新しい Variant API が安定版となり、古い API は非推奨となります

4.1 と 4.2 では準備中であった Variant API が安定し、gradle-api アーティファクトに配置されます。古い Variant API で使用されていた以前のインターフェースとクラスは非推奨になり、使用するには明示的なオプトインが必要になります。

新しい DSL インターフェースが安定版となり、古い DSL インターフェースは非推奨となります

4.1、4.2、7.0 では準備中であった DSL インターフェースが安定し、gradle-api アーティファクトに配置されます。DSL で使用されていた以前のインターフェースとクラスは非推奨になり、使用するには明示的なオプトインが必要になります。

非公開の内部 AGP クラスには引き続きアクセス可能

他のアーティファクトにある AGP の非公開の内部クラスには、ビルドファイルとプラグインのコンパイル中に引き続きアクセスできますが、常に破壊的に変更される可能性があるため、使用することはおすすめしません。