Menggunakan Upgrade Assistant plugin Android Gradle

Upgrade Assistant plugin Android Gradle (AGP) adalah alat di Android Studio yang membantu Anda mengupgrade versi AGP yang digunakan oleh project Anda.

Kami merilis perubahan AGP secara berkala yang terkait dengan fitur baru untuk mengonfigurasi build, yaitu API baru untuk digunakan oleh plugin Gradle lainnya, dan menyesuaikan integrasi build project dengan Android Studio. Dengan mengupgrade versi AGP yang digunakan oleh project, Anda dapat memanfaatkan fitur-fitur terbaru.

Apa kegunaan Upgrade Assistant AGP?

Upgrade Assistant AGP membantu 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 kami mengembangkan AGP, kami memperbarui file build 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 bertujuan untuk menghilangkan kebutuhan perubahan uji coba yang menyebabkan error pada file build, atau menebak arti pesan error setelah upgrade, serta menjelaskan alasan perubahan yang disarankan tersebut harus dilakukan.

Cara menggunakan Upgrade Assistant AGP

Untuk menggunakan Upgrade Assistant, pastikan struktur project Anda mengakomodasinya, lalu jalankan dari Android Studio, seperti yang dijelaskan di bawah.

Penyiapan

Sebelum menjalankan Upgrade Assistant, pastikan project Anda telah diformat dan dicadangkan dengan benar.

Membuat struktur project menggunakan file build Gradle dan bahasa khusus domain

Upgrade Assistant AGP akan berfungsi dengan baik jika Anda melakukan hal berikut:

  • Mengonfigurasi build menggunakan file build Gradle: Upgrade Assistant mengandalkan analisis statis file build Gradle. Untuk mengoptimalkan Upgrade Assistant, Anda harus mengonfigurasi build menggunakan file build ini. Perlu diperhatikan bahwa Upgrade Assistant tidak mendukung project yang menggunakan buildSrc untuk menentukan konstanta dan variabel yang digunakan dalam file build. Secara umum, sebaiknya jangan menggunakan buildSrc untuk membuat struktur project Anda, karena mungkin tidak efisien: perubahan sekecil apa pun pada konstanta dan variabel buildSrc akan memicu pembuatan ulang project sepenuhnya.
  • Menggunakan bahasa khusus domain build deklaratif: File build Gradle memiliki ekspresi dalam bahasa pemrograman lengkap, Groovy dan/atau Kotlin. Namun, semakin deklaratif ekspresi konfigurasi project, semakin besar kemungkinan Upgrade Assistant akan berhasil menemukan semua tempat yang perlu disesuaikan untuk upgrade.

Meskipun project tidak dijalankan berdasarkan batasan ini, Upgrade Assistant mungkin masih gagal melakukan upgrade tanpa kendala. Lihat Pemecahan masalah untuk mendapatkan panduan cara menyelesaikan atau melaporkan bug.

Mencadangkan project

Sebelum mulai 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, sebaiknya cadangkan 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:

  1. Luncurkan Upgrade Assistant dari perintah notifikasi atau dengan membuka Tools > AGP Upgrade Assistant... Jendela alat yang muncul akan menampilkan detail upgrade default dari AGP versi project saat ini ke versi terbaru yang didukung oleh versi Android Studio ini.
Jendela alat Upgrade Assistant AGP saat diluncurkan, dan perintah notifikasi.
Gambar 1. Jendela alat Upgrade Assistant AGP saat diluncurkan, dan perintah notifikasi.
  1. Periksa langkah-langkah yang diperlukan dan direkomendasikan. Di panel sebelah kiri, terdapat hierarki dengan kotak centang yang memberi detail setiap langkah dalam upgrade, yang dikategorikan berdasarkan apakah langkah tersebut diperlukan atau direkomendasikan untuk update, dan apakah langkah tersebut merupakan prasyarat dari langkah lain atau bukan. Pilih satu per satu item dalam hierarki untuk menampilkan detail selengkapnya tentang setiap langkah di panel utama.

  2. Jalankan upgrade dengan memilih langkah-langkah yang diperlukan atau yang diinginkan, lalu mengklik Run selected steps. Upgrade Assistant akan membuat perubahan pada 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.

  3. Setelah project berhasil disinkronkan dengan Android Studio, build project dan jalankan rangkaian pengujian untuk memverifikasi bahwa operasi upgrade tidak mengubah fungsi apa pun.

  4. Setelah memverifikasi bahwa project Anda dalam kondisi baik, commit versi baru project ke sistem kontrol versi.

Pemecahan masalah

Jika Upgrade Assistant menawarkan upgrade, tetapi upgrade gagal (biasanya dengan membuat perubahan pada file build yang menyebabkan kegagalan sinkronisasi), ada langkah-langkah yang dapat Anda lakukan untuk membantu mengisolasi dan memperbaiki error.

  • Pertama, periksa error yang menyebabkan kegagalan sinkronisasi. Terkadang, error akan memiliki penyebab yang jelas, yang dapat Anda tangani dalam file build project.

  • Jika pesan error tidak jelas, atau penyebab masalah tidak diketahui dengan jelas, berarti saatnya untuk mengembalikan project ke status aslinya guna membagi upgrade menjadi langkah yang lebih kecil. Pulihkan status asli dari kontrol versi atau dari cadangan, dan pastikan project (dalam status aslinya) disinkronkan sekali lagi dengan Android Studio. Selanjutnya, Anda dapat menyelidiki menggunakan dua jenis pengelompokan upgrade berikut:

    • Upgrade ke versi AGP yang bukan versi terbaru. Jika upgrade yang salah adalah upgrade sejumlah besar versi, cara terbaik untuk membuat progres dan membantu mengisolasi masalahnya adalah dengan melakukan serangkaian upgrade yang lebih kecil, dari setiap versi, untuk menemukan upgrade pertama yang memicu masalah.
    • Dalam upgrade, lakukan setiap langkah satu per satu. Setelah menemukan upgrade antara versi AGP yang berurutan yang memicu masalah, Anda mungkin dapat menonaktifkan setiap langkah dalam upgrade. Jika demikian, coba lakukan setiap langkah satu per satu, untuk mengetahui langkah mana yang memicu masalah. Jika Anda tidak dapat menemukan langkah yang bermasalah, sebaiknya periksa catatan rilis plugin Gradle lain yang Anda gunakan untuk masalah kompatibilitas apa pun dengan Gradle atau AGP. Terkadang, akan ada rilis baru untuk 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, tetap laporkan kegagalan awal ke pelacak bug agar masalah dapat ditangani oleh tim pengembangan.