Linimasa migrasi DSL/API Plugin Android Gradle

Plugin Android Gradle (AGP) adalah sistem build yang didukung untuk aplikasi Android dan mencakup dukungan untuk mengompilasi berbagai jenis sumber dan menautkannya ke dalam aplikasi yang dapat Anda jalankan pada perangkat Android fisik atau emulator.

Bagian berikut menjelaskan evolusi yang direncanakan dari DSL dan API AGP. Saat API baru diperkenalkan dalam rilis stabil, API lama akan ditandai sebagai tidak digunakan lagi. API yang tidak digunakan lagi tersebut selanjutnya akan menjadi tidak tersedia dalam rilis stabil berikutnya. Bagian berikut memberikan informasi tentang perubahan mendatang di setiap rilis AGP utama.

Untuk mengetahui log penghentian atau penghapusan API AGP yang lebih mendetail, lihat update API AGP.

AGP 10.0 (akhir 2026)

Perubahan dan modernisasi API Plugin Android Gradle 10.0

AGP 10.0 menyelesaikan transisi ke model build yang sepenuhnya lambat dan kompatibel dengan cache konfigurasi. Rilis ini adalah puncak dari upaya multi-tahun untuk mengganti API lama yang tidak lambat dengan arsitektur yang lebih aman dan berperforma lebih baik.

Mengapa model build lambat?

Dalam model build lama yang tidak lambat, Gradle mengevaluasi objek, mengkueri data varian, dan mengonfigurasi tugas di semua modul project selama setiap sinkronisasi atau pemanggilan build. Evaluasi yang tidak sabar ini membuang waktu CPU dan memori pada varian dan tugas yang tidak berjalan, serta menyebabkan konflik pengurutan evaluasi di seluruh skrip build yang kompleks.

Dengan beralih ke model build yang sepenuhnya lambat menggunakan penyedia lambat (Provider<T>) dan Variant API modern (androidComponents {}), properti dan koneksi tugas dihitung secara lambat sesuai permintaan hanya jika diperlukan oleh grafik eksekusi build aktif.

API lama yang dihapus dalam rilis ini pada dasarnya tidak kompatibel dengan arsitektur modern ini. Dengan menghapusnya, AGP dapat sepenuhnya mendukung Gradle Configuration Cache dan Project Isolation, yang secara drastis meningkatkan kecepatan build dan waktu sinkronisasi di Android Studio.

Perbedaan arsitektur inti

BaseVariant API lama (applicationVariants.all {}) tidak sabar dan berpusat pada tugas. API ini memberi developer akses langsung ke tugas Gradle dan konfigurasi internal selama fase konfigurasi, yang secara inheren melanggar fitur performa Gradle modern.

Variant API baru (androidComponents {}) lambat dan berpusat pada artefak. API ini menggunakan Property API Gradle secara ekstensif dan sepenuhnya menghapus semua referensi ke Task dan TaskProvider, sehingga Anda harus berinteraksi dengan bersih dengan input dan output (Variant.artifacts), bukan tugas yang mendasarinya.

Apa yang dihapus dan diganti

Semua antarmuka dan class sebelumnya yang digunakan di DSL lama dan Variant API lama dihapus. Untuk menyiapkan skrip build dan plugin kustom, migrasikan dari API dan flag akhir masa pakai berikut:

API atau fitur yang dihapus Penggantian atau tindakan yang diperlukan
Akses tugas langsung:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API: Daripada mengambil tugas untuk mengubah perilakunya, gunakan variant.artifacts untuk menambahkan, mengubah, atau mengganti file aktual (Artefak) yang diteruskan antar-tugas.
Pendaftaran sumber yang tidak sabar:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 Sources API: Hubungkan direktori output tugas kustom Anda menggunakan variant.sources.java.addGeneratedSourceDirectory(...).
Akses classpath / konfigurasi:
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API: Untuk mengubah atau memeriksa bytecode (kasus penggunaan paling umum untuk akses classpath), gunakan variant.instrumentation.transformClassesWith(...) menggunakan AsmClassVisitorFactory.
Mutasi properti yang tidak sabar:
  • buildConfigField()
  • resValue()
 Instance `MapProperty` lambat: Gunakan variant.buildConfigFields.put(...) dan variant.manifestPlaceholders.put(...).
Flag tidak ikut serta:
  • android.newDsl
  • android.builtInKotlin
 Tidak ada penggantian langsung. Hapus flag ini dari gradle.properties; DSL modern dan Kotlin bawaan diterapkan secara ketat.
Ekstensi Variant API lama:
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 Ganti dengan androidComponents.onVariants().
Pemfilteran varian (blok variantFilter) Ganti dengan androidComponents.beforeVariants() menggunakan pemilih varian.
Komponen SDK dan NDK:
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 Akses komponen SDK menggunakan androidComponents.sdkComponents.
Lingkungan pengujian:
  • deviceProvider
  • testServer
 Migrasikan pendaftaran perangkat pengujian kustom ke perangkat yang dikelola Gradle.
API pendaftaran yang tidak digunakan lagi:
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 Dihapus tanpa penggantian langsung.
Transform API Ganti transformasi dengan Artifacts API dan AsmClassVisitorFactory.

Untuk mengakses semua antarmuka dan class DSL dan Variant API (androidComponents {}) pengganti, selalu gunakan artefak gradle-api saat mengembangkan plugin Gradle kustom atau logika build.

Langkah-langkah migrasi

