Menambahkan dependensi build

Sistem build Gradle di Android Studio memungkinkan Anda menyertakan biner atau modul library lainnya ke build Anda sebagai dependensi. Dependensi dapat ditemukan di komputer Anda atau di repositori jarak jauh, dan setiap dependensi transitif yang dideklarasikan akan otomatis disertakan. Halaman ini menjelaskan cara menggunakan dependensi dengan project Android Anda, termasuk tentang perilaku dan konfigurasi yang spesifik untuk plugin Android Gradle (AGP). Untuk panduan konseptual yang lebih mendalam tentang dependensi Gradle, sebaiknya Anda juga membaca Panduan Gradle untuk pengelolaan dependensi, tetapi ingat bahwa project Android Anda hanya boleh menggunakan konfigurasi dependensi yang ditentukan pada halaman ini.

Perhatian: Saat menetapkan dependensi, Anda tidak boleh menggunakan nomor versi dinamis, seperti 'com.android.tools.build:gradle:3.+'. Menggunakan fitur ini dapat menyebabkan update versi yang tidak terduga, kesulitan menyelesaikan perbedaan versi, dan performa buruk.

Menambahkan library atau dependensi plugin

Cara terbaik untuk menambahkan dan mengelola dependensi build adalah dengan menggunakan katalog versi, metode yang digunakan proyek baru secara {i>default<i}. Bagian ini membahas hal-hal yang paling umum jenis konfigurasi yang digunakan untuk project Android; lihat Dokumentasi Gradle untuk opsi lainnya. Untuk contoh aplikasi yang menggunakan katalog versi, lihat Kini di Android. Jika Anda telah menyiapkan dependensi build tanpa katalog versi dan memiliki project multi-modul, sebaiknya bermigrasi.

Untuk panduan menambahkan dan mengelola dependensi native (tidak umum), lihat Dependensi native.

Pada contoh berikut, kami menambahkan biner jarak jauh dependensi (Jetpack Macrobenchmark library), modul library lokal dependensi (myLibrary), dan plugin (plugin Android Gradle) ke project kita. Berikut adalah langkah-langkah untuk menambahkan dependensi ini ke project Anda:

Catatan: Anda dapat mendeklarasikan katalog versi di setelan file, tetapi sebaiknya gunakan file toml terpisah untuk mendapatkan dukungan lebih lanjut terkait kode saran dan sorotan dari Android Studio.

1. Tambahkan alias untuk versi dependensi yang Anda inginkan dalam Bagian [versions] di file katalog versi, yang disebut libs.versions.toml (pada direktori gradle di Tampilan Project atau Gradle Scripts di tampilan Android):

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

   Alias dapat menyertakan tanda hubung atau garis bawah. Alias ini menghasilkan nilai bertingkat yang dapat direferensikan dalam skrip build. Referensi dimulai dengan nama katalog, bagian libs dari libs.versions.toml. Kapan menggunakan satu katalog versi, sebaiknya pertahankan nilai default "libs".

2. Tambahkan alias untuk dependensi dalam [libraries] (untuk biner jarak jauh atau modul library lokal) atau [plugins] (untuk plugin) dari file 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" }
   

   Beberapa library tersedia dalam Bill of Materials (BOM) yang telah dipublikasikan yang kelompok library dan versinya. Anda dapat menyertakan BOM dalam katalog versi, dan file build, serta mengizinkannya mengelola versi tersebut untuk Anda. Lihat Menggunakan Bill of Materials untuk mengetahui detailnya.

3. Tambahkan referensi ke alias dependensi ke skrip build dari modul yang memerlukan dependensi. Konversi alias garis bawah dan tanda hubung menjadi titik-titik saat Anda mereferensikannya dari skrip build. Skrip build level modul kami akan terlihat seperti ini:

   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
   }
   

   Referensi plugin menyertakan plugins setelah nama katalog, dan referensi versi menyertakan versions setelah nama katalog (versi jarang digunakan; lihat Dependensi dengan nomor versi yang sama sebagai contoh referensi versi.) Galeri foto referensi tidak menyertakan penentu libraries, sehingga Anda tidak dapat menggunakan versions atau plugins di awal library alias.

Mengonfigurasi dependensi

