Sistem build Gradle di Android Studio memungkinkan Anda menyertakan biner eksternal atau modul library lainnya ke build 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 detail 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.
Menambahkan library atau dependensi plugin
Cara terbaik untuk menambahkan dan mengelola dependensi build adalah dengan menggunakan katalog versi, metode yang digunakan project baru secara default. Bagian ini membahas jenis konfigurasi paling umum yang digunakan untuk project Android; lihat dokumentasi Gradle untuk opsi lainnya. Untuk contoh aplikasi yang menggunakan katalog versi, lihat Now in Android. Jika Anda sudah menyiapkan dependensi build tanpa katalog versi dan memiliki project multi-modul, sebaiknya migrasikan.
Untuk panduan tentang menambahkan dan mengelola dependensi native (tidak umum), lihat Dependensi native.
Pada contoh berikut, kita menambahkan dependensi biner
jarak jauh (library
Jetpack Macrobenchmark), dependensi modul library
lokal (myLibrary
), dan dependensi
plugin (plugin Android Gradle) ke project kita. Berikut adalah langkah-langkah umum untuk menambahkan dependensi ini ke project Anda:
Tambahkan alias untuk versi dependensi yang Anda inginkan di bagian
[versions]
file katalog versi, yang disebutlibs.versions.toml
(pada direktorigradle
dalam tampilan Project atau Skrip Gradle dalam 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 Anda referensikan dalam skrip build. Referensi dimulai dengan nama katalog, bagian
libs
darilibs.versions.toml
. Saat menggunakan satu katalog versi, sebaiknya pertahankan nilai default "libs".Tambahkan alias untuk dependensi di bagian
[libraries]
(untuk biner jarak jauh atau modul library lokal) atau[plugins]
(untuk plugin) di filelibs.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 di Bill of Materials (BOM) yang dipublikasikan yang mengelompokkan kelompok library dan versinya. Anda dapat menyertakan BOM dalam katalog versi dan file build, serta membiarkannya mengelola versi tersebut untuk Anda. Lihat Menggunakan Bill of Materials untuk detailnya.
Tambahkan referensi ke alias dependensi ke skrip build modul yang memerlukan dependensi. Konversikan garis bawah dan tanda hubung alias menjadi titik saat Anda mereferensikannya dari skrip build. Skrip build level modul kita 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 menyertakanversions
setelah nama katalog (referensi versi jarang digunakan; lihat Dependensi dengan nomor versi yang sama untuk mengetahui contoh referensi versi.) Referensi library tidak menyertakan penentulibraries
, sehingga Anda tidak dapat menggunakanversions
atauplugins
di awal alias library.
Mengonfigurasi dependensi
Dalam blok dependencies
, Anda dapat mendeklarasikan dependensi library menggunakan salah satu dari sejumlah 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. Saat mengonfigurasi dependensi implementation , modul akan memberi tahu Gradle bahwa Anda tidak ingin modul tersebut membocorkan dependensi ke modul lain pada waktu kompilasi. Artinya, dependensi
tidak tersedia untuk modul lain yang bergantung pada modul
saat ini.
Menggunakan konfigurasi dependensi ini dan bukan
|
api |
Gradle menambahkan dependensi ke classpath kompilasi dan output build. Jika menyertakan dependensi api , modul akan
memberi tahu Gradle bahwa modul tersebut ingin mengekspor
dependensi tersebut secara transitif ke modul lainnya agar tersedia untuk modul lain
selama runtime dan waktu kompilasi.
Gunakan konfigurasi ini dengan hati-hati dan hanya dengan dependensi yang
perlu Anda ekspor secara transitif ke konsumen upstream lainnya. Jika dependensi
|
compileOnly |
Gradle hanya menambahkan dependensi ke classpath kompilasi
(artinya, dependensi tidak ditambahkan ke output build). Ini berguna saat Anda membuat modul Android dan memerlukan dependensi selama kompilasi, tetapi ketersediaannya opsional selama runtime. 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 sebagai 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 konfigurasi |
runtimeOnly |
Gradle hanya menambahkan dependensi ke output build, untuk digunakan
selama runtime. Artinya, ini tidak ditambahkan ke classpath kompilasi.
Metode ini jarang digunakan di Android, tetapi biasanya digunakan di aplikasi
server untuk menyediakan implementasi logging. Misalnya,
library dapat menggunakan API logging yang tidak menyertakan
implementasi. Konsumen library tersebut dapat menambahkannya sebagai
dependensi implementation dan menyertakan
dependensi runtimeOnly untuk penerapan logging
aktual yang akan digunakan.
|
ksp |
Konfigurasi ini menyediakan library yang memproses anotasi dan simbol lain dalam kode Anda sebelum dikompilasi. Alat ini biasanya memvalidasi kode Anda atau membuat kode tambahan, sehingga mengurangi kode yang perlu Anda tulis. Untuk menambahkan dependensi tersebut, Anda harus menambahkannya ke classpath pemroses anotasi menggunakan konfigurasi Android Gradle Plugin mengasumsikan dependensi adalah pemroses anotasi jika file JAR-nya berisi file berikut:
Jika plugin mendeteksi pemroses anotasi yang ada pada classpath kompilasi, error build akan muncul.
Saat memutuskan konfigurasi yang akan digunakan, pertimbangkan hal-hal berikut:
Untuk informasi selengkapnya tentang penggunaan pemroses anotasi, lihat Menambahkan pemroses anotasi. |
lintChecks |
Gunakan konfigurasi ini untuk menyertakan library yang berisi pemeriksaan lint yang ingin dijalankan Gradle saat mem-build project aplikasi Android Anda. Perhatikan bahwa AAR yang berisi file |
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 .
Kotlindependencies { // 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")) } Groovydependencies { // 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 ingin mendeklarasikan dependensi hanya untuk set sumber varian build tertentu atau untuk set sumber pengujian, Anda harus membuat huruf besar untuk nama konfigurasi dan memberinya awalan dengan nama varian build atau set sumber pengujian.
Misalnya, untuk menambahkan dependensi biner jarak jauh hanya ke ragam produk "free" menggunakan konfigurasi implementation
, gunakan perintah 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 ingin menambahkan dependensi untuk varian yang menggabungkan ragam produk dan jenis build, Anda harus melakukan inisialisasi 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.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' }
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
danLIB_B
(dalam urutan tersebut) - Dan
LIB_A
bergantung padaLIB_C
danLIB_D
(dalam urutan tersebut) - Serta
LIB_B
juga bergantung padaLIB_C
Urutan dependensi rata akan menjadi seperti berikut:
LIB_A
LIB_D
LIB_B
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 mem-build aplikasi, AGP menyertakan metadata yang menjelaskan dependensi library yang dikompilasi ke dalam aplikasi Anda. Saat mengupload aplikasi, Konsol Play akan memeriksa metadata ini untuk memberikan pemberitahuan tentang masalah umum terkait SDK dan dependensi yang digunakan aplikasi Anda, dan, dalam beberapa kasus, memberikan masukan yang bisa ditindaklanjuti untuk menyelesaikan masalah tersebut.
Data dikompresi, dienkripsi oleh kunci penandatanganan Google Play, dan disimpan di
blok penandatanganan aplikasi rilis Anda. Sebaiknya simpan file dependensi ini
untuk pengalaman pengguna yang aman dan positif. Anda dapat memilih tidak ikut dengan menyertakan
blok
dependenciesInfo
berikut dalam 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 Dialog Struktur Project untuk SDK publik di Google Play SDK Index jika terjadi masalah berikut:
- SDK ditandai sebagai usang oleh penulisnya.
- SDK melanggar kebijakan Play.
Peringatan ini merupakan sinyal bahwa Anda harus memperbarui dependensi tersebut, karena menggunakan versi yang sudah tidak berlaku dapat mencegah Anda memublikasikan ke Konsol Google Play pada masa mendatang.
Menambahkan dependensi build tanpa katalog versi
Sebaiknya gunakan katalog versi untuk menambahkan dan mengelola dependensi, tetapi project sederhana mungkin tidak memerlukannya. Berikut adalah 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 library "app-magic" versi 12.3, di dalam grup namespace "com.example.android". Deklarasi dependensi biner jarak jauh adalah singkatan untuk 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:
dalam
file settings.gradle.kts
. Saat Anda mem-build aplikasi, sistem build
akan mengompilasi modul library dan memaketkan konten terkompilasi yang dihasilkannya ke dalam
aplikasi.
File build juga mendeklarasikan dependensi pada plugin Android Gradle
(com.application.android
). Jika memiliki beberapa modul yang menggunakan plugin
yang sama, Anda hanya dapat memiliki satu versi plugin pada classpath build
di semua modul. Daripada menentukan versi di setiap skrip build
modul, Anda harus menyertakan dependensi plugin dalam skrip build root
dengan versi, dan menunjukkan untuk tidak menerapkannya. Menambahkan apply false
akan memberi tahu
Gradle untuk mencatat versi plugin, tetapi tidak 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 satu modul, Anda dapat menentukan versi secara eksplisit dalam skrip build level modul dan membiarkan 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' }