ビルド依存関係を追加する

Android Studio の Gradle ビルドシステムを使うと、外部バイナリや 他のライブラリ モジュールを依存関係として簡単にビルドに含めることができます。依存関係は、マシン上またはリモート リポジトリで見つけることができます。推移的な依存関係が宣言されている場合、それも自動的に含まれます。このページでは、Android Gradle プラグイン（AGP）に特有の動作と構成を含め、Android プロジェクトで依存関係を使う方法について詳しく説明します。Gradle の依存関係の概念をより深く理解するには、 依存関係管理に関する Gradle のガイドもご覧ください。 ただし、Android プロジェクトでは、このページに定義された 依存関係 コンフィグレーションのみを使用する必要がある点に注意してください。

ライブラリまたはプラグインの依存関係を追加する

ビルド依存関係を追加して管理する最良の方法は、バージョン カタログを使用することです。 これは、新しいプロジェクトでデフォルトで使用される方法です。このセクションでは、Android プロジェクトで使用される最も一般的な タイプの構成について説明します。その他のオプションについては、 Gradle のドキュメント をご覧ください。バージョン カタログを使用するアプリの例については、 Now in Androidをご覧ください。 バージョン カタログを使用せずにビルド依存関係をすでに設定していて、マルチモジュール プロジェクトがある場合は、 移行することをおすすめします。

ネイティブ依存関係（一般的ではありません）の追加と管理については、 ネイティブ依存関係をご覧ください。

次の例では、リモート バイナリ 依存関係（Jetpack Macrobenchmark ライブラリ）、ローカル ライブラリ モジュール 依存関係（myLibrary）、プラグイン 依存関係（Android Gradle プラグイン）をプロジェクトに追加します。プロジェクトにこれらの依存関係を追加する一般的な 手順は次のとおりです。

  1. バージョン カタログ ファイルの [versions]セクションに、必要な依存関係のバージョンのエイリアスを追加します。このファイルは libs.versions.tomlと呼ばれ、gradleディレクトリの [**プロジェクト**]ビューまたは [**Gradle スクリプト**]の [**Android**]ビューにあります。

    [versions]
agp = "8.3.0"
androidx-macro-benchmark = "1.2.2"
my-library = "1.4"

[libraries]
...

[plugins]
...

    エイリアスには、ハイフンまたはアンダースコアを含めることができます。これらのエイリアスは、ビルドスクリプトで参照できるネストされた値 を生成します。参照は、 カタログの名前（libs.versions.toml の libs 部分）で始まります。単一のバージョン カタログを使用する場合は、デフォルト値の 「libs」を維持することをおすすめします。

  2. [libraries] ファイルの [plugins]（ リモート バイナリまたはローカル ライブラリ モジュールの場合）または libs.versions.toml（ プラグインの場合）セクションに、依存関係のエイリアスを追加します。

    [versions]
...

[libraries]
androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }

[plugins]
androidApplication = { id = "com.android.application", version.ref = "agp" }

    一部のライブラリは、ライブラリ ファミリーとそのバージョンをグループ化した公開済みの Bill of Materials（BOM）で 利用できます。バージョン カタログとビルドファイルに BOM を含めて、これらのバージョンを管理できます。詳細については、 Bill of Materials を使用するをご覧ください。

  3. 依存関係を必要とする モジュールのビルドスクリプトに、依存関係エイリアスへの参照を追加します。ビルドスクリプトから参照する場合は、エイリアスのアンダースコアとハイフン をドットに変換します。モジュール レベルのビルドスクリプト は次のようになります。

    Kotlin

    plugins {
  alias(libs.plugins.androidApplication)
}

dependencies {
  implementation(libs.androidx.benchmark.macro)
  implementation(libs.my.library)
}

    Groovy

    plugins {
  alias 'libs.plugins.androidApplication'
}

