Gradle プラグインを作成する

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

AGP には、標準のビルドタスクと統合できる新しい手順により、ビルド入力を制御し、機能を拡張するプラグインの拡張ポイントが含まれています。AGP の以前のバージョンには、内部の実装から明確に分離された公式の API はありませんでした。バージョン 7.0 以降の AGP には、信頼できる公式の安定版 API のセットが用意されています。

AGP API のライフサイクル

AGP は Gradle 機能のライフサイクルに従って、API の状態を指定します。

  • 内部: 一般公開用ではありません。
  • 準備中: 一般公開できますが最終版ではありません。つまり、最終版では下位互換性がない可能性があります。
  • 一般公開: 一般公開が可能な安定版です。
  • 非推奨: サポートが終了し、新しい API に置き換えられました。

非推奨ポリシー

AGP は、古い API のサポート終了と、新しい安定版 API と新しいドメイン固有言語（DSL）との置き換えによって進化しています。この進化は複数の AGP リリースに適用されます。詳細については、AGP API / DSL 移行タイムラインをご覧ください。

この移行やその他の方法で AGP API のサポートが終了した場合、現在のメジャー リリースでは引き続き利用できますが、警告が表示されます。サポートが終了した API は、今後のメジャー リリースで AGP から完全に削除されます。たとえば、API が AGP 7.0 で非推奨になっている場合は、そのバージョンで使用することはできますが、警告が生成されます。この API は AGP 8.0 で使用できなくなります。

一般的なビルドのカスタマイズで使用される新しい API の例を確認するには、Android Gradle プラグインのレシピをご覧ください。一般的なビルドのカスタマイズ例を示しています。新しい API について詳しくは、リファレンス ドキュメントをご覧ください。

AGP API アーティファクトに対してコンパイルする

AGP を拡張するカスタム Gradle プラグインまたはビルドロジック（buildSrc ディレクトリ、コンベンション プラグイン モジュール、スタンドアロン プラグイン プロジェクトなど）を記述するには、完全なプラグイン実装アーティファクトではなく、AGP の gradle-api アーティファクトに対してコンパイルします。

gradle-api アーティファクトに対してコンパイルする理由

AGP は、次の 2 つの主要なアーティファクトを公開します。

  • com.android.tools.build:gradle-api: 安定版 API（AndroidComponentsExtension、Variant、公開 DSL インターフェースなど）、インキュベーション API（@Incubating とマーク）、非推奨 API（@Deprecated とマーク）など、公式 AGP API を含みます。
  • com.android.tools.build:gradle: 内部クラス、ビルドタスク、コンパイラ統合など、AGP ランタイムの実装全体が含まれます。

gradle-api アーティファクトに対してコンパイルすると、主に次のようなメリットがあります。

  • 内部 API を避ける: プラグイン コードが公式 API にのみアクセスするようにします。これにより、AGP バージョン間で予告なく変更または削除される可能性のある内部実装クラス（com.android.build.gradle.internal.*）への依存関係が誤って発生することを防ぎます。
  • ビルドの高速化とフットプリントの縮小: gradle-api アーティファクトの依存関係ツリーは、完全な gradle アーティファクトよりもはるかに小さくなります。これにより、ダウンロード サイズが小さくなり、クラスパスの汚染が回避され、ビルドロジックのコンパイルが高速化されます。
  • ランタイム分離: カスタム プラグインはコンパイル時に API 定義のみを必要とします。実行時に、Android アプリケーションまたはライブラリ プラグインが適用されると、Android ビルドによって AGP の完全な実装が提供されます。

依存関係を追加する

プラグイン プロジェクトのビルドファイルまたは buildSrc ディレクトリに、gradle-api アーティファクトを依存関係として追加します。gradle-api アーティファクトは、Google の Maven リポジトリで公開されています。アーティファクトを解決するには、ビルドに google() リポジトリが含まれていることを確認します。たとえば、settings.gradle ファイルまたは settings.gradle.kts ファイルの dependencyResolutionManagement.repositories ブロック、またはプラグインのビルドファイルまたは buildSrc ディレクトリのビルドファイルの repositories ブロックで構成します。

バージョン カタログを使用する

プロジェクトでバージョン カタログを使用している場合は、gradle/libs.versions.toml ファイルで gradle-api 依存関係を定義します。

[versions]
androidGradlePlugin = "9.4.0"

[libraries]
android-gradle-plugin-api = { group = "com.android.tools.build", name = "gradle-api", version.ref = "androidGradlePlugin" }

android-gradle-plugin-api カタログ エイリアスは、タイプセーフなアクセサー libs.android.gradle.plugin.api を生成します。

次に、プラグインのビルドファイルの dependencies ブロックに libs.android.gradle.plugin.api を追加します。

Kotlin

dependencies {
    compileOnly(libs.android.gradle.plugin.api)
}

Groovy

dependencies {
    compileOnly libs.android.gradle.plugin.api
}

バージョン カタログがない場合

プロジェクトでバージョン カタログを使用していない場合は、プラグインのビルドファイルで依存関係を直接宣言します。

Kotlin

dependencies {
    compileOnly("com.android.tools.build:gradle-api:9.4.0")
}

Groovy

dependencies {
    compileOnly 'com.android.tools.build:gradle-api:9.4.0'
}

公開を目的としたスタンドアロン プラグインのデフォルトとして compileOnly 構成オプションを使用します。使用側のプロジェクトは AGP を適用し、ビルドスクリプトのクラスパスでランタイム クラスを提供します。compileOnly 構成を使用すると、公開されたプラグインが特定の AGP バージョンのランタイム依存関係を漏洩することを防ぎ、コンシューマーのバージョン競合を回避できます。buildSrc ディレクトリのプラグインや複合ビルドの規約プラグインなど、内部ビルド ロジックを開発する場合は、代わりに implementation 構成オプションを使用します。これらのプラグインはビルド内で実行され、ランタイム クラスパスに AGP が必要です。

Gradle ビルドの基本

このガイドでは、Gradle ビルドシステム全体について説明するわけではありません。Google の API との統合に役立つ、最低限必要な一連のコンセプトについて説明します。また、より詳細な Gradle メイン ドキュメントへのリンクも記載しています。

プロジェクトの構成、ビルドファイルの編集、プラグインの適用、タスクの実行など、Gradle の動作について基本的な知識をお持ちであることを前提としています。AGP に関する Gradle の基本については、ビルドを構成するを確認することをおすすめします。Gradle プラグインのカスタマイズの一般的なフレームワークについては、カスタムの Gradle プラグインを開発するをご覧ください。

Gradle の遅延型の用語集

Gradle には、いくつかの型の「遅延」動作、すなわち大量の計算や Task の作成をビルドの後のフェーズで行うよう遅延させる機能が用意されています。これらの型は、多くの Gradle API と AGP API の中核を担うものです。遅延実行に関連する主な Gradle の型と重要なメソッドのリストを以下に示します。

Provider<T>
T 型の値を指定します（「T」は任意の型です）。これは、実行フェーズ中に get() を使用して読み取る、または map()、flatMap()、zip() のメソッドを使用して新しい Provider<S>（「S」は他の型です）に変換することができます。構成フェーズ中は get() を呼び出さないでください。