Pengoptimalan untuk penulis library

Sebagai penulis library, Anda harus memastikan bahwa developer aplikasi dapat dengan mudah menyertakan library Anda ke dalam aplikasi mereka sekaligus mempertahankan pengalaman pengguna akhir yang berkualitas tinggi. Artinya, library Anda harus kompatibel dengan pengoptimalan Android (R8) tanpa memerlukan penyiapan tambahan dari developer—atau mendokumentasikan bahwa library mungkin tidak sesuai untuk digunakan di Android. Pustaka yang ditujukan untuk digunakan di Android tidak boleh mencegah pengoptimalan aplikasi penting dan mematuhi persyaratan pengoptimalan tambahan.

Dokumentasi ini ditujukan bagi developer library yang dipublikasikan, tetapi mungkin juga berguna bagi developer modul library internal dalam aplikasi modular yang besar.

Jika Anda adalah developer aplikasi dan ingin mempelajari cara mengoptimalkan aplikasi Android Anda, lihat Mengaktifkan pengoptimalan aplikasi. Untuk mempelajari library mana yang tepat untuk digunakan, lihat Pilih library dengan bijak.

Memahami jenis aturan penyimpanan

Ada dua jenis aturan penyimpanan berbeda yang dapat Anda miliki di pustaka:

  • Aturan penyimpanan konsumen harus menentukan aturan yang menyimpan apa pun yang tercermin di library. Jika library menggunakan refleksi atau JNI untuk memanggil kodenya, atau kode yang ditentukan oleh aplikasi klien, aturan ini harus menjelaskan kode yang perlu dipertahankan. Library harus mengemas aturan penyimpanan konsumen, yang menggunakan format yang sama dengan aturan penyimpanan aplikasi. Aturan ini dibundel ke dalam artefak library (AAR atau JAR) dan digunakan secara otomatis selama pengoptimalan aplikasi Android saat library digunakan. Aturan ini dikelola dalam file yang ditentukan dengan properti consumerProguardFiles di file build.gradle.kts (atau build.gradle). Untuk mempelajari lebih lanjut, lihat Menulis aturan penyimpanan konsumen.
  • Aturan keep build library diterapkan saat library Anda dibangun. File ini hanya diperlukan jika Anda memutuskan untuk mengoptimalkan library sebagian pada waktu build. Hal ini harus mencegah API publik library dihapus, jika tidak, API publik tidak akan ada dalam distribusi library, yang berarti developer aplikasi tidak dapat menggunakan library. Aturan ini dikelola dalam file yang ditentukan dengan properti proguardFiles di file build.gradle.kts (atau build.gradle) Anda. Untuk mempelajari lebih lanjut, lihat Mengoptimalkan build library AAR.

Persyaratan dan panduan pengoptimalan

Konfigurasi R8 di library memiliki dampak global pada ukuran dan performa biner akhir aplikasi yang menggunakan library tersebut. Selain praktik terbaik aturan penyimpanan umum, penulis pustaka harus mematuhi persyaratan tertentu, dan mempertimbangkan panduan tambahan.

Mematuhi persyaratan pengoptimalan

