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

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

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

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

ネイティブ依存関係の追加と管理に関するガイダンス(一般的ではありません)については、ネイティブ依存関係をご覧ください。

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

  1. バージョン カタログ ファイルの [versions] セクション(Project ビューの gradle ディレクトリ、または [Android] ビューの Gradle Scripts)に、libs.versions.toml という依存関係のバージョン エイリアスを追加します。

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

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

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

    [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" }
    

    一部のライブラリは、ライブラリのファミリーとそのバージョンをグループ化した、発行済みの部品構成表(BOM)に含まれています。バージョン カタログとビルドファイルに BOM を含めると、それらのバージョンが自動的に管理されます。詳しくは、部品構成表の使用をご覧ください。

  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 ブロック内では、さまざまな依存関係コンフィグレーション(前述の implementation など)のいずれかを使用して、ライブラリ依存関係を宣言できます。それぞれの依存関係構成は、依存関係の使用方法についてのさまざまな指示を Gradle に与えます。次の表に、Android プロジェクト内で依存関係に使用できる各構成を示します。

設定 動作
implementation Gradle は依存関係をコンパイル クラスパスに追加し、また依存関係をビルド出力にパッケージ化します。モジュールで implementation 依存関係を設定すると、コンパイル時にその依存関係が他のモジュールにリークされないように Gradle が認識されます。つまり、現在のモジュールに依存する他のモジュールで依存関係を使用することはできません。

api の代わりにこの依存関係コンフィグレーションを使用すると、ビルドシステムで再コンパイルが必要となるモジュールの数が減るため、ビルド時間が大幅に短縮されます。たとえば、implementation 依存関係の API が変更された場合、Gradle はその依存関係とそれに直接依存するモジュールのみを再コンパイルします。ほとんどのアプリとテスト モジュールでは、この構成を使用する必要があります。

api Gradle は依存関係をコンパイル クラスパスとビルド出力に追加します。モジュールに api 依存関係が含まれている場合、Gradle はその依存関係を他のモジュールに推移的にエクスポートし、実行時とコンパイル時の両方で利用できるようにします。

この構成は、他のアップストリーム コンシューマに推移的にエクスポートする必要がある依存関係がある場合にのみ、慎重に使用してください。api 依存関係の外部 API が変更されると、Gradle はコンパイル時にその依存関係にアクセスできるすべてのモジュールを再コンパイルします。api 依存関係が多数存在すると、ビルド時間が大幅に長くなる可能性があります。依存関係の API を別のモジュールに公開しない場合以外は、ライブラリ モジュールでは代わりに implementation 依存関係を使用する必要があります。

compileOnly Gradle は依存関係をコンパイル クラスパスのみに追加します(つまり、ビルド出力には追加されません)。これは、Android モジュールを作成しており、コンパイル時には依存関係が必要であるものの、実行時にはなくても構わない場合に役立ちます。たとえば、コンパイル時のアノテーションのみを含むライブラリに依存している場合(通常はコードの生成に使用されますが、ビルド出力には含まれない場合が多い)、そのライブラリを compileOnly としてマークできます。

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

注: Android Archive(AAR)依存関係には compileOnly 構成を使用できません。

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

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

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

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

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

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

ksp は Kotlin Symbol Processor であり、Kotlin コンパイラによって実行されます。

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

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

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

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

lintChecks

Android アプリ プロジェクトのビルド時に Gradle に実行させる lint チェックを含むライブラリを含めるには、このコンフィグレーションを使用します。

lint.jar ファイルを含む AAR は、その lint.jar ファイルで定義されたチェックを自動的に実行します。明示的な lintChecks 依存関係を追加する必要はありません。これにより、ライブラリと関連する lint チェックを単一の依存関係で定義し、コンシューマがライブラリを使用したときにチェックを実行できます。

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.5.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.5.1'
}

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

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

依存関係の順序

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

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

  • LIB_A への依存関係と LIB_B への依存関係(この順序)
  • LIB_ALIB_CLIB_D に依存(この順序)
  • LIB_BLIB_C に依存

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

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

これにより、LIB_ALIB_B はいずれも LIB_C より優先され、LIB_DLIB_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 分析情報

Android Studio では、以下の問題に該当する場合、バージョン カタログ ファイルと Google Play SDK Index 内の公開 SDK の [Project Structure] ダイアログに lint 警告が表示されます。

  • SDK は作成者によって古いものとしてマークされています。
  • SDK が Google Play ポリシーに違反しています。

古いバージョンを使用すると 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」名前空間グループ内で、「app-magic」ライブラリのバージョン 12.3 への依存関係を宣言しています。リモート バイナリの依存関係宣言は、次の省略形です。

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)も宣言します。同じプラグインを使用する複数のモジュールがある場合、すべてのモジュールにわたって、ビルド クラスパスに含めることができるプラグインのバージョンは 1 つだけです。各モジュール ビルド スクリプトでバージョンを指定するのではなく、プラグインの依存関係をバージョンとともにルート ビルド スクリプトに含め、適用しないよう指示する必要があります。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'
}