Upgrade Assistant plugin Android Gradle (AGP) adalah alat di Android Studio yang membantu Anda mengupgrade versi AGP yang digunakan oleh project Anda.
Ada banyak rilis untuk perubahan AGP yang terkait dengan fitur baru untuk mengonfigurasi build Anda, API baru untuk digunakan oleh plugin Gradle lainnya, dan perbaikan untuk integrasi build project dengan Android Studio. Dengan mengupgrade versi AGP yang digunakan oleh project, Anda dapat memanfaatkan fitur-fitur terbaru.
Untuk mengetahui informasi selengkapnya tentang struktur project yang direkomendasikan bagi Upgrade Assistant, lihat Penyiapan di halaman ini.
Kasus penggunaan Upgrade Assistant AGP
Upgrade Assistant AGP memandu Anda dalam melakukan perubahan yang diperlukan untuk mengupgrade versi AGP. Berikut adalah kasus penggunaan paling umum untuk Upgrade Assistant:
Perubahan sintaksis: Upgrade Assistant mencoba menerjemahkan file build AGP versi lama ke file build yang diperlukan untuk AGP versi lebih baru. Saat AGP dikembangkan, file build diupdate untuk mendukung antarmuka karena sudah diganti, tidak digunakan lagi, atau tidak didukung seiring waktu.
Persyaratan kompatibilitas antara AGP dan Gradle: Upgrade Assistant mengetahui persyaratan kompatibilitas antara AGP dan Gradle, dan membantu memastikan bahwa Anda menggunakan versi Gradle yang diperlukan untuk versi AGP Anda.
Persyaratan kompatibilitas antara AGP dan plugin Gradle pihak ketiga: Upgrade Assistant mengetahui persyaratan kompatibilitas antara AGP dan beberapa plugin Gradle pihak ketiga, dan membantu memastikan bahwa Anda menggunakan versi plugin Gradle pihak ketiga yang diperlukan untuk versi AGP Anda.
Secara umum, Upgrade Assistant memudahkan Anda mengupdate file build dan memahami pesan error terkait setelah upgrade AGP. Upgrade Assistant juga menjelaskan alasan terjadinya perubahan yang diusulkan.
Cara menggunakan Upgrade Assistant AGP
Untuk menggunakan Upgrade Assistant, pastikan struktur project Anda mengakomodasi alat, lalu jalankan dari Android Studio, seperti yang dijelaskan dalam Menjalankan Upgrade Assistant.
Menyiapkan project
Sebelum menjalankan Upgrade Assistant, pastikan project Anda telah diformat dan dicadangkan dengan benar. Untuk memastikan Upgrade Assistant AGP disiapkan dengan benar, baca bagian berikut.
Membuat struktur project menggunakan file build Gradle dan bahasa khusus domain
Untuk mengoptimalkan penggunaan Upgrade Assistant AGP, lakukan hal berikut:
- Konfigurasi build menggunakan file build Gradle: Upgrade Assistant mengandalkan analisis statis file build Gradle. Untuk mengoptimalkan Upgrade Assistant, konfigurasikan build Anda menggunakan file build ini.
- Gunakan bahasa khusus domain build deklaratif: File build Gradle dinyatakan dalam Groovy atau Kotlin. Namun, makin deklaratif ekspresi konfigurasi project, makin besar kemungkinan Upgrade Assistant berhasil menemukan semua tempat yang perlu penyesuaian untuk upgrade.
Meskipun project sesuai dengan batasan ini, Upgrade Assistant mungkin masih gagal melakukan upgrade tanpa kendala. Lihat Memecahkan masalah error untuk mendapatkan panduan cara me-resolve atau melaporkan bug.
Mencadangkan project
Sebelum menggunakan Upgrade Assistant, sebaiknya project Anda tidak memiliki perubahan yang tidak di-commit seperti yang terlihat oleh sistem kontrol versi. Jika Anda tidak menggunakan kontrol versi, gunakan cadangan versi baik yang terakhir diketahui pada tahap ini.
Setelah Upgrade Assistant berjalan dan project berhasil dibuat serta diuji, Anda dapat meng-commit project versi baru ke sistem kontrol versi.
Menjalankan Upgrade Assistant
Untuk menjalankan Upgrade Assistant, ikuti langkah-langkah berikut:
Untuk meluncurkan Upgrade Assistant, buka Tools > AGP Upgrade Assistant atau klik perintah notifikasi, seperti yang ditunjukkan pada gambar 1.
Jendela alat yang muncul menampilkan detail upgrade default termasuk versi AGP project saat ini dan versi terbaru yang didukung oleh versi Android Studio ini.
Gambar 1. Jendela alat Upgrade Assistant AGP saat diluncurkan dengan perintah notifikasi. Periksa langkah-langkah yang diperlukan dan direkomendasikan.
Di panel sebelah kiri, hierarki dengan kotak centang menguraikan setiap langkah dalam upgrade, yang dikategorikan berdasarkan apakah langkah tersebut diperlukan atau direkomendasikan untuk update dan apakah merupakan prasyarat dari langkah lain. Pilih satu per satu item dalam hierarki untuk menampilkan detail selengkapnya tentang setiap langkah di panel utama.
Untuk menjalankan upgrade, pilih langkah-langkah yang diperlukan dan diinginkan, lalu klik Run selected steps.
Upgrade Assistant mengubah file build project dan mencoba menyinkronkan build project baru dengan Android Studio. Proses ini mungkin memerlukan waktu jika Anda memiliki banyak modul, karena versi baru plugin dan library mungkin perlu didownload.
Tinjau laporan pasca-upgrade. Laporan ini menjelaskan langkah-langkah yang selesai dan jika upgrade berhasil atau gagal. Ini juga mencakup tindakan untuk mengembalikan perubahan yang dibuat oleh asisten upgrade jika ada masalah dalam mem-build atau menguji project setelah upgrade.
Setelah project berhasil disinkronkan dengan Android Studio, build project dan jalankan rangkaian pengujian untuk memverifikasi bahwa operasi upgrade tidak mengubah fungsi apa pun.
Setelah memverifikasi bahwa project Anda dalam kondisi baik, commit versi baru project ke sistem kontrol versi.
Memecahkan masalah error
Jika Upgrade Assistant menyarankan untuk mengupgrade, tetapi upgrade gagal, hal ini biasanya disebabkan oleh perubahan pada file build sehingga menyebabkan kegagalan sinkronisasi. Ikuti langkah-langkah berikut untuk membantu mengurangi dan memperbaiki error:
Pertama, periksa error yang menyebabkan kegagalan sinkronisasi. Terkadang, error memiliki penyebab yang jelas, yang dapat Anda tangani dalam file build project.
Jika pesan error tidak jelas, atau penyebab masalah tidak diketahui dengan jelas, tampilkan project ke status aslinya untuk membagi upgrade menjadi langkah yang lebih kecil. Pulihkan status asli dari kontrol versi atau dari cadangan, dan pastikan project dalam status aslinya dan disinkronkan dengan Android Studio.
Selidiki error dengan mengikuti dua jenis pengelompokan upgrade:
Upgrade ke versi AGP berbeda yang bukan versi terbaru. Jika upgrade yang salah adalah upgrade sejumlah besar versi, cara terbaik untuk mengatasi masalahnya adalah dengan melakukan serangkaian upgrade yang lebih kecil, dari setiap versi, untuk menemukan upgrade pertama yang memicu masalahnya.
Dalam upgrade, lakukan setiap langkah satu per satu. Setelah menentukan upgrade yang memicu masalah, Anda dapat menonaktifkan langkah-langkah tersebut saat upgrade. Jika memungkinkan, coba lakukan setiap langkah satu per satu untuk menemukan langkah mana yang menyebabkan error. Jika Anda tidak dapat menemukan langkah yang bermasalah, periksa catatan rilis plugin Gradle lain yang digunakan untuk masalah kompatibilitas dengan Gradle atau AGP. Terkadang, rilis baru menangani penggunaan API internal atau yang tidak digunakan lagi.
Laporkan bug. Terkadang semua langkah persiapan dan sinkronisasi berhasil, tetapi langkah upgrade terakhir masih gagal. Jika demikian, laporkan bug. Meskipun Anda berhasil memperbaiki error tersebut, laporkan kegagalan awal ke pelacak bug sehingga masalah tersebut dapat ditangani oleh tim pengembangan.