Di dalam blok dependencies, Anda dapat mendeklarasikan dependensi library menggunakan satu dari beberapa konfigurasi dependensi yang berbeda (seperti implementation yang ditampilkan sebelumnya). Setiap konfigurasi dependensi memberikan petunjuk yang berbeda kepada Gradle tentang cara menggunakan dependensi. Tabel berikut menjelaskan setiap konfigurasi yang dapat Anda gunakan untuk dependensi di project Android Anda.

Konfigurasi	Perilaku
implementation	Gradle menambahkan dependensi ke classpath kompilasi dan memaketkan dependensi ke output build. Jika mengonfigurasi dependensi implementation, memberi tahu Gradle bahwa Anda tidak ingin modul membocorkan dependensi ke modul lain pada waktu kompilasi. Artinya, dependensi tidak tersedia untuk modul lain yang bergantung pada ruang lingkup modul ini. Menggunakan konfigurasi dependensi ini alih-alih api dapat menghasilkan peningkatan waktu build yang signifikan karena mengurangi jumlah modul yang dibutuhkan sistem build untuk dikompilasi ulang. Misalnya, jika implementation dependensi mengubah API-nya, Gradle hanya mengompilasi ulang dependensi itu dan modul yang bergantung langsung padanya. Sebagian besar aplikasi dan pengujian modul, sebaiknya gunakan konfigurasi ini.
api	Gradle menambahkan dependensi ke classpath kompilasi dan output build. Jika modul menyertakan dependensi api, memberi tahu Gradle bahwa modul ingin mengekspor secara transitif dependensi itu ke modul lain, sehingga tersedia untuk mereka di runtime dan waktu kompilasi. Gunakan konfigurasi ini dengan hati-hati dan hanya dengan dependensi yang Anda perlu mengekspor secara transitif ke konsumen upstream lainnya. Jika Dependensi api mengubah API eksternalnya, Gradle mengompilasi ulang semua modul yang memiliki akses ke dependensi tersebut saat kompilasi baik. Memiliki banyak dependensi api dapat meningkatkan waktu build secara signifikan. Kecuali jika Anda ingin mengekspos API dependensi ke modul terpisah, modul library harusnya menggunakan dependensi implementation.
compileOnly	Gradle menambahkan dependensi ke classpath kompilasi saja (artinya, tidak ditambahkan ke output build). Ini berguna saat Anda membuat modul Android dan memerlukan dependensi selama kompilasi, tetapi ketersediaannya opsional selama runtime. Sebagai misalnya, jika Anda bergantung pada library yang hanya menyertakan anotasi waktu kompilasi—yang biasanya digunakan untuk membuat kode tetapi sering kali tidak disertakan dalam output build—Anda dapat menandai library tersebut compileOnly. Jika Anda menggunakan konfigurasi ini, modul library harus menyertakan kondisi runtime untuk memeriksa ketersediaan dependensi, lalu mengubah perilakunya dengan lancar agar tetap dapat berfungsi jika tidak disediakan. Cara ini membantu mengurangi ukuran aplikasi akhir dengan tidak menambahkan dependensi sementara yang tidak begitu penting. Catatan: Anda tidak dapat menggunakan compileOnly khusus dengan dependensi Android Archive (AAR).
runtimeOnly	Gradle hanya menambahkan dependensi ke output build, untuk digunakan selama runtime. Artinya, ini tidak ditambahkan ke classpath kompilasi. Ini jarang digunakan di Android, tetapi biasanya digunakan di server aplikasi Anda untuk menyediakan implementasi logging. Sebagai contoh, library dapat menggunakan API logging yang tidak menyertakan terlepas dari implementasi layanan. Konsumen perpustakaan dapat menambahkannya sebagai Dependensi implementation dan menyertakan Dependensi runtimeOnly untuk logging aktual implementasi yang tepat untuk digunakan.
ksp kapt annotationProcessor	Konfigurasi ini menyediakan library yang memproses anotasi dan simbol lain dalam kode Anda sebelum dikompilasi. Mereka biasanya memvalidasi kode Anda atau membuat kode tambahan, mengurangi kode yang Anda tulis. Untuk menambahkan dependensi tersebut, Anda harus menambahkannya ke classpath pemroses anotasi menggunakan konfigurasi ksp, kapt, atau annotationProcessor. Dengan menggunakan meningkatkan performa build dengan memisahkan kompilasi classpath dari classpath pemroses anotasi. Jika Gradle menemukan pemroses anotasi pada classpath kompilasi, akan menonaktifkan pencegahan kompilasi, yang berdampak negatif pada waktu build (Gradle 5.0 dan yang lebih tinggi mengabaikan pemroses anotasi yang ditemukan dalam kompilasi {i>classpath<i}). Android Gradle Plugin mengasumsikan dependensi adalah pemroses anotasi jika file JAR-nya berisi file berikut: META-INF/services/javax.annotation.processing.Processor Jika plugin mendeteksi pemroses anotasi yang ada pada classpath kompilasi, error build akan muncul. ksp adalah Pemroses Simbol Kotlin, dan dijalankan oleh Compiler Kotlin. kapt dan apt adalah alat terpisah yang anotasi proses sebelum compiler Kotlin atau Java dieksekusi. Saat memutuskan konfigurasi mana yang akan digunakan, pertimbangkan berikut ini: Jika prosesor tersedia sebagai Pemroses Simbol Kotlin, gunakan sebagai dependensi ksp. Lihat Bermigrasi dari kapt ke ksp untuk mengetahui detail tentang cara menggunakan Prosesor Simbol Kotlin. Jika prosesor tidak tersedia sebagai Prosesor Simbol Kotlin: Jika project Anda menyertakan sumber Kotlin (tetapi juga dapat termasuk sumber Java), gunakan kapt untuk menyertakannya. Jika project Anda hanya menggunakan sumber Java, gunakan annotationProcessor untuk menyertakannya. Untuk informasi lebih lanjut tentang cara menggunakan pemroses anotasi, lihat Menambahkan pemroses anotasi.
lintChecks	Gunakan konfigurasi ini untuk menyertakan library yang berisi lint pemeriksaan yang Anda inginkan untuk dijalankan Gradle saat membangun aplikasi Android proyek. Perhatikan bahwa AAR yang berisi file lint.jar akan secara otomatis menjalankan pemeriksaan yang ditentukan dalam file lint.jar tersebut; Anda tidak perlu menambahkan dependensi lintChecks eksplisit. Ini memungkinkan Anda mendefinisikan library dan pemeriksaan lint terkait dalam satu dependensi, memastikan bahwa pemeriksaan Anda berjalan saat konsumen menggunakan library.
lintPublish	Gunakan konfigurasi ini di project library Android untuk menyertakan pemeriksaan lint yang perlu dikompilasi Gradle ke dalam paket dan file lint.jar di AAR Anda. Dengan demikian, project yang menggunakan AAR Anda juga menerapkan pemeriksaan lint tersebut. Jika sebelumnya Anda menggunakan konfigurasi dependensi lintChecks untuk menyertakan pemeriksaan lint dalam AAR yang dipublikasikan, Anda perlu memigrasikan dependensi tersebut agar menggunakan konfigurasi 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') }

