AAPT2

AAPT2 (Android Asset Packaging Tool) is a build tool that Android Studio and Android Gradle Plugin use to compile and package your app's resources. AAPT2 parses, indexes, and compiles the resources into a binary format that is optimized for the Android platform.

Android Gradle Plugin 3.0.0 and higher enables AAPT2 by default. You typically don't need to invoke aapt2 yourself. However, if you prefer to use your terminal and your own build system instead of Android Studio, you can use AAPT2 from the command line. You can also debug build errors related to AAPT2 from the command line. To do so, find AAPT2 as a standalone tool in Android SDK Build Tools 26.0.2 and higher.

To download Android SDK Build Tools from the command line, use sdkmanager and run the following command:

sdkmanager "build-tools;build-tools-version"

Once you have downloaded the SDK Build Tools, find AAPT2 in android_sdk/build-tools/version/.

Because revisions of the Android SDK Build Tools aren't released often, the version of AAPT2 included in your SDK Build Tools might not be the latest. To get the latest version of AAPT2, download AAPT2 from Google Maven.

To use AAPT2 from the command line on Linux or Mac, run the aapt2 command. On Windows, run the aapt2.exe command.

AAPT2 supports faster compilation of resources by enabling incremental compilation. To accomplish incremental compilation, resource processing is separated into two steps:

• Compile: compiles resource files into binary formats.
• Link: merges all compiled files and packages them to a single package.

This separation helps improve performance for incremental builds. For example, if there are changes in a single file, you need to recompile only that file.

Download AAPT2 from Google Maven

To get the newest version of AAPT2 that's not bundled in the build tools, download AAPT2 from Google's Maven repository as follows:

1. In the repository index, navigate to com.android.tools.build > aapt2.
2. Copy the name of the latest version of AAPT2.

3. Insert the version name you copied into the following URL and specify your target operating system: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/ aapt2-version/aapt2-aapt2-version- [windows | linux | osx].jar

   For example, to download version 3.2.0-alpha18-4804415 for Windows, use: 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. Navigate to the URL in a browser. AAPT2 will begin downloading shortly.

5. Unpackage the JAR file you just downloaded.

   The JAR file should contain an aapt2 executable and some libraries that the executable depends on.

Compile

AAPT2 supports compilation of all Android resource types, such as drawables and XML files. When you invoke AAPT2 for compilation, pass a single resource file as an input per invocation. AAPT2 then parses the file and generates an intermediate binary file with a .flat extension.

When passing whole directories, AAPT2 recompiles all files in the directory even when only one resource has changed. Although you can pass resource directories containing more than one resource file to AAPT2 using the --dir flag, you don't gain the benefits of incremental resource compilation this way.

The output file types can differ based on the input you provide for compilation, as shown in the following table:

Table 1. The input and output file types for compilation

The files AAPT2 outputs are not executables, and you must later include these binary files as input in the link phase to generate an APK. However, the generated APK file is not an executable that you can deploy on an Android device right away, because it does not contain DEX files and is not signed.

Compile syntax

The general syntax for using compile is as follows:

aapt2 compile path-to-input-files [options] -o output-directory/

In the following example, AAPT2 compiles resource files named values.xml and myImage.png individually:

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/

As shown in table 1, the name of the output file depends on the input filename and the name of its parent directory.

For the preceding example with strings.xml file as the input, aapt2 automatically names the output file as values-en_strings.arsc.flat. However, the compiled drawable file stored in the drawable directory is named drawable_img.png.flat.

Compile options

There are several options that you can use with the compile command, as shown in table 2:

Table 2. Compile command options

Link

In the link phase, AAPT2 merges all the intermediate files that the compilation phase generates, such as resource tables, binary XML files, and processed PNG files, and then packages the files into a single APK. Additionally, other auxiliary files, such as R.java and ProGuard rules files, can be generated during this phase. However, the generated APK does not contain DEX bytecode and is unsigned. You can't deploy this APK to a device.

If you're not using the Android Gradle plugin to build your app from the command line, you can use other command-line tools, such as d8 to compile Java bytecode into DEX bytecode and apksigner to sign your APK.

Link syntax

The general syntax for using link is as follows:

aapt2 link path-to-input-files [options] -o
outputdirectory/outputfilename.apk --manifest AndroidManifest.xml

In the following example, AAPT2 merges two intermediate files, drawable_Image.flat and values_values.arsc.flat, and the AndroidManifest.xml file. AAPT2 links the result against the android.jar file, which holds the resources defined in the android package:

 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

Link options

You can use the following options with the link command:

Table 3. Link command options

Dump

dump is used for printing information about the APK you generated using the link command.

Dump syntax

The general syntax for using dump is as follows:

aapt2 dump sub-command filename.apk [options]

The following example prints content from the resource table of the specified APK:

aapt2 dump resources output.apk

Dump sub-commands

Specify one of the following sub-commands with the dump command:

Table 4. Dump sub-commands

Dump options

Use the following options with dump:

Table 5. Dump options

Diff

Use diff to compare two APKs and identify any differences between them.

Diff syntax

The general syntax for using diff is as follows:

