a little madness

A man needs a little madness, or else he never dares cut the rope and be free -Nikos Kazantzakis


Understanding the Android Build Process


In my previous post, I ran through how I set up a build for an Android project. The build was based around the Ant and Eclipse support provided in the Android SDK. This time around, I’ll dig into what actually happens under the hood when you run an Android build. This helped me to understand how everything fits together, which is key for diagnosing problems or making future changes.

Overview of the Build Process

The easiest way to get a handle on the build process as a whole is to trace the inputs and outputs at each stage, which I have drawn up in the graph below:

Briefly, your source and resources are compiled, converted to run on the Android VM, and then packaged up in an apk file (a zip-compatible format). In the following sections I’ll explain each step in a little more detail. Note that throughout the explanations I will refer to the default input and output locations (e.g. src/ for Java source, and bin/ for binary output) — if you customise these paths then adjust as necessary.

Resource Pre-compilation

The first step in the build process involves generation of Java source files from your Android resources. The resources, stored in the res subdirectory, include such things as icons, layouts and strings. These are compiled using the aapt tool into a file named R.java, stored in the gen/ subdirectory. If you take a look at the generated file, you will see that it defines a bunch of constants:

 * This class was automatically generated by the
 * aapt tool from the resource data it found.  It
 * should not be modified by hand.

package com.zutubi.android.myapp;

public final class R {
    public static final class attr {
    public static final class drawable {
        public static final int icon=0x7f020000;
    public static final class layout {
        public static final int main=0x7f030000;
    public static final class string {
        public static final int app_name=0x7f040001;
        public static final int hello=0x7f040000;

The constants are used to refer to your resources, which are stored in the package file separately in a later step.

Service Interface Pre-compilation

The second build step also involves generation of Java source. If your project uses any service interfaces, you need to include the service interface definition files (which have an .aidl extension) in your project. These files superficially resemble normal Java interfaces:

package com.zutubi.android.myapp;

interface ISimpleService
    String echo(in String s);

The aidl tool is used to generate actual Java interfaces for these services. The Java source files will have the same name as the input files (with the .aidl extension replaced by .java) and are created in the gen/ subdirectory. These generated sources serve as a basis for you to implement or call the service interfaces in your own code.

Java Compilation

After the two pre-compilation steps, your project’s Java code is complete and ready to be compiled itself. This step is a standard Java compilation from .java source files (both hand-crafted and generated) to .class bytecode files. The binary bytecode files are stored in the bin/classes subdirectory.

One thing to be aware of is the classpath used to compile your source. This includes:

  • The android.jar file for your target Android platform. This jar includes class and method stubs for all of the Android APIs.
  • External library jars you have added to your project (all .jar files in the libs/ subdirectory).
  • For test projects only: the class files and external libraries for the tested project.

Bytecode Translation

After compilation, you have standard Java bytecode, which would run on a standard Java VM. However, Android uses its own Dalvik VM, which requires a different bytecode format. Thus, after compilation, the dx tool is used to translate your class files into a Dalvik executable or .dex file. This includes the class files stored in any external library jars you have added to your project. All classes are package up in a single output file, named classes.dex, which is produced in the bin/ subdirectory.

Resource Packaging

Next, the resources are compiled into a partial Android package file. This is done by the same aapt tool that generates Java source corresponding to the resources. The resource package is created, named after your application with an ap_ suffix in the bin directory. You can use unzip to take a peek inside the package:

 jsankey@caligula:~/work/my-app/build$ unzip -t MyApp.ap_
Archive:  MyApp.ap_
    testing: res/layout/main.xml      OK
    testing: AndroidManifest.xml      OK
    testing: resources.arsc           OK
    testing: res/drawable-hdpi/icon.png   OK
    testing: res/drawable-ldpi/icon.png   OK
    testing: res/drawable-mdpi/icon.png   OK
No errors detected in compressed data of MyApp.ap_.

Note that although icon and layout files are included at their original location, they have been processed during packaging (presumably for more efficient storage and/or processing). The icons appear to be optimised but still valid images, whereas layout XML files are converted to a binary format. Strings are compiled into the binary resources.arsc file.

Debug Packaging and Signing

Now all of the components required for the final Android package are ready to be bundled up into an apk file named after your application. In the default debug mode, this build step also includes signing of the package with a debug key. Note that for release, signing is a separate step that requires access to your own key (and may prompt for a password). Android packages are assembled with the apkbuidler tool, which takes input from several sources:

  • The Dalvik executable file bin/classes.dex.
  • All non-Java resources from your source directory (src/).
  • All non-Java resources from your external libraries (found by searching all .jar files in the libs/ subdirectory).
  • Any native code shared-libraries included by your project.
  • The resource package built in the previous step.

The produced package will be placed in the bin/ subdirectory, named something like MyApp-debug-unaligned.apk.


As a final optimisation step, the package file is aligned using the zipalign tool. This step ensures that resources in the package file are aligned on 4-byte word boundaries. This allows the Dalvik VM to memory-map those parts of the file for more efficient access. You can read more about alignment on the Android Developers Blog. This step takes the -unaligned package as input, and produces an output something like bin/MyApp-debug.apk. This is the final, signed, aligned Android package — ready to be installed on an Android device!

Liked this post? Share it!

6 Responses to “Understanding the Android Build Process”

  1. June 12th, 2010 at 2:46 pm

    Nick Burton says:

    Hey guys, love your work. Just thought i’d invite you to join the Android Australia user group. Would be great to have you onboard.



  2. June 12th, 2010 at 2:49 pm

    Nick Burton says:

    (Here’s the link http://bit.ly/androidaustralia)

  3. June 28th, 2011 at 4:42 am

    satish says:

    This is the best explanation that I have seen regarding complete pre execution process.. Awesome really..

  4. May 31st, 2012 at 1:41 pm

    Android?????? | Bits Digger says:

    [...] file format?? ??APK????? ??build process?? [...]

  5. January 31st, 2013 at 10:18 pm

    Evgeni says:

    Very nice explanation. Thank you.

  6. April 29th, 2014 at 9:21 pm

    Mayank Gupta says:


    Nice Work. Can you please provide a similar article depicting the build process for the NDK applications.

Leave a Reply