Inefisiensi dalam library adalah penyebab utama pembengkakan aplikasi, pemborosan memori, pengaktifan yang lambat, dan ANR (error Aplikasi Tidak Merespons). Library harus menghindari pelanggaran persyaratan berikut untuk menghindari penurunan kualitas aplikasi dan pengalaman pengguna secara signifikan.

  • Tidak ada aturan penyimpanan luas atau di seluruh paket: Library Anda tidak boleh menyertakan aturan penyimpanan luas yang menyimpan sebagian besar kode di library Anda, atau di library lain. Aturan penyimpanan yang luas dapat menyelesaikan error dalam jangka pendek, tetapi akan memperbesar ukuran aplikasi semua aplikasi yang menggunakan library Anda.

    Jangan sertakan aturan keep di seluruh paket (seperti -keep class com.mylibrary.** {*; }) untuk paket di library Anda atau library lain yang dirujuk. Aturan tersebut membatasi pengoptimalan untuk paket ini di semua aplikasi yang menggunakan library Anda.

  • Tidak ada aturan global yang tidak pantas: Jangan pernah menggunakan opsi global seperti -dontobfuscate atau -allowaccessmodification.

  • Penggunaan codegen daripada refleksi jika memungkinkan: Jika memungkinkan, gunakan pembuatan kode (codegen) daripada refleksi. Codegen dan refleksi adalah pendekatan umum untuk menghindari kode boilerplate saat memprogram, tetapi codegen lebih kompatibel dengan pengoptimal aplikasi seperti R8.

    Dengan codegen, kode dianalisis dan dimodifikasi selama proses build. Karena tidak ada modifikasi besar setelah waktu kompilasi, pengoptimal mengetahui kode yang pada akhirnya diperlukan dan kode yang dapat dihapus dengan aman.

    Dengan refleksi, kode dianalisis dan dimanipulasi saat runtime. Karena kode tidak benar-benar diselesaikan hingga dieksekusi, pengoptimal tidak tahu kode mana yang dapat dihapus dengan aman. Hal ini kemungkinan akan menghapus kode yang digunakan secara dinamis melalui refleksi selama runtime, yang menyebabkan aplikasi error bagi pengguna.

    Banyak library modern menggunakan codegen, bukan refleksi. Lihat KSP untuk titik entri umum, yang digunakan oleh Room, Dagger2, dan banyak lagi.

  • Mendukung mode penuh R8: Library Anda tidak boleh mengalami error saat mode penuh R8 diaktifkan. Mode penuh R8 adalah mode yang direkomendasikan untuk digunakan R8, dan merupakan mode default sejak AGP 8.0, yang dibuat stabil pada tahun 2023. Jika library Anda error di R8, solusinya adalah mengidentifikasi titik entri JNI atau refleksi tertentu dan menambahkan aturan yang ditargetkan, bukan mempertahankan seluruh paket.

Rekomendasi tambahan

Selain persyaratan pengoptimalan, berikut adalah rekomendasi tambahan.

  • Jangan gunakan -repackageclasses dalam file aturan penyimpanan konsumen library Anda. Namun, untuk mengoptimalkan build library, Anda dapat menggunakan -repackageclasses dengan nama paket internal, seperti <your.library.package>.internal, di file aturan penyimpanan build library Anda. Hal ini dapat meningkatkan efisiensi library Anda di aplikasi yang tidak dioptimalkan. Namun, hal ini umumnya tidak diperlukan karena aplikasi juga harus dioptimalkan.
  • Deklarasikan semua atribut yang Anda butuhkan agar library Anda berfungsi dalam file aturan keep library Anda, meskipun mungkin ada tumpang-tindih dengan atribut yang ditentukan dalam proguard-android-optimize.txt.
  • Jika Anda memerlukan atribut berikut dalam distribusi library, pertahankan atribut tersebut dalam file aturan penyimpanan build library Anda, dan bukan dalam file aturan penyimpanan konsumen library Anda:
    • AnnotationDefault
    • EnclosingMethod
    • Exceptions
    • InnerClasses
    • RuntimeInvisibleAnnotations
    • RuntimeInvisibleParameterAnnotations
    • RuntimeInvisibleTypeAnnotations
    • RuntimeVisibleAnnotations
    • RuntimeVisibleParameterAnnotations
    • RuntimeVisibleTypeAnnotations
    • Signature
  • Penulis library harus menyimpan atribut RuntimeVisibleAnnotations dalam aturan penyimpanan konsumen jika anotasi digunakan saat runtime.
  • Penulis library tidak boleh menggunakan opsi global berikut dalam aturan penyimpanan konsumen:
    • -include
    • -basedirectory
    • -injars
    • -outjars
    • -libraryjars
    • -repackageclasses
    • -flattenpackagehierarchy
    • -allowaccessmodification
    • -renamesourcefileattribute
    • -ignorewarnings
    • -addconfigurationdebugging
    • -printconfiguration
    • -printmapping
    • -printusage
    • -printseeds
    • -applymapping
    • -obfuscationdictionary
    • -classobfuscationdictionary
    • -packageobfuscationdictionary