Mengonfigurasi dependensi untuk varian build tertentu

Semua konfigurasi sebelumnya menerapkan dependensi ke semua varian build. Jika Anda ingin mendeklarasikan dependensi hanya untuk build tertentu set sumber varian atau untuk sumber pengujian tetapkan, Anda harus menggunakan huruf besar untuk konfigurasi dan berikan awalan dengan nama varian build atau set sumber pengujian.

Misalnya, untuk menambahkan dependensi biner jarak jauh hanya ke dependensi "free" produk menggunakan konfigurasi implementation, gunakan ini:

Kotlin

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

Groovy

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

Namun, jika Anda ingin menambahkan dependensi untuk varian yang menggabungkan produk dan jenis build, maka Anda harus menginisialisasi nama konfigurasi:

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

Untuk menambahkan dependensi implementation bagi pengujian lokal dan pengujian berinstrumen, caranya adalah seperti berikut:

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'
}

Namun, konfigurasi tertentu tidak cocok dengan situasi ini. Misalnya, karena modul lain tidak dapat bergantung pada androidTest, Anda akan mendapatkan peringatan berikut jika menggunakan konfigurasi androidTestApi:

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

Urutan dependensi

Urutan pencantuman dependensi menunjukkan prioritas untuk setiap dependensi: library pertama memiliki prioritas lebih tinggi daripada library kedua, library kedua memiliki prioritas lebih tinggi daripada library ketiga, dan seterusnya. Urutan ini penting jika resource digabungkan atau elemen manifes digabungkan ke dalam aplikasi Anda dari library.

