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 utama AGP.

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

AGP 10.0 (akhir tahun 2026)

Perubahan dan modernisasi API Plugin Android Gradle 10.0

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

Mengapa model build lambat?

Dalam model build non-lazy lama, Gradle mengevaluasi objek, mengkueri data varian, dan mengonfigurasi tugas di semua modul project dengan cepat selama setiap sinkronisasi atau pemanggilan build. Evaluasi langsung ini membuang-buang 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 pengaitan tugas dihitung secara lambat sesuai permintaan hanya saat diperlukan oleh grafik eksekusi build aktif.

API lama yang dihapus dalam rilis ini pada dasarnya tidak kompatibel dengan arsitektur modern ini. Menghapusnya memungkinkan AGP mendukung sepenuhnya 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 {}) bersifat antusias dan berfokus pada tugas. Hal ini memberi developer akses langsung ke tugas Gradle dan konfigurasi internal selama fase konfigurasi, yang secara inheren merusak fitur performa Gradle modern.

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

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, lakukan migrasi dari API dan flag yang tidak digunakan lagi berikut:

API atau fitur yang dihapus Perlu diganti atau tindakan diperlukan
Akses tugas langsung:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 Artifacts API: Daripada mengambil tugas untuk mengubah perilakunya, gunakan variant.artifacts untuk menambahkan, mengubah, atau mengganti file sebenarnya (Artefak) yang diteruskan di antara tugas.
Pendaftaran sumber yang aktif:
  • 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 ingin segera:
  • buildConfigField()
  • resValue()
 Instance `MapProperty` yang dimuat lambat: Gunakan variant.buildConfigFields.put(...) dan variant.manifestPlaceholders.put(...).
Flag penolakan:
  • android.newDsl
  • android.builtInKotlin
 Tidak ada pengganti langsung. Hapus tanda ini dari gradle.properties; DSL modern dan Kotlin bawaan diterapkan secara ketat.
Ekstensi Legacy Variant API:
  • 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
 Memigrasikan 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 Mengganti 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 Anda ke AGP 10.0 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). Asisten ini mengotomatiskan beberapa migrasi DSL dan skrip build umum serta membantu mempertahankan perilaku build yang ada.
  2. Menggunakan kemampuan Agent Mode di Android Studio: Manfaatkan kemampuan upgrade AI (seperti kemampuan upgrade AGP yang tersedia di repositori kemampuan Android) untuk mengotomatiskan dan menyederhanakan migrasi logika build dan DSL yang kompleks di dalam Android Studio.
  3. Perbaiki peringatan penghentian penggunaan di AGP 9.x terlebih dahulu: Upgrade project Anda ke rilis AGP 9.x terbaru dan selesaikan semua peringatan penghentian penggunaan yang ada. Setelah project Anda berfungsi dengan 9.x tanpa peringatan dan tanpa mengandalkan 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 perbandingan sebelum dan sesudah yang menunjukkan cara bermigrasi dari kueri varian lama yang dilakukan secara langsung ke konfigurasi varian yang dilakukan secara lambat menggunakan androidComponents {}:

Sebelum: Legacy Variant API (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: Modern Variant API (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 berjalan di rilis AGP 9.x, Anda dapat secara eksplisit menerapkan perilaku AGP 10.0 dengan memverifikasi bahwa gradle.properties menonaktifkan semua penonaktifan 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 Anda sepenuhnya kompatibel dengan persyaratan API ketat AGP 10.0.

Tidak ikut serta sub-project tertentu selama migrasi

Jika Anda 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 memilih untuk tidak menggunakan modul tertentu 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 Anda 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 kendala saat bermigrasi dari API lama dan Variant API baru tidak dapat mengakomodasi kasus penggunaan Anda, ikuti langkah-langkah berikut untuk memberikan masukan:

  1. Periksa item yang ada: Pertama, periksa Bug Pelacakan Global API Varian AGP 10.0 untuk melihat apakah penghalang migrasi Anda sudah diketahui, lalu beri +1 pada masalah tersebut.
  2. Laporkan API yang tidak ada: Jika kasus penggunaan Anda unik, ajukan permintaan fitur baru menggunakan template Variant API 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 versi 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 kini stabil dan berada 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 sebaiknya jangan menggunakannya karena dapat berubah dengan cara yang dapat menyebabkan gangguan kapan saja.