Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

AAPT2

AAPT2 (Android Asset Packaging Tool) adalah alat build yang digunakan oleh Android Studio dan Android Gradle Plugin untuk mengompilasi dan memaketkan resource aplikasi Anda. AAPT2 mengurai, mengindeks, dan mengompilasi resource menjadi format biner yang dioptimalkan untuk platform Android.

Android Gradle Plugin 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 tinggi.

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 menjadi 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 Google Maven sebagai berikut:

  1. Buka com.android.tools.build > aapt2 dalam indeks repositori.
  2. Salin nama versi terbaru AAPT2.
  3. 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

  4. Buka URL di browser. AAPT2 akan segera didownload.

  5. 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 dam 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

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.

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

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.

--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 --allow-reserved-package-id, Anda dapat menetapkan ID yang berada dalam rentang ID paket yang sudah dialokasikan.

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 tinggi.

--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 dihimpun 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 --rename-manifest-package.

-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-perintahDeskripsi
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:

OpsiDeskripsi
--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.