AAPT2 (Android Asset Packaging Tool) adalah alat build yang digunakan oleh Android Studio dan Plugin Android Gradle untuk mengompilasi dan memaketkan resource aplikasi Anda. AAPT2 mengurai, mengindeks, dan mengompilasi resource menjadi format biner yang dioptimalkan untuk platform Android.
Plugin Android Gradle 3.0.0 dan lebih tinggi mengaktifkan AAPT2 secara default, dan biasanya
Anda tidak perlu meminta aapt2
sendiri. Namun, jika lebih memilih untuk menggunakan
sistem build dan terminal milik sendiri daripada Android Studio, Anda dapat menggunakan AAPT2 dari
command line. Anda juga dapat men-debug error build yang terkait dengan AAPT2 dari command line.
Untuk melakukannya, Anda dapat menemukan AAPT2 sebagai alat mandiri di Android SDK Build Tools 26.0.2 dan yang lebih baru.
Untuk mendownload Android SDK Build Tools dari command line, gunakan sdkmanager dan jalankan perintah:
sdkmanager "build-tools;build-tools-version"
Setelah mendownload SDK Build Tools, Anda dapat menemukan AAPT2 yang berada di
android_sdk/build-tools/version/
.
Karena revisi Android SDK Build Tools baru tidak dirilis terlalu
sering, versi AAPT2 yang disertakan dalam SDK Build Tools Anda mungkin bukan
yang terbaru. Untuk mendapatkan versi terbaru AAPT2, baca Download AAPT2 dari Google Maven.
Untuk menggunakan AAPT2 dari command line di Linux atau Mac, jalankan perintah aapt2
.
Di Windows, jalankan perintah aapt2.exe
. AAPT2 mendukung kompilasi
resource yang lebih cepat dengan mengaktifkan kompilasi inkremental. Hal ini dicapai dengan membagi
pemrosesan resource menjadi dua langkah:
- Compile: mengompilasi file resource ke dalam format biner.
- Link: menggabungkan semua file yang dikompilasi, lalu memaketkannya menjadi satu.
Pembagian ini akan membantu meningkatkan performa untuk build inkremental. Misalnya, jika ada perubahan dalam satu file, Anda hanya perlu menghimpun ulang file tersebut.
Mendownload AAPT2 dari Google Maven
Untuk mendapatkan versi terbaru AAPT2 yang tidak disertakan dalam alat build, Anda dapat mendownload AAPT2 dari repositori Maven Google sebagai berikut:
- Buka com.android.tools.build > aapt2 dalam indeks repositori.
- Salin nama versi terbaru AAPT2.
Masukkan nama versi yang Anda salin ke URL berikut dan tentukan sistem operasi target Anda: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar
Misalnya, untuk mendownload versi 3.2.0-alpha18-4804415 untuk Windows, Anda dapat menggunakan: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar
Buka URL di browser. AAPT2 akan segera didownload.
Buka paket file JAR yang baru saja didownload. File JAR harus berisi
aapt2
yang dapat dijalankan dan beberapa library yang dijadikan tumpuan oleh file tersebut.
Compile
AAPT2 mendukung kompilasi semua jenis resource Android,
seperti file drawable dan file XML. Saat memanggil AAPT2 untuk kompilasi, Anda
harus meneruskan satu file resource sebagai input per pemanggilan. AAPT2 kemudian menguraikan
file dan menghasilkan file biner menengah dengan ekstensi .flat
.
Meskipun Anda dapat meneruskan direktori resource yang berisi lebih dari satu file resource
ke AAPT2 menggunakan flag --dir
, Anda tidak akan mendapatkan keuntungan dari
kompilasi resource inkremental saat melakukannya. Artinya, saat meneruskan seluruh
direktori, AAPT2 mengompilasi ulang semua file dalam direktori bahkan saat hanya satu
resource yang berubah.
Jenis file output dapat berbeda berdasarkan input yang diberikan untuk kompilasi. Hal ini dijelaskan dalam tabel di bawah ini:
Input | Output |
---|---|
File resource XML, seperti String
dan Style,
yang terletak di direktori res/values/ .
|
Tabel resource dengan *.arsc.flat sebagai ekstensinya.
|
Semua file resource lainnya. |
Semua file selain file pada direktori res/values/ akan
dikonversi ke file XML biner dengan ekstensi *.flat .
Selain itu, semua file PNG dijalankan secara default dan menggunakan ekstensi *.png.flat
. Jika Anda memilih untuk tidak mengompresi PNG, Anda dapat menggunakan
opsi --no-crunch saat kompilasi.
|
File yang dihasilkan oleh AAPT2 tidak dapat dijalankan, dan nantinya, Anda harus menyertakan file biner ini sebagai input dalam fase penautan untuk membuat APK. Namun, file APK yang dihasilkan juga bukan file yang dapat dijalankan yang dapat langsung di-deploy ke perangkat Android, karena tidak berisi file DEX (bytecode yang dikompilasi) dan tidak ditandatangani.
Sintaksis Compile
Sintaksis umum untuk menggunakan compile
adalah sebagai berikut:
aapt2 compile path-to-input-files [options] -o output-directory/
Dalam contoh berikut, AAPT2 mengompilasi file resource dengan nama values.xml
dan
myImage.png
secara individual:
aapt2 compile project_root/module_root/src/main/res/values-en/ strings.xml -o compiled/ aapt2 compile project_root/module_root/src/main/res/drawable /myImage.png -o compiled/
Seperti yang ditunjukkan dalam tabel di atas, nama file output bergantung pada nama file
input dan nama direktori induknya (jenis resource dan
konfigurasi). Untuk contoh di atas dengan strings.xml
sebagai input, aapt2
secara otomatis memberi nama file output sebagai values-en_strings.arsc.flat
.
Di sisi lain, nama file untuk file drawable yang dikompilasi disimpan dalam
direktori drawable akan menjadi drawable_img.png.flat
.
Opsi Compile
Ada beberapa opsi yang dapat Anda gunakan dengan perintah compile
, seperti yang ditunjukkan
pada tabel di bawah ini:
Opsi | Deskripsi |
---|---|
-o path
|
Menentukan lokasi output untuk resource yang dihimpun.
Ini adalah flag yang diperlukan karena Anda harus menentukan lokasi ke direktori tempat AAPT2 dapat menghasilkan dan menyimpan resource yang dihimpun. |
--dir directory
|
Menentukan direktori yang akan dipindai untuk mencari resource.
Meskipun penanda ini dapat digunakan untuk menghimpun beberapa file resource dengan satu perintah, Anda tidak akan mendapatkan manfaat dari kompilasi inkremental sehingga opsi ini sebaiknya jangan digunakan untuk project besar. |
--pseudo-localize
|
Menghasilkan string default dalam versi yang dilokalkan secara semu, seperti en-XA dan en-XB. |
--no-crunch
|
Menonaktifkan pemrosesan PNG.
Gunakan opsi ini jika Anda sudah memproses file PNG, atau jika sedang membuat build debug yang tidak memerlukan kompresi ukuran file. Mengaktifkan opsi ini akan mempercepat eksekusi, tetapi ukuran file output akan menjadi lebih besar. |
--legacy
|
Memperlakukan error yang diizinkan saat menggunakan versi AAPT yang lebih lama sebagai
peringatan.
Flag ini harus digunakan untuk error waktu kompilasi yang tidak terduga. Untuk mengatasi perubahan perilaku diketahui yang mungkin didapatkan saat menggunakan AAPT2, baca Perubahan perilaku dalam AAPT2. |
-v
|
Aktifkan logging panjang |
Link
Dalam fase penautan, AAPT2 akan menggabungkan semua file menengah yang dihasilkan dari
fase kompilasi, seperti tabel resource, file XML biner, dan file
PNG terproses, lalu memaketkannya menjadi satu APK. Selain itu, file tambahan lainnya
seperti R.java
dan file aturan ProGuard dapat dihasilkan pada fase ini.
Namun, APK yang dihasilkan tidak berisi bytecode DEX dan tidak ditandatangani.
Artinya, Anda tidak dapat menerapkan APK ini ke perangkat. Jika tidak menggunakan Android
Gradle Plugin untuk membuat aplikasi dari command line,
Anda dapat menggunakan alat command line lainnya seperti d8 untuk
mengompilasi bytecode Java menjadi bytecode DEX danapksigner
untuk menandatangani APK.
Sintaksis Link
Sintaks umum untuk menggunakan link
adalah sebagai berikut:
aapt2 link path-to-input-files [options] -o outputdirectory/outputfilename.apk --manifest AndroidManifest.xml
Pada contoh berikut, AAPT2 menggabungkan dua file menengah -
drawable_Image.flat
dan values_values.arsc.flat
, serta file
AndroidManifest.xml
. AAPT2 menautkan hasil pada file android.jar
yang berisi
resource yang ditentukan dalam paket android:
aapt2 link -o output.apk -I android_sdk/platforms/android_version/android.jar compiled/res/values_values.arsc.flat compiled/res/drawable_Image.flat --manifest /path/to/AndroidManifest.xml -v
Opsi Link
Anda dapat menggunakan opsi berikut dengan perintah link
:
Opsi | Deskripsi |
---|---|
-o path
|
Menentukan jalur output untuk APK resource yang tertaut.
Flag ini diperlukan karena Anda harus menentukan jalur untuk APK output yang dapat menyimpan resource yang tertaut. |
--manifest file
|
Menentukan lokasi ke file manifes Android yang akan di-build.
Flag ini diperlukan karena file manifes menyimpan informasi penting tentang aplikasi Anda, seperti nama paket dan ID aplikasi. |
-I
|
Memberikan jalur ke android.jar platform atau APK lain seperti
framework-res.apk yang mungkin berguna saat membuat
fitur.
Flag ini diperlukan jika Anda menggunakan atribut dengan namespace android
(misalnya, android:id ) di file resource Anda.
|
-A directory
|
Menentukan direktori aset yang akan disertakan dalam APK.
Anda dapat menggunakan direktori ini untuk menyimpan file asli yang belum diproses. Untuk mempelajari lebih lanjut, baca Mengakses file asli. |
-R file
|
Teruskan masing-masing file .flat untuk menautkan, menggunakan semantik overlay
tanpa menggunakan tag <add-resource> .
Ketika Anda memberikan file resource yang melingkupi (memperluas atau mengubah) file yang ada, resource bertentangan yang terakhir diberikan akan digunakan. |
--package-id package-id
|
Menentukan ID paket yang akan digunakan untuk aplikasi Anda.
ID paket yang Anda tentukan harus lebih besar dari atau sama dengan 0x7f,
kecuali digunakan bersama |
--allow-reserved-package-id
|
Mengizinkan penggunaan ID paket yang sudah dialokasikan.
ID paket yang sudah dialokasikan adalah ID yang biasanya ditetapkan ke library
bersama dan berada dalam rentang inklusif 0x02 hingga 0x7e. Dengan menggunakan
Sebaiknya hanya gunakan opsi ini untuk paket yang memiliki min-sdk versi 26 atau lebih rendah. |
--java directory
|
Menentukan direktori untuk menghasilkan R.java .
|
--proguard proguard_options
|
Menghasilkan file output untuk aturan ProGuard. |
--proguard-conditional-keep-rules
|
Menghasilkan file output untuk aturan ProGuard bagi dex utama. |
--no-auto-version
|
Menonaktifkan penetapan versi SDK gaya dan tata letak otomatis. |
--no-version-vectors
|
Menonaktifkan penetapan versi otomatis vector drawable. Hanya gunakan opsi ini ketika mem-build APK dengan Vector Drawable Library. |
--no-version-transitions
|
Menonaktifkan penetapan versi otomatis resource transisi. Gunakan opsi ini hanya ketika mem-build APK dengan Transition Support Library. |
--no-resource-deduping
|
Menonaktifkan de-duplikasi resource secara otomatis dengan nilai yang identik di seluruh konfigurasi yang kompatibel. |
--enable-sparse-encoding
|
Mengaktifkan encoding entri sparse menggunakan pohon penelusuran biner. Opsi ini berguna untuk pengoptimalan ukuran APK, tetapi performa pengambilan resource harus dikorbankan. |
-z
|
Mewajibkan pelokalan string yang ditandai sebagai 'disarankan'. |
-c config
|
Menyediakan daftar konfigurasi yang dipisahkan dengan koma.
Misalnya, jika harus menggunakan support library (yang berisi terjemahan untuk berbagai bahasa), Anda dapat memfilter resource untuk konfigurasi bahasa yang ditentukan saja, seperti bahasa Inggris atau Spanyol. Anda harus menentukan konfigurasi bahasa dengan kode bahasa ISO 639-1 dua huruf, yang secara opsional diikuti dengan kode daerah ISO 3166-1-alpha-2 dua huruf yang diawali dengan huruf kecil 'r' (misalnya, en-rUS). |
--preferred-density density
|
Mengizinkan AAPT2 memilih kepadatan yang paling cocok dan menghapus
yang lainnya.
Ada beberapa kualifikasi kepadatan piksel yang tersedia untuk digunakan dalam aplikasi, seperti ldpi, hdpi, dan xhdpi. Saat menentukan kepadatan yang diinginkan, AAPT2 akan memilih dan menyimpan kepadatan yang paling cocok dalam tabel resource dan menghapus yang lainnya. |
--output-to-dir
|
Menghasilkan konten APK ke direktori yang ditentukan oleh -o .
Jika mendapatkan error ketika menggunakan flag ini, Anda dapat mengatasinya dengan mengupgrade ke Android SDK Build Tools 28.0.0 atau yang lebih baru. |
--min-sdk-version min-sdk-version
|
Menetapkan versi SDK minimum default yang akan digunakan untuk AndroidManifest.xml .
|
--target-sdk-version target-sdk-version
|
Menetapkan versi SDK target default yang akan digunakan untuk AndroidManifest.xml .
|
--version-code version-code
|
Menentukan kode versi (bilangan bulat) yang akan disertakan ke AndroidManifest.xml
jika belum ada.
|
--compile-sdk-version-name compile-sdk-version-name
|
Menentukan nama versi yang akan disertakan ke AndroidManifest.xml
jika belum ada.
|
--proto-format
|
Menghasilkan resource yang dikompilasi dalam format Protobuf. Cocok sebagai input bagi alat bundle untuk menghasilkan Android App Bundle. |
--non-final-ids
|
Menghasilkan R.java dengan ID resource non-final (referensi dari
kode aplikasi ke ID ini tidak akan disertakan selama kompilasi kotlinc/javac).
|
--emit-ids path
|
Memberikan file di jalur yang ditentukan dengan daftar nama jenis resource dan
pemetaan ID-nya. Sangat cocok digunakan dengan --stable-ids .
|
--stable-ids outputfilename.ext
|
Menggunakan file yang dihasilkan dengan --emit-ids yang berisi
daftar nama jenis resource dan ID yang ditetapkan kepadanya.
Opsi ini memungkinkan ID yang ditetapkan menjadi tetap stabil meskipun Anda menghapus atau menambahkan resource baru pada saat penautan. |
--custom-package package_name
|
Menentukan paket Java kustom untuk membuat R.java .
|
--extra-packages package_name
|
Membuat file R.java yang sama tetapi dengan nama paket yang berbeda.
|
--add-javadoc-annotation annotation
|
Menambahkan anotasi JavaDoc ke semua class Java yang dihasilkan. |
--output-text-symbols path
|
Menghasilkan file teks yang berisi simbol resource class R dalam
file yang ditentukan.
Anda harus menentukan jalur ke file output. |
--auto-add-overlay
|
Memungkinkan penambahan resource baru dalam overlay tanpa menggunakan
tag <add-resource> .
|
--rename-manifest-package manifest-package
|
Mengganti nama paket di AndroidManifest.xml .
|
--rename-instrumentation-target-package instrumentation-
target-package
|
Mengubah nama paket target untuk
instrumentasi.
Ini harus digunakan bersama |
-0 extension
|
Menentukan ekstensi file yang tidak ingin Anda kompresi. |
--split path:config[,config[..]]
|
Memisahkan resource berdasarkan suatu rangkaian konfigurasi untuk menghasilkan
versi APK yang berbeda.
Anda harus menentukan lokasi ke APK output beserta rangkaian konfigurasi. |
-v
|
Memungkinkan penambahan panjang output. |
Dump
dump
digunakan untuk mencetak informasi tentang APK yang Anda buat menggunakan
perintah link
. Misalnya, perintah berikut akan mencetak konten dari
tabel resource APK yang ditentukan:
aapt2 dump resources output.apk
Sintaksis Dump
Sintaksis umum untuk menggunakan dump
adalah sebagai berikut:
aapt2 dump sub-command filename.apk [options]
Sub-perintah Dump
Anda harus menentukan salah satu sub-perintah berikut dengan perintah dump
:
Sub-perintah | Deskripsi |
---|---|
apc
|
Mencetak konten AAPT2 Container (APC) yang dibuat selama proses kompilasi. |
badging
|
Mencetak informasi yang diekstraksi dari manifes APK. |
configurations
|
Mencetak setiap konfigurasi yang digunakan oleh resource di APK. |
packagename
|
Mencetak nama paket APK. |
permissions
|
Mencetak izin yang diekstraksi dari manifes APK. |
strings
|
Mencetak konten gabungan string tabel resource APK. |
styleparents
|
Mencetak induk gaya yang digunakan di APK. |
resources
|
Mencetak konten tabel resource APK. |
xmlstrings
|
Mencetak string dari xml yang dikompilasi APK. |
xmltree
|
Mencetak pohon xml yang dikompilasi APK. |
Opsi Dump
Anda dapat menggunakan opsi berikut dengan dump
:
Opsi | Deskripsi |
---|---|
--no-values
|
Menekan output nilai saat menampilkan resource. |
--file file
|
Menentukan file sebagai argumen yang akan dibuang dari APK. |
-v
|
Menambah panjang output. |
Perubahan perilaku saat menggunakan AAPT2
Sebelum AAPT2, AAPT adalah versi default Android Asset Packaging Tool yang kini sudah tidak digunakan lagi. Meskipun AAPT2 dapat langsung berfungsi dengan project lama, bagian ini menjelaskan beberapa perubahan perilaku yang harus Anda ketahui.
Hierarki elemen dalam manifes Android
Dalam versi AAPT sebelumnya, elemen yang disarangkan dalam node yang salah pada manifes Android akan diabaikan atau mengakibatkan munculnya peringatan. Misalnya, perhatikan contoh berikut:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.myname.myapplication"> <application ... <activity android:name=".MainActivity"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> <action android:name="android.intent.action.CUSTOM" /> </activity> </application> </manifest>
AAPT versi sebelumnya akan mengabaikan tag <action>
yang salah tempat.
Namun, dengan AAPT2, Anda akan mendapatkan error berikut:
AndroidManifest.xml:15: error: unknown element <action> found.
Untuk mengatasi masalah ini, pastikan elemen manifes disarangkan dengan benar. Untuk mengetahui informasi selengkapnya, baca Struktur file manifes.
Deklarasi resource
Anda tidak lagi dapat menunjukkan jenis resource dari atribut name
.
Misalnya, contoh berikut salah mendeklarasikan item resource attr
:
<style name="foo" parent="bar"> <item name="attr/my_attr">@color/pink</item> </style>
Mendeklarasikan jenis resource dengan cara ini akan mengakibatkan error build seperti berikut:
Error: style attribute 'attr/attr/my_attr (aka my.package:attr/attr/my_attr)' not found.
Untuk mengatasi error ini, deklarasikan jenis menggunakan type="attr"
secara eksplisit:
<style name="foo" parent="bar"> <item type="attr" name="my_attr">@color/pink</item> </style>
Selain itu, saat mendeklarasikan elemen <style>
, induknya juga harus
berupa jenis resource gaya. Jika tidak, Anda akan mendapatkan error seperti berikut:
Error: (...) invalid resource type 'attr' for parent of style
Namespace Android dengan ForegroundLinearLayout
ForegroundLinearLayout
menyertakan tiga
atribut:
foregroundInsidePadding
,
android:foreground
, dan
android:foregroundGravity
.
Perhatikan bahwa foregroundInsidePadding
tidak disertakan dalam namespace android
,
tidak seperti dua atribut lainnya.
Di AAPT versi sebelumnya, compiler akan mengabaikan
atribut foregroundInsidePadding
secara diam-diam saat Anda menentukannya dengan namespace
android
. Saat menggunakan AAPT2, compiler akan menangkapnya dengan cepat dan menampilkan
error build seperti berikut:
Error: (...) resource android:attr/foregroundInsidePadding is private
Untuk mengatasi masalah ini, cukup ganti android:foregroundInsidePadding
dengan
foregroundInsidePadding
.
Penggunaan simbol referensi resource @ yang salah
AAPT2 akan menampilkan error build jika Anda menghilangkan atau salah menempatkan simbol referensi
resource (@
). Misalnya, perhatikan jika Anda menghilangkan simbol tersebut saat
menentukan atribut gaya, seperti yang ditunjukkan di bawah ini:
<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar"> ... <!-- Note the missing '@' symbol when specifying the resource type. --> <item name="colorPrimary">color/colorPrimary</item> </style>
Saat membuat modul, AAPT2 akan menampilkan error build seperti berikut:
ERROR: expected color but got (raw string) color/colorPrimary
Selain itu, perhatikan jika Anda salah menyertakan simbol saat mengakses
resource dari namespace android
, seperti yang ditunjukkan di bawah ini:
... <!-- When referencing resources from the 'android' namespace, omit the '@' symbol. --> <item name="@android:windowEnterAnimation"/>
Saat membuat modul, AAPT2 akan menampilkan error build seperti berikut:
Error: style attribute '@android:attr/windowEnterAnimation' not found
Konfigurasi library yang salah
Jika aplikasi Anda harus menggunakan library pihak ketiga yang dibuat menggunakan versi lama
Android SDK Build Tools, aplikasi
mungkin akan berhenti bekerja pada runtime tanpa menampilkan error atau peringatan apa pun. Error
ini mungkin terjadi karena, saat pembuatan library, kolom R.java
dideklarasikan sebagai final
dan, akibatnya, semua ID resource disertakan dalam
class library.
AAPT2 bergantung pada kemampuan untuk menetapkan ulang ID ke resource library saat membuat
aplikasi Anda. Jika library menganggap ID tersebut sebagai final
dan menyertakannya sebagai
bagian dari dex library, ketidakcocokan runtime akan terjadi.
Untuk mengatasi error ini, hubungi pembuat library untuk membuat ulang library menggunakan versi terbaru Android SDK Build Tools dan memublikasikannya lagi.