Untuk membantu membuat upgrade ke AGP 10.0 menjadi lancar dan dapat diprediksi, ikuti praktik migrasi berikut:

  1. Jalankan Asisten Upgrade AGP: Sebelum mengupgrade langsung ke 10.0, jalankan Asisten Upgrade AGP resmi di Android Studio (Tools > AGP Upgrade Assistant). Alat ini mengotomatiskan beberapa migrasi DSL dan skrip build umum serta membantu mempertahankan perilaku build yang ada.
  2. Gunakan keterampilan Mode Agen di Android Studio: Manfaatkan keterampilan upgrade AI (seperti keterampilan upgrade AGP yang tersedia di repositori keterampilan Android) untuk mengotomatiskan dan menyederhanakan migrasi logika build dan DSL yang kompleks di dalam Android Studio.
  3. Perbaiki peringatan penghentian di AGP 9.x terlebih dahulu: Upgrade project Anda ke rilis AGP 9.x terbaru dan selesaikan semua peringatan penghentian yang ada. Setelah project Anda berfungsi dengan 9.x tanpa peringatan dan tanpa bergantung pada android.newDsl=false atau android.builtInKotlin=false, transisi ke 10.0 akan berjalan lancar.
  4. Audit plugin Gradle pihak ketiga: Pastikan plugin pihak ketiga diupgrade ke versi yang kompatibel dengan AGP 10.0. Plugin yang masih mengandalkan jenis ekstensi lama akan menyebabkan kegagalan build seperti ClassCastException: ... cannot be cast to class BaseExtension.
  5. Gunakan resep migrasi resmi: Untuk contoh migrasi dunia nyata yang kompleks dan perbandingan berdampingan, lihat repositori GitHub gradle-recipes resmi.

Berikut adalah perbandingan sebelum dan sesudah yang menunjukkan cara bermigrasi dari kueri varian lama yang tidak sabar ke konfigurasi varian yang lambat menggunakan androidComponents {}:

Sebelum: Variant API Lama (Dihapus di AGP 10.0)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

Setelah: Variant API Modern (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

Cara menguji perilaku AGP 10.0 di AGP 9.x

Anda tidak perlu menunggu rilis AGP 10.0 untuk mulai menguji perilaku build dan memvalidasi kompatibilitasnya. Saat menjalankan rilis AGP 9.x, Anda dapat secara eksplisit menerapkan perilaku AGP 10.0 dengan memverifikasi bahwa gradle.properties Anda menonaktifkan semua tidak ikut serta dan menetapkan flag perilaku ketat berikut:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

Dengan menerapkan android.newDsl=true dan android.builtInKotlin=true, Anda dapat memverifikasi bahwa logika build kustom dan plugin pihak ketiga sepenuhnya kompatibel dengan persyaratan API ketat AGP 10.0.

Tidak ikut serta sub-project selektif selama migrasi

Jika ingin mengaktifkan android.newDsl=true secara global di seluruh project untuk menguji perilaku modern, tetapi memerlukan lebih banyak waktu untuk memigrasikan sub-project tertentu, Anda dapat secara selektif tidak ikut serta modul individual mulai dari AGP 9.4.0-alpha04. Tambahkan android.newDsl.optOut ke gradle.properties yang menentukan jalur project:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Penonaktifan Kotlin bawaan selektif per modul

Jika ingin mengaktifkan Kotlin bawaan secara global di seluruh project (android.builtInKotlin=true), tetapi memerlukan lebih banyak waktu untuk memigrasikan sub-project tertentu dari kotlin-android (atau untuk modul tanpa kode Kotlin), konfigurasi modul tersebut di tingkat DSL, bukan tingkat project. Tetapkan enableKotlin = false di dalam file build modul:

android {
    enableKotlin = false
}

Alur kerja pelaporan bug dan masukan

Kami ingin memastikan Variant API baru mendukung kasus penggunaan yang Anda perlukan. Jika Anda mengalami hambatan saat bermigrasi dari API lama yang tidak dapat mengakomodasi kasus penggunaan Anda, ikuti langkah-langkah berikut untuk memberikan masukan:

  1. Periksa item yang ada: Pertama, periksa Bug Pelacakan Global Variant API AGP 10.0 untuk melihat apakah pemblokir migrasi Anda sudah diketahui, dan +1 masalah tersebut.
  2. Laporkan API yang tidak ada: Jika kasus penggunaan Anda unik, ajukan permintaan fitur baru menggunakan template AGP 10.0 khusus kami agar kami dapat menyelidiki dan membantu.

(Tentatif) Akses ke class AGP internal pribadi dihapus

Dependensi pada artefak gradle sekarang menyembunyikan semua class internal dan memberikan akses kompilasi hanya ke antarmuka dan class yang tersedia di artefak gradle-api. Hal ini memengaruhi kompilasi plugin.

Tidak memungkinkan bagi Anda untuk menambahkan dependensi secara manual untuk mendapatkan akses ke class internal.

AGP 9.0 (Januari 2026)

Variant API baru stabil, API lama tidak digunakan lagi

Variant API yang diinkubasi di 4.1 dan 4.2 bersifat stabil dan terletak di artefak gradle-api. Antarmuka dan class sebelumnya yang digunakan di Variant API lama kini tidak digunakan lagi, dan memerlukan keikutsertaan eksplisit untuk digunakan.

Antarmuka DSL baru sudah stabil, antarmuka versi lama tidak digunakan lagi

Antarmuka DSL yang diinkubasi di 4.1, 4.2, dan 7.0 sekarang stabil dan terletak di artefak gradle-api. Antarmuka dan class sebelumnya yang digunakan dalam DSL kini tidak digunakan lagi, dan memerlukan keikutsertaan eksplisit untuk digunakan.

Class AGP internal pribadi masih dapat diakses

Class internal pribadi dari AGP, yang berada di artefak lain, masih dapat diakses selama kompilasi file build dan plugin berlangsung, tetapi kami tidak merekomendasikan untuk menggunakannya karena dapat berubah dengan cara yang dapat menyebabkan gangguan kapan saja.