Misalnya, jika project Anda mendeklarasikan dependensi berikut:

• Dependensi pada LIB_A dan LIB_B (dalam urutan tersebut)
• Dan LIB_A bergantung pada LIB_C dan LIB_D (dalam urutan tersebut)
• Serta LIB_B juga bergantung pada LIB_C

Urutan dependensi rata akan menjadi seperti berikut:

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

Ini memastikan bahwa baik LIB_A maupun LIB_B dapat menggantikan LIB_C; dan LIB_D masih lebih tinggi prioritasnya daripada LIB_B karena LIB_A (yang bergantung padanya) memiliki prioritas lebih tinggi daripada LIB_B.

Untuk mengetahui informasi selengkapnya tentang penggabungan manifes dari sumber/dependensi project yang berbeda, baca Menggabungkan beberapa file manifes.

Informasi dependensi untuk Konsol Play

Saat membangun aplikasi, AGP menyertakan metadata yang menjelaskan library dependensi yang dikompilasi ke dalam aplikasi Anda. Saat mengupload aplikasi Anda, Play Store Konsol memeriksa metadata guna memberikan pemberitahuan untuk masalah umum pada SDK dan dependensi yang digunakan aplikasi Anda, dan, dalam beberapa kasus, memberikan masukan yang dapat ditindaklanjuti untuk menyelesaikan masalah tersebut.

Data dikompresi, dienkripsi oleh kunci penandatanganan Google Play, dan disimpan di blok penandatanganan aplikasi rilis Anda. Sebaiknya pertahankan dependensi ini untuk menciptakan pengalaman pengguna yang aman dan positif. Anda dapat memilih tidak ikut dengan menyertakan mengikuti dependenciesInfo di file build.gradle.kts modul Anda.

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

Untuk informasi lengkap kebijakan kami dan potensi masalah dengan dependensi, lihat halaman dukungan kami tentang menggunakan SDK pihak ketiga di aplikasi Anda.

Insight SDK

Android Studio menampilkan peringatan lint dalam file katalog versi dan Project Dialog Struktur untuk SDK publik di Google Play SDK Index jika masalah berikut terjadi:

• SDK ditandai sebagai usang oleh penulisnya.
• SDK melanggar kebijakan Play.

Peringatan merupakan sinyal bahwa Anda harus memperbarui dependensi tersebut, karena menggunakan versi yang sudah usang dapat mencegah Anda memublikasikan ke Google Play Konsol di masa mendatang.

Menambahkan dependensi build tanpa katalog versi

Sebaiknya gunakan katalog versi untuk menambahkan dan mengelola dependensi, tetapi hal ini sederhana proyek mungkin tidak membutuhkannya. Berikut contoh file build yang tidak menggunakan katalog versi:

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')
}

File build ini mendeklarasikan dependensi pada "app-magic" versi 12.3 library, di dalam "com.example.android" grup namespace. Biner jarak jauh deklarasi dependensi adalah singkatan untuk hal-hal berikut:

Kotlin

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

Groovy

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

File build juga mendeklarasikan dependensi pada modul library Android bernama "mylibrary"; nama ini harus cocok dengan nama library yang ditentukan dengan include: di file settings.gradle.kts Anda. Saat Anda membangun aplikasi, sistem build mengompilasi modul {i>library<i} dan memaketkan konten terkompilasi yang dihasilkan ke dalam .

File build juga mendeklarasikan dependensi pada plugin Android Gradle (com.application.android). Jika Anda memiliki beberapa modul yang menggunakan , Anda hanya bisa memiliki satu versi plugin pada classpath build di semua modul. Daripada menetapkan versi di setiap modul, Anda harus menyertakan dependensi plugin dalam skrip build root dengan versi, dan menunjukkan untuk tidak menerapkannya. Menambahkan apply false memberi tahu Gradle untuk mencatat versi plugin, tetapi tidak untuk menggunakannya dalam build root. Biasanya skrip build root kosong kecuali untuk blok plugins ini.

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
}

Jika memiliki project modul tunggal, Anda dapat menentukan versi secara eksplisit di skrip build level modul dan biarkan skrip build level project kosong:

Kotlin

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

Groovy

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