Saat refleksi tidak masalah

Jika Anda harus menggunakan refleksi, Anda hanya boleh merefleksikan ke salah satu dari berikut:

  • Jenis yang ditargetkan tertentu (implementasi antarmuka atau subkelas tertentu)
  • Kode menggunakan anotasi runtime tertentu

Penggunaan refleksi dengan cara ini membatasi biaya runtime, dan memungkinkan penulisan aturan penyimpanan konsumen yang ditargetkan.

Bentuk refleksi yang spesifik dan bertarget ini adalah pola yang dapat Anda lihat di framework Android (misalnya, saat meng-inflate aktivitas, tampilan, dan drawable) dan library AndroidX (misalnya, saat membuat WorkManager ListenableWorkers, atau RoomDatabases). Sebaliknya, refleksi Gson yang tidak terbatas tidak sesuai untuk digunakan di aplikasi Android.

Kesalahpahaman umum

Beberapa kesalahpahaman umum dapat menyebabkan Anda salah mengonfigurasi R8. Hal ini mencakup:

  • Kesalahan pemahaman tentang pengoptimalan R8: Berbeda dengan pemahaman umum, pengoptimalan R8 tidak hanya terbatas pada obfuscation, tetapi juga mencakup penyingkatan kode dan pengoptimalan logis dengan teknik penyisipan metode dan penggabungan class. Untuk mengetahui informasi selengkapnya, lihat Ringkasan pengoptimalan R8.

  • Melewati pengoptimalan library yang di-obfuscate: Kesalahan umum adalah menghilangkan library dari pengoptimalan, karena library dioptimalkan atau di-obfuscate saat dikompilasi ke AAR (Android Archive) atau JAR (Java Archive). Pengoptimalan selama waktu pembuatan library terbatas, dan aplikasi Anda tidak boleh menonaktifkan pengoptimalan library dengan menyertakannya dalam aturan keep. Untuk mengetahui informasi selengkapnya, lihat Mengoptimalkan build library AAR.

  • Salah memahami opsi -keep Aturan -keep mencegah R8 menjalankan optimization pass apa pun. Untuk mengetahui informasi selengkapnya, lihat Memilih opsi penyimpanan yang tepat.

Mengonfigurasi pengemasan aturan

Untuk memastikan aturan keep konsumen Anda diterapkan dengan benar, Anda harus mengemasnya dengan tepat, bergantung pada format library Anda.

Library AAR

Untuk menambahkan aturan konsumen bagi library AAR, gunakan opsi consumerProguardFiles dalam skrip build modul library Android. Untuk mengetahui informasi selengkapnya, lihat panduan kami tentang cara membuat modul library.

Kotlin

android {
    defaultConfig {
        consumerProguardFiles("consumer-proguard-rules.pro")
    }
    ...
}

Groovy

android {
    defaultConfig {
        consumerProguardFiles 'consumer-proguard-rules.pro'
    }
    ...
}

Library JAR

Untuk memaketkan aturan dengan library Kotlin atau Java yang dikirimkan sebagai JAR, letakkan file aturan Anda di direktori META-INF/proguard/ JAR akhir, dengan nama file apa pun. Misalnya, jika kode Anda ada di <libraryroot>/src/main/kotlin, letakkan file aturan konsumen di <libraryroot>/src/main/resources/META-INF/proguard/consumer-proguard-rules.pro dan aturan akan dibundel di lokasi yang benar dalam JAR output Anda.

Verifikasi bahwa JAR akhir mengikat aturan dengan benar dengan memeriksa bahwa aturan tersebut ada di direktori META-INF/proguard.

Mengoptimalkan build library AAR (lanjutan)

Umumnya, Anda tidak perlu mengoptimalkan build library secara langsung karena kemungkinan pengoptimalan pada waktu build library sangat terbatas. Sebagai developer library, Anda perlu mempertimbangkan beberapa tahap pengoptimalan dan mempertahankan perilaku, baik pada waktu build library maupun aplikasi, sebelum mengoptimalkan library tersebut.