dependencies {
  implementation libs.androidx.benchmark.macro
  implementation libs.my.library
}

    プラグイン参照にはカタログ名の後に plugins が含まれ、 バージョン参照にはカタログ名の後に versions が含まれます（バージョン 参照は一般的ではありません。バージョン 参照の例については、同じバージョン番号の依存関係をご覧ください）。ライブラリ 参照には libraries 修飾子が含まれていないため、ライブラリ エイリアスの先頭に versions または plugins を使用することはできません。

依存関係を構成する

dependencies ブロックで、複数の依存関係構成のうちの 1 つ（上記の implementation など）を使用して、ライブラリ依存関係を宣言できます。それぞれの依存関係構成は、依存関係の使用方法についてのさまざまな 指示を Gradle に与えます。次の表に、Android プロジェクトの依存関係に使用できる各構成について説明します。

構成 動作
implementation Gradle は依存関係をコンパイル クラスパスに追加し、また 依存関係をビルド出力にパッケージ化します。モジュールで implementation 依存関係を構成している場合、Gradle はモジュールの依存関係がコンパイル時に他のモジュールに通知されないようにします。つまり、依存関係 は、現在の モジュールに依存する他のモジュールでは使用できません。

`api` の代わりにこの依存関係構成を使用すると、ビルドシステムで再コンパイルする必要があるモジュールの数が減るため、ビルド時間を大幅に短縮できます。apiたとえば、implementation 依存関係の API が変更された場合、Gradle はその依存関係 と、それに直接依存するモジュールのみを再コンパイルします。ほとんどのアプリ モジュールとテスト モジュールでは、この構成を使用する必要があります。
api Gradle は依存関係をコンパイル クラスパスとビルド 出力に追加します。モジュールに api 依存関係が含まれている場合、Gradle はモジュールの依存関係を他のモジュールに推移的にエクスポートします。この場合、他のモジュールは実行時とコンパイル時の両方で依存関係を利用できるようになります。

この構成は慎重に使用し、他の上流モジュールに推移的にエクスポートする必要がある依存関係のみを対象として使用する必要があります。`api` 依存関係の外部 API が変更された場合、Gradle はコンパイル時に、その依存関係にアクセスできるすべてのモジュールを再コンパイルします。apiapi 依存関係の数が多いと、 ビルド時間が大幅に増加する可能性があります。ライブラリ モジュールでは、分離されたモジュールに依存関係の API を公開する場合を除き、implementation 依存関係を使用する必要があります。
compileOnly Gradle は、コンパイル クラスパスのみに依存関係を追加します （ビルド出力には追加されません）。これは、Android モジュールを作成しており、コンパイル時には依存関係が必要であるものの、実行時にはなくても構わない場合に便利です。たとえば、コンパイル時アノテーションのみを含むライブラリ（通常はコードの生成に使用されますが、ビルド出力には含まれないことが多い）に依存している場合は、そのライブラリを compileOnly とマークできます。

この構成を使用する場合は、ライブラリ モジュールに 実行時に依存関係が利用可能かどうかを確認する条件を含める必要があります。次に、依存関係が提供されていなくても構成が機能するように、その動作をスムーズに 切り替える必要があります。これは、重要でない一時的な依存関係を追加しないことにより最終的なアプリのサイズを削減するのに役立ちます。

注: compileOnly `compileOnly` 構成と Android アーカイブ（AAR）の依存関係を一緒に使用することはできません。

runtimeOnly Gradle は、実行時に使用できるように、ビルド出力だけに依存関係を追加します。つまり、コンパイル クラスパスには追加されません。 Android で使用されることはほとんどありませんが、サーバー アプリケーションでロギング実装を提供するために一般的に使用されます。たとえば、ライブラリは実装を含まないロギング API を使用できます。そのライブラリの利用者は、それを implementation 依存関係として追加し、使用する実際のロギング 実装の runtimeOnly 依存関係を含めることができます。
ksp
kapt
annotationProcessor

これらの構成は、コードがコンパイルされる前に、コード内のアノテーション やその他のシンボルを処理するライブラリを提供します。通常、コードを検証したり、追加のコードを生成したりして、記述する必要があるコードを減らします。

