How to use aapt2, where is the documentation?

Question

I have used aapt p to package resources and generate R.java.

But when I upgraded to Android 24, I found aapt2.exe.

Should I use aapt2.exe? How do I use it? I could not find any documentation about it.

Answer 1

There are some big differences between how AAPT and AAPT2 work.

Compile and link

The main idea behind AAPT2, apart from new features, is that it divides the 'package' step into two: 'compile' and 'link'. It improves performance, since if only one file changes, you only need to recompile that one file and link all the intermediate files with the 'link' command.

More restrictive

AAPT2 tries to catch most bugs as early as possible. That's why when switching from AAPT to AAPT2 you might encounter many errors stating that some elements are nested incorrectly or that some references are incorrect. For more info on the new restrictiveness look at Android Studio 3.0 documentation.

Usage

Android Studio 3.0 comes with AAPT2 enabled by default (with Android Gradle Plugin 3.0.0). But if you want to use AAPT2 in your own script, you will need to change the way you process your resources. For the 'package' command with AAPT you would pass the resource directory with the -S. With AAPT2 you need to compile each resource first with the 'compile command and only then pass all the compiled files with the -R flag.
For example:

aapt package -S app/src/main/res/ ...

Instead use:

aapt2 compile -o compiled/res/ app/src/main/res/values/values.xml
aapt2 compile -o compiled/res/ app/src/main/res/drawable/myImage.png --no-crunch
...
aapt2 link -R compiled/res/values_values.arsc.flat -R compiled/res/drawable_myImage.flat ...

Flags

There are more differences in flag usage, for example the both '--pseudo-localize' and '--no-crunch' flags are used per file during the 'compile' step. For full information about AAPT2 flags type:

aapt2 compile -h
aapt2 link -h

Answer 2

Note: treat this as an addition to Izabela's answer

The authors of the Overlay Manager Service in Android O presented their work and talk about AAPT2 in their slides (see slides 12-14 for context). The official documentation for this tool is now here (courtesy @Shrijana's answer)

Also, when in doubt, look at the source code: https://android.googlesource.com/platform/frameworks/base/+/android-7.0.0_r7/tools/aapt2.