Jika Anda masih ingin mengoptimalkan library pada waktu build, hal ini didukung oleh Plugin Android Gradle.

Kotlin

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        configureEach {
            consumerProguardFiles("consumer-rules.pro")
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles
                getDefaultProguardFile('proguard-android-optimize.txt'),
                'proguard-rules.pro'
        }
        configureEach {
            consumerProguardFiles "consumer-rules.pro"
        }
    }
}

Perhatikan bahwa perilaku proguardFiles sangat berbeda dengan consumerProguardFiles:

  • proguardFiles digunakan pada waktu build, sering kali bersama dengan getDefaultProguardFile("proguard-android-optimize.txt"), untuk menentukan bagian library Anda yang harus dipertahankan selama build library. Setidaknya, ini adalah API publik Anda.
  • consumerProguardFiles sebaliknya dikemas ke dalam library untuk memengaruhi pengoptimalan yang terjadi kemudian, selama build aplikasi yang menggunakan library Anda.

Misalnya, jika library Anda menggunakan refleksi untuk membuat class internal, Anda mungkin perlu menentukan aturan keep di proguardFiles dan consumerProguardFiles.

Jika Anda menggunakan -repackageclasses dalam build library, kemas ulang class ke sub-paket di dalam paket library Anda. Misalnya, gunakan -repackageclasses 'com.example.mylibrary.internal', bukan -repackageclasses 'internal'.

Mendukung berbagai versi R8 (lanjutan)

Anda dapat menyesuaikan aturan untuk menargetkan versi R8 tertentu. Hal ini memungkinkan library Anda berfungsi secara optimal dalam project yang menggunakan versi R8 yang lebih baru, sekaligus memungkinkan aturan yang ada untuk terus digunakan dalam project dengan versi R8 yang lebih lama.

Untuk menentukan aturan R8 yang ditargetkan, Anda harus menyertakannya dalam direktori META-INF/com.android.tools di dalam classes.jar AAR atau dalam direktori META-INF/com.android.tools JAR.

In an AAR library:
    proguard.txt (legacy location, the file name must be "proguard.txt")
    classes.jar
    └── META-INF
        └── com.android.tools (location of targeted R8 rules)
            ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
            └── ... (more directories with the same name format)

In a JAR library:
    META-INF
    ├── proguard/<ProGuard-rule-files> (legacy location)
    └── com.android.tools (location of targeted R8 rules)
        ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
        └── ... (more directories with the same name format)

Di direktori META-INF/com.android.tools, ada beberapa subdirektori dengan nama dalam bentuk r8-from-<X>-upto-<Y> untuk menunjukkan versi R8 yang digunakan untuk menulis aturan. Setiap subdirektori dapat memiliki satu atau beberapa file yang berisi aturan R8, dengan nama dan ekstensi file apa pun.

Perhatikan bahwa bagian -from-<X> dan -upto-<Y> bersifat opsional, versi <Y> bersifat eksklusif, dan rentang versi biasanya berkesinambungan, tetapi juga dapat tumpang-tindih.

Misalnya, r8, r8-upto-8.0.0, r8-from-8.0.0-upto-8.2.0, dan r8-from-8.2.0 adalah nama direktori yang merepresentasikan sekumpulan aturan R8 yang ditargetkan. Aturan di direktori r8 dapat digunakan oleh semua versi R8. Aturan dalam direktori r8-from-8.0.0-upto-8.2.0 dapat digunakan oleh R8 dari versi 8.0.0 hingga tidak termasuk versi 8.2.0.

Plugin Android Gradle menggunakan informasi tersebut untuk memilih semua aturan yang dapat digunakan oleh versi R8 saat ini. Jika library tidak menentukan aturan R8 yang ditargetkan, plugin Android Gradle akan memilih aturan dari lokasi lama (proguard.txt untuk AAR atau META-INF/proguard/<ProGuard-rule-files> untuk JAR).