このような依存関係を追加するには、ksp、kapt、または annotationProcessor 構成を使用して、アノテーション プロセッサ クラスパスに依存関係を追加する必要があります。これらの 構成を使用すると、コンパイル クラスパスとアノテーション プロセッサ クラスパスが別々になり、ビルドのパフォーマンスが向上します。Gradle は、コンパイル クラスパスでアノテーション プロセッサを検出すると、ビルド時間に悪影響を及ぼす コンパイル回避を無効にします（Gradle 5.0 以降では、コンパイル クラスパスで検出されたアノテーション プロセッサは無視されます）。

JAR ファイルに次のファイルが含まれる場合、Android Gradle プラグインは、依存関係がアノテーション プロセッサであると想定します。

META-INF/services/javax.annotation.processing.Processor

プラグインは、コンパイル クラスパス上のアノテーション プロセッサを検出すると、ビルドエラーを生成します。

ksp は Kotlin シンボル プロセッサであり、 Kotlin コンパイラによって実行されます。

kapt と apt は、Kotlin コンパイラまたは Java コンパイラが実行される前にアノテーションを処理する別のツールです。

使用する構成を決定する際は、次の点を考慮してください。

  • プロセッサが Kotlin シンボル プロセッサとして使用できる場合は、 それを ksp 依存関係として使用します。 Kotlin シンボル プロセッサの使用方法について詳しくは、kapt から ksp に移行する をご覧ください。
  • プロセッサが Kotlin シンボル プロセッサとして使用できない場合:
    • プロジェクトに Kotlin ソースが含まれている場合（Java ソースも含むことができます）、を使用して含めます。kapt
    • プロジェクトで Java ソースのみを使用する場合は、 annotationProcessor を使用して含めます。

アノテーション プロセッサの使用方法について詳しくは、 アノテーション プロセッサを追加するをご覧ください。
lintChecks

この構成を使用して、Android アプリ プロジェクトのビルド時に Gradle で実行する lint チェックを含むライブラリを含めます。

lint.jar ファイルを含む AAR は、その lint.jar ファイルで定義されたチェックを自動的に実行します。明示的な lintChecks 依存関係を追加する必要はありません。これにより、ライブラリと関連する lint チェックを 1 つの 依存関係で定義できるため、利用者がライブラリを使用するときにチェックが実行されます。
lintPublish Gradle で lint チェックを lint.jar ファイルにコンパイルして AAR にパッケージ化するには、Android ライブラリ プロジェクトでこの構成を使用します。これにより、AAR を使用するプロジェクトもそれらの lint チェックを適用するようになります。以前に lintChecks 依存関係構成を使用して公開 AAR に lint チェックを含めていた場合は、その依存関係を移行して、代わりに lintPublish 構成を使用する必要があります。

Kotlin

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

Groovy

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

特定のビルド バリアントの依存関係を構成する

上記のすべての構成は、すべてのビルド バリアントに依存関係を適用します。これに対し、特定のビルド バリアントのソースセットまたはテスト用のソースセットのみに依存関係を宣言する場合は、コンフィグレーション名の先頭を大文字にして、その先頭に対象のビルド バリアントまたはテスト用のソースセットの名前を付加する必要があります。

たとえば、implementation 構成を使用して、リモート バイナリ依存関係を「free」プロダクト フレーバーのみに追加するには、次のようにします。

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

一方、プロダクト フレーバーとビルドタイプを組み合わせたバリアントに依存関係を追加する場合は、コンフィグレーション名を初期化する必要があります。

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

ローカルテストとインストルメンテーション テストに implementation 依存関係を追加するには 、次のようにします。

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

ただし、この状況では、一部の構成は効果がありません。たとえば、他のモジュールが androidTest に依存できないため、以下の警告が androidTestApi 構成を使用すると表示されます。

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

依存関係の順序

依存関係をリストする順序は、それぞれの優先度を示します。たとえば、1 番目のライブラリは 2 番目のライブラリより優先度が高く、2 番目は 3 番目より優先度が高くなります。この順序は、ライブラリからアプリにリソースをマージする場合、またはマニフェスト要素をマージする場合に重要です。