aapt2 diff first.apk second.apk

There are no options for the diff command.

Optimize

optimize is used to run optimizations on the merged resources and resources.arsc before they are packaged into the APK. This optimization can reduce APK size by around 1-3%, depending on the size and number of resources that are being used.

Optimize syntax

The general syntax for using optimize is as follows:

aapt2 optimize options file[,file[..]]

The following example optimizes the resources in input.apk and creates a new, optimized APK in output.apk. It replaces the usual flat table representation with a more compact binary search tree, resulting in a smaller APK at the cost of retrieval performance:

aapt2 optimize -o output.apk --enable-sparse-encoding input.apk

Optimize options

You can use the following options with optimize:

Table 6. Optimize options

Convert

By default, the AAPT compile command compiles resources in to a binary format that is suitable for APKs. It is possible to also specify protobuf format that is suitable for AABs by specifying --proto-format. The convert command converts APKs between the two formats.

Convert syntax

The general syntax for convert is as follows:

aapt2 convert -o output-file options file[,file[..]]

The following example converts the resources in input.apk and creates a new, APK in output.apk containing protobuf format resources. It replaces the usual flat table representation with a more compact binary search tree, resulting in a smaller APK at the cost of retrieval performance:

aapt2 convert -o output.apk --output-format proto --enable-sparse-encoding input.apk

Convert Options

Use the following options with convert:

Table 7. Convert options

Daemon mode

AAPT version 2.19 introduced daemon mode for issuing commands. Daemon mode lets you enter multiple commands in a single AAPT session.

Daemon syntax

Start daemon mode with the following command:

aapt2 daemon

Once daemon mode is running, you can enter commands. Each argument of the command must be on a separate line, with a blank line at the end of the command. Exit daemon mode by typing Control+D.

Consider the following individual compile commands:

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/

These commands can be entered in daemon mode as:

aapt2 daemon
Ready
compile
project_root/module_root/src/main/res/values-en/strings.xml
-o
compiled/

Done
compile
project_root/module_root/src/main/res/drawable/myImage.png
-o
compiled/

Done
^D
Exiting daemon

Daemon mode options

The single option for daemon mode is --trace-folder folder, which generates a systrace JSON trace fragment to specified folder.

Version

Determine the version of AAPT2 you are using with the version command:

aapt2 version
Android Asset Packaging Tool (aapt) 2.19-8678579

Behavior changes when using AAPT2

Prior to AAPT2, AAPT was the default version of the Android Asset Packaging Tool, which is now deprecated. Although AAPT2 should immediately work with older projects, this section describes some behavior changes you should be aware of.

Element hierarchies in the Android manifest

In previous versions of AAPT, elements nested in incorrect nodes in the AndroidManifest.xml file were either ignored or resulted in a warning. For example, consider the following example:

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

Previous versions of AAPT would simply ignore the misplaced <action> tag.

With AAPT2, you receive the following error:

AndroidManifest.xml:15: error: unknown element <action> found.

To resolve the issue, make sure your manifest elements are nested correctly. For more information, read the App Manifest overview.

Declaration of resources

You can no longer indicate the type of a resource from the name attribute. The following example incorrectly declares an attr resource item:

<style name="childStyle" parent="parentStyle">
    <item name="attr/my_attr">@color/pink</item>
</style>

Declaring a resource type this way results in the following build error:

Error: style attribute 'attr/attr/my_attr (aka my.package:attr/attr/my_attr)'
not found.

To resolve this error, explicitly declare the type using type="attr":

<style name="childStyle" parent="parentStyle">
  <item type="attr" name="my_attr">@color/pink</item>
</style>

Additionally, when declaring a <style> element, its parent must also be a style resource type. Otherwise, you get an error similar to the following:

Error: (...) invalid resource type 'attr' for parent of style

Incorrect use of @ resource reference symbols

AAPT2 throws build errors when you omit or incorrectly place resource reference symbols (@). For example, if you omit the symbol when specifying a style attribute:

<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
  ...
  <!-- Note the missing '@' symbol when specifying the resource type. -->
  <item name="colorPrimary">color/colorPrimary</item>
</style>

When building the module, AAPT2 throws the following build error:

ERROR: expected color but got (raw string) color/colorPrimary

Additionally, if you incorrectly include the symbol when accessing a resource from the android namespace:

...
<!-- When referencing resources from the 'android' namespace, omit the '@' symbol. -->
<item name="@android:windowEnterAnimation"/>

When building the module, AAPT2 throws the following build error:

Error: style attribute '@android:attr/windowEnterAnimation' not found

Incorrect configuration of libraries

If your app has a dependency on a third-party library that was built using older versions of the Android SDK Build Tools, your app might crash at runtime without displaying any errors or warnings. This crash might occur because during the library's creation, the R.java fields are declared final. As a result, all the resource IDs are inlined in the library's classes.

AAPT2 relies on being able to re-assign IDs to library resources when building your app. If the library assumes the IDs are final and inlines them in the library DEX, there is a runtime mismatch.

To resolve this error, contact the library author to rebuild the library using the latest version of the Android SDK Build Tools, and republish the library.