たとえば、プロジェクトで以下を宣言したとします。

  • LIB_A への依存関係と LIB_B への依存関係（この順序）
  • LIB_A は LIB_C と LIB_D に依存（この順序）
  • LIB_B も LIB_C に依存

この場合、依存関係の順序を展開すると次のようになります。

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. LIB_C

これにより、LIB_A と LIB_B はいずれも LIB_C より優先され、LIB_D は LIB_B よりも優先度が高くなります。これは、依存元の LIB_A の優先度が LIB_B より高いためです。

異なるプロジェクトのソースや依存関係のマニフェストをマージする方法については、 複数のマニフェスト ファイルをマージするをご覧ください。

Google Play Console の依存関係情報

アプリをビルドすると、AGP には、アプリにコンパイルされるライブラリ 依存関係を記述したメタデータが含まれます。アプリがアップロードされると、Google Play Console はこのメタデータを検査して、アプリが使用している SDK と 依存関係の既知の問題に関するアラートを発信します。また、場合によっては、その問題を解決するための実用的なフィードバックも 提供します。

データは圧縮され、Google Play の署名鍵で暗号化されて、 リリースアプリの署名ブロックに保存されます。この依存関係 ファイルを保持して、安全で優れたユーザー エクスペリエンスのために役立てることをおすすめします。モジュールの build.gradle.kts ファイルに次の dependenciesInfo ブロックを含めることで、オプトアウトできます。

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

依存関係に関する Google のポリシーと潜在的な問題について詳しくは、 アプリでサードパーティの SDK を使用する場合の サポートページをご覧ください。

SDK 分析情報

Google Play SDK Index の公開 SDK について、次の問題が該当する場合、Android Studio のバージョン カタログ ファイルと [Project Structure Dialog] に lint 警告が表示されます。

  • SDK が作成者によって古いとマークされている。
  • SDK が Google Play のポリシーに違反している。
  • SDK に既知のセキュリティの脆弱性がある。
  • SDK が作成者によって非推奨になっている。

古いバージョンを使用すると Google Play Console に今後公開できなくなる可能性があるため、こうした警告は該当する依存関係を更新するためのシグナルになります。

バージョン カタログを使用せずにビルド依存関係を追加する

依存関係の追加と管理にはバージョン カタログを使用することをおすすめしますが、シンプルな プロジェクトでは必要ない場合があります。バージョン カタログを使用しないビルドファイルの例を次に示します:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

このビルドファイルは、「com.example.android」名前空間グループ内に存在するバージョン 12.3 の「app-magic」 ライブラリへの依存関係を宣言しています。リモート バイナリ 依存関係の宣言は、次の省略形です。

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

ビルドファイルは、「mylibrary」という名前の Android ライブラリ モジュールへの依存関係も宣言しています。この名前は、settings.gradle.kts ファイルの include: で定義されているライブラリ名と一致する必要があります。アプリをビルドすると、ビルドシステムは ライブラリ モジュールをコンパイルし、コンパイルされたコンテンツを アプリにパッケージ化します。

ビルドファイルは、Android Gradle プラグイン （com.application.android）への依存関係も宣言します。同じ プラグインを使用するモジュールが複数ある場合は、すべてのモジュールでビルド クラスパス にプラグインの単一バージョンのみを含めることができます。各モジュール ビルドスクリプトでバージョンを指定するのではなく、バージョンを含むプラグイン依存関係をルート ビルドスクリプト に含めて、適用しないように指定する必要があります。apply false を追加すると、 Gradle はプラグインのバージョンをメモしますが、ルートビルドでは使用しません。 通常、ルート ビルドスクリプトは、この plugins ブロックを除いて空です。

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

単一モジュール プロジェクトの場合は、モジュール レベルのビルドスクリプトでバージョンを明示的に指定し プロジェクト レベルのビルドスクリプトを空のままにできます。

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}