What new Android developers need to know

Android is a new operating system. Apps are written in Java, which is a familiar language to many.  On the other hand, developing for mobile apps is a different beast than with other platforms.  Here are some things I've learned in my years of programming for Android, and I suggest if you are learning Android that you learn about these topics.  I think these make for great interview questions, so it would help to know about these topics if you are going for an Android related interview.

Android Topics

1.       Know what a task is in Android.

a.       How does the task and the navigation stack relate.

b.      What is the difference between default, singleTask, singleTop, etc.?

c.       What happens when you press BACK? 

d.      What happens when you press HOME?

2.       Know what activity lifecycles are. 

a.       When do you use onPause() vs. onDestroy()? 

b.      What are onConfigurationChange() and retainInstanceState() useful for? 

c.       What happens to static variables when you switch activities?

3.       Know what API levels are. 

a.       Unfortunately, the Android builder does not distinguish API levels.  You can build an application with minSdkVersion=3, targetSdkVersion=4 with code which uses methods only available on level 4.  This will build fine, but throw an exception when the class loader attempts to load your class files on an API level 3 phone.

b.      In Eclipse, change the API level to 3 briefly, just to see if the code can compile.

c.       We have to develop with API level 8 in order to use certain features in the manifest, so we have to be very careful about using API methods that are only API levels 1-3. 

d.      You can still use reflection and wrapper classes to prevent class loader from breaking, etc. to use newer classes; examples are available on the Android dev site.

e.      Be wary of the element in the Android manifest.

                                                               i.      An app may be filtered from the Marketplace based on these elements.

                                                             ii.      Bluetooth feature has special rules.

4.       Test your app in all sorts of UI configurations:

a.      Low density, extra large screens, landscape, etc.

b.      A layout may look good on a 320x480 screenshot in a mockup, but did the mockup address how it would look in landscape?

c.       Horizontally laid-out information isn’t good for mobile devices in general.  Keep the layouts flowing vertically.

d.      You get to create all sorts of UI configurations with emulators.

5.       Compress your graphics.  I use an open source program Paint.NET to adjust .PNG images. 

a.       PNG graphics can have unnecessary meta data from graphics programs which take up extra space.

b.      Sometimes encoding in 8-bit vs. 32-bit can save space, but careful that transparency is retained.

c.       If your business customer wants to give you graphics for every type of UI configuration, see if they can accept using a standard image size, and let Android scale the images.  It greatly increases the size of the app.  Android scales the images. 

d.      Use drawables defined in Android XML files when possible instead of bitmaps; they scale well in different sizes and take up less disk space.

6.       Don’t schedule services too often. 

a.       Do you really need to download data from the network every 15 minutes?  This is awful on battery life!

b.      You change the frequency of the service by rescheduling every time the service finishes instead of scheduling a periodic service.

Java in Android

1.       Learn what a strong reference, a weak reference, and a soft reference are.  Weak references are especially useful in Android.

a.       Use weak references when dealing with separate threads and timed operations: WeakReference. 

b.      Both WeakReference and SoftReferences can be useful for some types of caches.

2.       Always use separate threads when doing network operations, disk operations, and other long-running operations.

a.       It turns out that the same code which takes 5 ms can take 5000 ms when Android is out of memory or waiting for other processes to finish file I/O, killing and starting processes, and doing a GC on your app.

                                                               i.      Get used to doing lazy initialization.  It seems unnecessary until you get 500 ANRs on the Marketplace reports.

                                                             ii.      In startup methods, don’t initialize variables.  Wait until an accessor method such as getVariable().

b.      IntentServices, Handlers, Threads.  They are useful in different situations.

c.       IntentServices guarantee a separate thread and that multiple intents handled by the service are synchronized to be processed one after another.

d.      Handlers are useful for transferring messages from the network/etc. threads to the UI thread in an activity.

e.      Threads may be useful in some situations, but remember that a running thread is not a guarantee to keep your process alive; if all activities/services/etc. are closed, then a running thread can (and will) legally be destroyed by the OS.

3.       Be wary of static variables: you don’t have knowledge of their lifecycle, unlike instanced variables accessible through activities and services with onCreate() and onDestroy().

a.       Their value can be reset but

b.      Static variables are notorious for causing memory leaks.

c.      They are useful in some situations still.  For example, preventing code from executing more than once when your process has already started.

4.       Do you know what a memory leak in Java is?  It’s not the same as it is in C.  It refers to keeping strong references to objects which shouldn’t be used anymore (should be GC-able), but programming error has kept them strongly reachable.

a.       In Android especially, you never want to keep references to Activities and Services in variables, especially static variables. 

b.      Sometimes you do need contexts; you can either use Application as a context, or if you have to have the Activity context then 1. Use a weak reference, or 2. Don’t let the object which has a reference to the Activity be referenced by anything else: make sure the Activity completely “owns” the object.

5.       Don’t ever keep static references to Activities, Services, Views, or BroadcastReceivers.

a.       This causes memory leaks!

b.      You can use a global (static) context from the Application. 

c.       This is useful for getting resources, files, etc. Be careful; you can’t create dialogs from this context, and any activities started with the application context will always create a new task.

d.      If you have to use a static reference, use a WeakReference.

Standards

1.       Build machine is good.

a.       You can create custom Ant scripts.

b.      I use them to copy files based on build properties, and to change variables in the Config.java class.

c.       I also change AndroidManifest.xml using a script based on QA or release builds.

                                                               i.      No worry about developer forgetting to change items.

                                                             ii.      Add/remove debuggable attribute, permissions for logging to SD card, etc.

2.       Always use ProGuard in any app released to the Android Marketplace.

a.       Reduces app size by removing unused variables and methods.

b.      Obfuscates code, which theoretically cannot prevent hackers from snooping but does slow them down.

c.       Allows you to have code  like:
if (Config.LOGGING) print(“The data is: “ + data);
The above statement is completely removed when Config.LOGGING is false.

3.       Code formatters are useful

a.       Standardization is nice.

b.      Simple whitespace differences can cause merges to break.

c.       If you are using Eclipse, you can check in the project settings into the source repository.

d.      Deciding some standards can be akin to a religious war; after 50 years, lots and lots of smart people have debated this and they haven’t come to the same conclusion on what’s best.  Just go with something.

4.       Hungarian notation is used in Android OS and in some of our apps.

a.       It can be useful, but a developer can easily mess up.  In a strongly-typed symbolic language such as Java, source code formatters do a better job of telling you the data type of a variable.

b.      You don’t have to use the Android OS coding style, but it is an example of a coding style:

                                                               i.      mVariable means instanced field (member variable)

                                                             ii.      sVariable means non-final static field.

                                                            iii.      ALL_CAPS means a constant (final static)

c.       Hungarian Notation was originally meant to describe the type of data as in network response or pixel measurements.  It has been incorrectly used as data type as in “final static” or “DWORD LONG *”.

5.       Use themes and styles in your layouts. 

a.       It makes it easier to make changes.

b.      You’ll probably not use styles the first time you make your layouts.  Then when you have to go back and change 25 layout files just to move some pixels to the right, you’ll start using styles.

6.       Put logs everywhere. 

a.       Make a standard for how it’s done. 

b.      No need to remove them or comment them out when using ProGuard if wrapped in a constant boolean; this is a good thing.

c.       I have many ways of dealing with logs:

                                                               i.      Log items to logcat, filterable by one single tag. 

                                                             ii.      Log items to the SD card.  Great because this persists after device resets and lets you observe behavior overnight or over a long time.

                                                            iii.      Added menu item in debug area of app which will automatically e-mail logs to an e-mail address.

Useful reading:

http://developer.android.com/resources/browser.html?tag=article

http://developer.android.com/resources/faq/commontasks.html

http://developer.android.com/resources/articles/avoiding-memory-leaks.html

Easy method for formatting Android TextViews

Android TextViews don't have an easy method for changing the style of a substring of its text. You may have wanted to do something like textView.setTextColor(Color.RED, 10, 20); in order to set the 10th to the 20th characters red. I'll show you a method of making this easy to do; not just with colors, but with all sorts of styles.

Using regular HTML tags in strings

You do have a limited option to format your strings without any programmatic methods. In strings.xml, where you define your strings, you can use the simple HTML format tags <b>, <i>, and <u> for bold, italics, and underlining, respectively. For example,

<string name="text1">This text uses <b>bold</b> and <i>italics</i> by using inline tags such as <b> within the string file.</string>

A TextView with this string will appear as: This text uses bold and italics by using inline tags such as <b> within the string file.
Unfortunately, you cannot use any more HTML tags than that. In order to have some nice inline styles, we'll need to use CharacterStyles. This class has many sub-classes, and allows you to do everything from changing the text appearance (like ForegroundColorSpan, to more complicated things like making clickable links (ClickableSpan) and images (ImageSpan).

CharSequences

A quick note about how this works. Skip to the next section if you don't care. TextView, along with many other Android classes which use formatted text, don't just use simple Strings. They use CharSequences. Get this: a CharSequence is more abstract than a String; a String is a sub-class of CharSequence. A CharSequence defines a series of characters, such as a regular string, but it could also define a series of characters with formatting, such as a SpannableString. Internally, what we will do to change the middle of a TextView's text is to add spans to its text. More precisely, we will add CharacterStyles to the TextView's CharSequence (text), which is a SpannableString.

Format text dynamically

Here's a handy utility method which will take in some text, and return the text formatted. The key is to surround the text you want with tokens such as "##". The tokens will be removed in the returned result.
For example, if a TextView has its text set as "Hello, ##world##!" and you want world to be in red, call setSpanBetweenTokens("Hello ##world##!", "##", new ForegroundColorSpan(0xFFFF0000)); will return the text Hello, world! with world in red. Note that you can send multiple spans as parameters to this method.

/**
 * Given either a Spannable String or a regular String and a token, apply
 * the given CharacterStyle to the span between the tokens, and also
 * remove tokens.
 * <p>
 * For example, {@code setSpanBetweenTokens("Hello ##world##!", "##",
 * new ForegroundColorSpan(0xFFFF0000));} will return a CharSequence
 * {@code "Hello world!"} with {@code world} in red.
 *
 * @param text The text, with the tokens, to adjust.
 * @param token The token string; there should be at least two instances
 *             of token in text.
 * @param cs The style to apply to the CharSequence. WARNING: You cannot
 *            send the same two instances of this parameter, otherwise
 *            the second call will remove the original span.
 * @return A Spannable CharSequence with the new style applied.
 *
 * @see http://developer.android.com/reference/android/text/style/CharacterStyle.html
 */
public static CharSequence setSpanBetweenTokens(CharSequence text,
    String token, CharacterStyle... cs)
{
    // Start and end refer to the points where the span will apply
    int tokenLen = token.length();
    int start = text.toString().indexOf(token) + tokenLen;
    int end = text.toString().indexOf(token, start);

    if (start > -1 && end > -1)
    {
        // Copy the spannable string to a mutable spannable string
        SpannableStringBuilder ssb = new SpannableStringBuilder(text);
        for (CharacterStyle c : cs)
            ssb.setSpan(c, start, end, 0);

        // Delete the tokens before and after the span
        ssb.delete(end, end + tokenLen);
        ssb.delete(start - tokenLen, start);

        text = ssb;
    }

    return text;
}

Clickable spans

One of the spans you can set your text to is a ClickableSpan. You may have added this and wondered why anything didn't happen when you clicked on the link. Well, you need to have one extra step to let Android know that there is a clickable link and it needs to be navigated to. You need to set a MovementMethod to the TextView. You can investigate this further if you wish, or you can just see the sample code to make it work below (and it is also in the sample):

// Adapted from Linkify.addLinkMovementMethod(), to make links clickable.
//
MovementMethod m = textView.getMovementMethod();
if ((m == null) || !(m instanceof LinkMovementMethod))
{
    textView.setMovementMethod(LinkMovementMethod.getInstance());
}

Sample Application

The sample application is a simple application with a few TextViews and a Button. The first TextView shows how you can set a TextView's text just by using HTML tags in strings.xml. The second TextView demonstrates how to change text dynamically, using the above utility method. When the button is clicked, it will first set some text red using a ForegroundColorSpan. Second, it will set some text bold and italics using a StyleSpan. Third, it will make a generic link by setting some text to blue, underlining it (UnderlineSpan), and then creating an onClick method which executes some custom code using a ClickableSpan. The final click demonstrates both a ForegroundColorSpan and a RelativeSizeSpan.

Project source code - formattedtext.zip (7.22 Kb)

Optimizing, Obfuscating, and Shrinking your Android Applications with ProGuard

Obfu-what? Right, there's a lot of technical terms there, and you may not know what they mean. I'm going to describe a way for you to shrink the size of your Android applications in half, optimize them to make them run faster, and obfuscate them to make it harder for others to reverse engineer your code.

What we'll do is use a Java program called ProGuard to apply its magic to your program's code, during the build process. To do this we'll use an Ant script to build the program, and add our extra steps into the regular build process.

Why do it?

The short answer is that your code will be smaller and faster. How much smaller and faster depends, but in general you'll find your code will be a lot smaller and a little faster. There are three key functions that ProGuard will do. Much of the text below is taken from the ProGuard website.

You may hear the term obfuscation to describe all three processes. Actually, obfuscation is just one form of the processes that a program such as ProGuard does. Instead of saying "shrink, obfuscate, and optimize", we'll just use the simple term of obfuscation to describe all three in this blog.

Shrinking

Java source code (.java files) is typically compiled to bytecode (.class files). Bytecode is more compact than Java source code, but it may still contain a lot of unused code, especially if it includes program libraries. Shrinking programs such as ProGuard can analyze bytecode and remove unused classes, fields, and methods. The program remains functionally equivalent, including the information given in exception stack traces.

For a realistic example, take the following code:

    if (Config.LOGGING)
    {
        TestClass test = new TestClass();
        Log.d(TAG, "[onCreate] testClass=" + test);
    }

The above code is a typical scenario during development. You create code like this to help debug and test your code. Before releasing the final product, though, you set Config.LOGGING to false, so it doesn't execute. The problem is, this code is still in your application. It makes it bigger, and may cause potential security issues by including code which should never be seen by a snooping hacker.

Shrinking the code solves this problem beautifully. The code is completely removed from the final product, leaving the final package safer and smaller.

Obfuscation

By default, compiled bytecode still contains a lot of debugging information: source file names, line numbers, field names, method names, argument names, variable names, etc. This information makes it straightforward to decompile the bytecode and reverse-engineer entire programs. Sometimes, this is not desirable. Obfuscators such as ProGuard can remove the debugging information and replace all names by meaningless character sequences, making it much harder to reverse-engineer the code. It further compacts the code as a bonus. The program remains functionally equivalent, except for the class names, method names, and line numbers given in exception stack traces.

Optimizing

Apart from removing unused classes, fields, and methods in the shrinking step, ProGuard can also perform optimizations at the bytecode level, inside and across methods. Thanks to techniques like control flow analysis, data flow analysis, partial evaluation, static single assignment, global value numbering, and liveness analysis, ProGuard can do things such as perform over 200 peephole optimizations, like replacing x * 2 with x << 1. The positive effects of these optimizations will depend on your code and on the virtual machine on which the code is executed. Simple virtual machines may benefit more than advanced virtual machines with sophisticated JIT compilers. At the very least, your bytecode may become a bit smaller.

Using Ant to build your project

When you create your Android application, or build it, there are many steps involved. First, a Java compiler compiles the source files (i.e. the textual .java files) into Java bytecode (i.e. .class files). Then, a tool in the Android SDK turns the Java bytecode into Dalvik bytecode (i.e. .dex files). Finally, all of the resources and code are packaged into a single ZIP file, which is an .APK file. Since ProGuard works with Java bytecode, we want to run ProGuard on the class files that are created by the Java compiler, before the build process converts the Java bytecode into Dalvik bytecode. This isn't possible with the regular Eclipse method of creating Android packages (at least, not that I know of), but it's a cinch if you use Ant to build your application. It doesn't take long to create an Ant build script to build your existing Android application. See the instructions on my blog post here. Or, you can just download the sample at the end of this blog.

Adding ProGuard to the Ant build script

Download the latest ProGuard distribution. Inside, find the library, and put it in a convenient location in your project directory, such as proguard/. For example, in the latest version as of this writing (4.5.1 distribution), I copied lib/proguard.jar from the distribution ZIP file into my source tree as proguard/proguard.jar. Now, we add the script to the Ant build file, build.xml.

<!-- ================================================= -->
    <!-- Obfuscation with ProGuard -->
    <!-- ================================================= -->
 
    <property name="proguard-dir" value="proguard"/>
 <property name="unoptimized" value="${proguard-dir}/unoptimized.jar"/>
 <property name="optimized" value="${proguard-dir}/optimized.jar"/>
 
 <target name="optimize" unless="nooptimize">
  <jar basedir="${out.classes.dir}" destfile="${unoptimized}"/>
 
  <java jar="${proguard-dir}/proguard.jar" fork="true" failonerror="true">
   <jvmarg value="-Dmaximum.inlined.code.length=16"/>
   <arg value="@${proguard-dir}/config.txt"/>      
   <arg value="-injars ${unoptimized}"/>
   <arg value="-outjars ${optimized}"/>
   <arg value="-libraryjars ${android.jar}"/>
  </java>     
 
  <!-- Delete source pre-optimized jar -->     
  <!--delete file="${unoptimized}"/-->
 
  <!-- Unzip target optimization jar to original output, and delete optimized.jar -->
  <delete dir="${out.classes.dir}"/>
  <mkdir dir="${out.classes.dir}"/>
  <unzip src="${proguard-dir}/optimized.jar" dest="${out.classes.dir}"/>
 
  <!-- Delete optimized jar (now unzipped into bin directory) -->
  <delete file="optimized.jar"/>
 
   </target>

To have the build call the optimize Ant target between the Java compiler and dex compiler, we change the dex target as so:

Android 7 and below:

<!-- Converts this project's .class files into .dex files -->
<target name="-dex" depends="compile,optimize">

Android 8 and above: Uncomment the -post-compile target, and add this:

<target name="-post-compile">
  <antcall target="optimize"/>
</target>

Configuring ProGuard

Now we'll tell ProGuard how it can work with our Android application. Create a file called proguard/config.txt, which is referenced in the above Ant script. The following is taken from the ProGuard manual, although -libraryjars, -injars, and -outjars is passed in via the Ant build script instead of here.

-target 1.6 
-optimizationpasses 2 
-dontusemixedcaseclassnames 
-dontskipnonpubliclibraryclasses 
-dontpreverify 
-verbose 
-dump class_files.txt 
-printseeds seeds.txt 
-printusage unused.txt 
-printmapping mapping.txt 

# The -optimizations option disables some arithmetic simplifications that Dalvik 1.0 and 1.5 can't handle. 
-optimizations !code/simplification/arithmetic 

-keep public class * extends android.app.Activity 
-keep public class * extends android.app.Application 
-keep public class * extends android.app.Service 
-keep public class * extends android.content.BroadcastReceiver 
-keep public class * extends android.content.ContentProvider 

-keep public class * extends View { 
public <init>(android.content.Context); 
public <init>(android.content.Context, android.util.AttributeSet); 
public <init>(android.content.Context, android.util.AttributeSet, int); 
public void set*(...); 
}

# Also keep - Enumerations. Keep the special static 
# methods that are required in enumeration classes.
-keepclassmembers enum  * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
} 

Note that we have added a few configurations which make extra output, such as -verbose and -printusage unused.txt. You may remove these if you don't like the extra output cluttering your build process.

Results

Now we're ready! When you run ant release from the command line, you will see the optimizer run. Here is the output from the test project, included below, when the build property config.logging is true:

>ant release
...
     [java] Shrinking...
     [java] Printing usage to [blog\obfuscation\proguard\unused.txt]...
     [java] Removing unused program classes and class elements...
     [java]   Original number of program classes: 8
     [java]   Final number of program classes:    2

Because we configured ProGuard with -printusage unused.txt, we can see what was removed from our code:

com.androidengineer.obfu.Obfuscation: 
    private static final java.lang.String TAG 
com.androidengineer.obfu.R 
com.androidengineer.obfu.R$attr 
com.androidengineer.obfu.R$drawable 
com.androidengineer.obfu.R$layout 
com.androidengineer.obfu.R$string 
com.androidengineer.obfu.TestClass: 
    private static final java.lang.String TAG 

That's pretty cool. You can also look at proguard/unoptimized.jar and proguard/optimized.jar. We can see that it removed many classes which were just placeholders for constants, and it removed the string TAG variables used by our logging code by replacing the references with the actual string constants.

In addition, if we build the application by changing the build property config.logging to false, we get an even further reduction in size. The best part about it is, it removes all of our debugging code.

>ant release
...
     [java]   Original number of program classes: 8
     [java]   Final number of program classes:    1

You can see that one more class was removed, TestClass. Because it is only used when Config.LOGGING is true, it is completely removed from the final build during the obfuscation process. So feel free to leave all of the debugging code you want in your source, because it can be removed during the build.

Of course, with our simple test project, our results are skewed, because it is not a typical Android application. proguard/unoptimized.jar is 4,959 bytes and proguard/optimized.jar is 646 bytes. But on an application I work with, which has over a thousand classes, I've seen a literal 50% reduction of code size. Well worth the trouble of setting this build up, in my opinion.

ClassNotFoundExceptions

There may be some cases where you get a ClassNotFoundException when running your application which has been obfuscated with ProGuard. In this case, you need to edit the config.txt file to tell ProGuard to keep the class in question. For example,

# Keep classes which are not directly referenced by code, but referenced by layout files. 
-keep,allowshrinking class com.androidengineer.MyClass 
{ 
*** (...); 
} 

This scenario is rare. I have seen it happen when I reference the child of an Android View class in an Android layout file, such as MyButton extends Button, but the class is not referenced in regular code. More information can be found in the ProGuard documentation.

Update for Android SDK versions 7 and above

Google updated the Ant scripts in the later SDK versions. They changed the name of a key variable, $[android-jar}, to ${android.jar}. This caused the builds to break. The solution is to define them both if they do not exist:

 <!-- In newer platforms, the build setup tasks were updated to begin using ${android.jar} instead of ${android-jar}.  This makes them both compatible. -->
<target name="target-new-vars" unless="android-jar">
<property name="android-jar" value="${android.jar}"/>
</target>

<!-- Be sure to call target-new-vars before anything else. -->   
<target name="config" depends="target-new-vars,clean">

The sample project file below has been updated.

Update for Android SDK versions 8

Well, it turns out Google changed the ant build files again. This time, though, they actually made it pretty darn easy. The build.xml file is much smaller this time. They've added a nifty new section:

<!-- extension targets. Uncomment the ones where you want to 
     do custom work in between standard targets -->
<!--
    <target name="-pre-build">
    </target>
    <target name="-pre-compile">
    </target>

    [This is typically used for code obfuscation.
     Compiled code location: ${out.classes.absolute.dir}
     If this is not done in place, override 
     ${out.dex.input.absolute.dir}]
    <target name="-post-compile">
    </target>
-->

All we have to do is uncomment the -post-compile Ant target, and add our obfuscation Ant target to it.

<target name="-post-compile">
    <antcall target="optimize"/>
</target>

The complete build file is here.

Using Google's License Verification Library (LVL)

For those of you using the Google licensing service, License Verification Library, you will want to keep an additional class from being obfuscated in the additional library. Be sure the following is in your proguard/config.txt file.

-keep class com.android.vending.licensing.ILicensingService

Sample Application

The sample application is a simple Hello World application, but it includes the custom build script and ProGuard library as described in this tutorial. First, you must run "android update project -p ." from the command line in the project's directory to let the tools set the SDK path in local.properties. Then you can turn on and off logging by changing the value of config.logging in build.properties. Finally, run ant release to build the application, which will create the obfuscated and signed .apk file. If you have any trouble, you may want to review the previous blog post about setting up Ant builds.

Project source code - obfuscation.zip (600 Kb)

Build file for Android API level 8 and above:build.xml (4.52 Kb)

Using Ant to Automate Building Android Applications

The standard way to develop and deploy Android applications is using Eclipse. This is great because it is free, easy to use, and many Java developers already use Eclipse. To deploy your applications using Eclipse, you simply right-click on the on the project, choose to export the application, and follow the prompts

There are a few things we cannot easily do with this system, though. Using the Eclipse GUI does not allow one to easily:

• Add custom build steps.
• Use an automated build system.
• Use build configurations.
• Build the release project with one command.

Fortunately, the Android SDK comes equipped with support for Ant, which is a common build script system popular among Java developers. It is how you can develop Android applications without using Eclipse, if you so desire. This tutorial will show you how to incorporate an Ant build script into your Android projects (even if you still develop with Eclipse), create your release package ready for Marketplace deployment in one step, create a build configuration using a properties file, and alter your source files based on the configuration.

You can use the Ant build script to solve all of the problems listed above.  This tutorial expects you to already have your Android SDK setup correctly, and to have Ant installed.  It will also help to know a little about Ant if you want to add custom build steps, but you don't really need to know anything to follow the tutorial here.

Although I don't personally use an automated build system for my projects, I do use it to create configuration files and to run custom build scripts. I also believe that it is very important to have a one-step build system, which means that there is only one command to create your final release package (I'll explain why later). You can already run your application in debug mode with Eclipse with one step, but I feel it is important to be able to create the release package in one step as well.

Finally, if this is too much reading for your taste, you can jump straight into the summary for a few simple steps, and download the sample application at the end of the tutorial.

Ant in a nutshell

A build script in Ant is an XML file.  The default filename for a Ant build file is build.xml. Build steps in Ant are called tasks, which are defined by targets in the build file. When you build your Android application with the default build script, you would type ant release at the command line. In this case, Ant looks for the default filename build.xml, and release is the target which it builds. The release target builds the application ready for release (as opposed to for debugging). Another example would be ant clean, which cleans the project binaries.

You can do pretty much anything you can imagine with more custom build scripts, from copying files to making network calls. More detail about how to use Ant is beyond the scope of this tutorial, but I will show you some useful tricks.

One custom script which I enjoy very much uses ProGuard to obfuscate and shrink the code. I see the code size of my applications drop by a whopping 50% using it. It helps for users who may think your application is taking too much space on their device. I'll explain how to do this in a future tutorial.

Adding build.xml to an existing project

If you already have a project that you'd like to add the Ant build script to, then there is an easy command line tool you can use. Open up a command prompt and navigate to the base directory of your project. From there, use the command:
android update project --path .

Here is an example of successful output:

>android update project --path .
Updated local.properties
Added file C:\dev\blog\antbuild\build.xml

If the android command is not found, then you need to update your path to include the Android tools.  On Windows, you can use something like set path=%PATH%;C:\dev\android-sdk-windows\tools (substituting your actual Android installation directory), or even better add it to your path persistently by updating the environment variables through your system properties.

Now you will have a working ant build script in build.xml.  You can test your setup by typing ant at the command prompt, and you should receive something similar to the following boilerplate help:

>ant
Buildfile: C:\dev\blog\antbuild\build.xml
    [setup] Android SDK Tools Revision 6
    [setup] Project Target: Android 1.5
    [setup] API level: 3
    [setup] WARNING: No minSdkVersion value set. Application will install on all Android versions.
    [setup] Importing rules file: platforms\android-3\ant\ant_rules_r2.xml

help:
     [echo] Android Ant Build. Available targets:
     [echo]    help:      Displays this help.
     [echo]    clean:     Removes output files created by other targets.
     [echo]    compile:   Compiles project's .java files into .class files.
     [echo]    debug:     Builds the application and signs it with a debug key.
     [echo]    release:   Builds the application. The generated apk file must be
     [echo]               signed before it is published.
     [echo]    install:   Installs/reinstalls the debug package onto a running
     [echo]               emulator or device.
     [echo]               If the application was previously installed, the
     [echo]               signatures must match.
     [echo]    uninstall: Uninstalls the application from a running emulator or
     [echo]               device.

BUILD SUCCESSFUL

If the ant command is not found, then you need to update your path. Like above, on Windows use set path=%PATH%;C:\dev\apache-ant-1.8.1\bin (substituting your actual Ant installation directory), or even better update your environment variables.

At this point you should be able to type ant release at the command prompt, which will build the project, placing the unsigned .apk file inside of the bin/ directory.

Note that the output from Ant will show further instructions under -release-nosign: which says to sign the apk manually and to run zipalign.  We'll get to these steps later in the signing section below.

Creating a new project with build.xml

If you've already created your project and followed the above instructions, you can skip this section. If not, you can may either create a new Android project using the regular Eclipse method (via New > Other... > Android Project), and follow the instructions in the above section, or you can use the command line as described here.

android create project --name YourProjectName --path C:\dev\YourProject --target android-3 --package com.company.testproject --activity MainActivity

Here is an example of successful output:

>android create project --name YourTestProject --path c:\temp\TestProject --target android-3 --package com.company.testproject --activity MainActivity

Created project directory: c:\temp\TestProject
Created directory C:\temp\TestProject\src\com\company\testproject
Added file c:\temp\TestProject\src\com\company\testproject\MainActivity.java
Created directory C:\temp\TestProject\res
Created directory C:\temp\TestProject\bin
Created directory C:\temp\TestProject\libs
Created directory C:\temp\TestProject\res\values
Added file c:\temp\TestProject\res\values\strings.xml
Created directory C:\temp\TestProject\res\layout
Added file c:\temp\TestProject\res\layout\main.xml
Added file c:\temp\TestProject\AndroidManifest.xml
Added file c:\temp\TestProject\build.xml

Note: To see the available targets, use android list target and you should see something like:

>android list target
id: 1 or "android-3"
     Name: Android 1.5
     Type: Platform
     API level: 3
     Revision: 4
     Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P

In the above case, you can use either 1 or android-3 as the target ID.  In the sample project, I chose android-4, which corresponds to Android 1.6.

Once the project is created, you can test if your project build is setup correctly by typing ant at the command line.  See the above section for further instructions.

Synchronizing with Eclipse

If you open the Ant build script, build.xml, in Eclipse, you will see an error on the second line of the file at this line: <project name="MainActivity" default="help">.  The problem with this line is that it is saying that the default Ant target is "help", but the actual Ant targets used in the build file are imported from another location, which the Eclipse editor does not recognize. The import is done at the line <taskdef name="setup", which imports Ant files from the Android SDK.

Unfortunately, while this error is active in your project, you cannot debug your project from Eclipse, even though the Ant build.xml is not needed. There are two solutions. You can remove default="help" from the file, which will remove the error in Eclipse. If you do this, and type ant at a command prompt without any targets (as opposed to "ant release"), you won't get the default help.  Or, you can copy the imported Ant files directly into your code, which is exactly what you must do if you would like to customize your build. If you follow this tutorial, you won't have to worry about this error. See the Customizing the build section for more information.

Automatically signing your application

Before an application can be delivered to a device, the package must be signed. When debugging using Eclipse, the package is technically signed with a debugging key. (Alternatively, you can build a debug package using ant debug) For actual applications delivered to the Android Marketplace, you need to sign them with a real key. It is useful to put this step into the build process. On top of the ease of automating the process, it allows you to build your application in one step. (One-step builds are a Good Idea^TM)

If you have not already created a key, you can do so automatically using Eclipse (Right click project > Android Tools > Export Signed Application Package...), or follow the instructions here.

Now we must tell the build script about our keystore. Create a file called build.properties in your project's base directory (in the same directory as build.xml and the other properties files), if it does not already exist. Add the following lines:

key.store=keystore
key.alias=www.androidengineer.com

Where keystore is the name of your keystore file and change the value of key.alias to your keystore's alias. Now when you run ant release, you will be prompted for your passwords, and the build will automatically sign and zipalign your package.

Of course, having to enter your password doesn't make for a one-step build process. So you could not use this for an automated build machine, for one thing. It also has the disadvantage of requiring you to type the password, which it will display clearly on the screen, which may be a security issue in some circumstances.  We can put the passwords into build.properties as well, which will solve the issue:

key.store.password=password
key.alias.password=password

Caution: There can be several issues with storing the keystore and passwords. Depending on your organization's security policies, you may not be able to store the passwords in version control, or you may not be able to give out the information to all developers who have access to the source. If you want to check in the keystore and the build.properties file, but not the passwords, you can create a separate properties file which could only be allowed on certain machines but not checked in to version control. For example, you could create a secure.properties file which goes on the build machine, but not checked in to version control so all developers wouldn't have access to it; import the extra properties file by adding <property file="secure.properties" /> to build.xml. Finally, you could always build the APKs unsigned with ant release by not adding any information to the properties files.  The package built using this method will need to be signed and aligned.

Customizing the build

Now that we've got a working Ant build script, we can create a one-step build. But if we want to customize the build further, we'll have to do a few extra steps. You can do anything with your build that you can do with Ant. There are a few things we'll have to do first.

The Ant targets are actually located in the Android SDK.  The targets are what you type after ant on the command line, such as release, clean, etc.  To customize the build further, we need to copy the imported targets into our own build file.

If you look in build.xml, you can see the instructions for how to customize your build steps:

The rules file is imported from
<SDK>/platforms/<target_platform>/templates/android_rules.xml
To customize some build steps for your project:
  - copy the content of the main node <project> from android_rules.xml
  - paste it in this build.xml below the <setup /> task.
  - disable the import by changing the setup task below to <setup import="false" />

Find the android_rules.xml file in your Android SDK. For example, mine is located at C:\dev\android-sdk-windows\platforms\android-4\templates. There, copy almost the entire file, excluding the project node (copy below <project name="MainActivity"> to above </project>), and paste it in your build.xml file. Also, change the line <setup /> to <setup import="false"/>.

Now you can change around the build as you please. Test that the build file is still working properly by running a build.  For an example of what you can do with the custom build script, see the next section.

Using a Java configuration file

This is a great way to use a build property to affect the source code of your Android application. Imagine a configuration class in your project which sets some variables, such as a debugging flag or a URL string. You probably have a different set of these values when developing than when you release your application. For example, you may turn the logging flag off, or change the URL from a debugging server to a production server.

public class Config
{
    /** Whether or not to include logging statements in the application. */
    public final static boolean LOGGING = true;
}

It would be nice to have the above LOGGING flag be set from your build. That way, you can be sure that when you create your release package, all of the code you used for debugging won't be included. For example, you may have debugging log statements like this:

if (Config.LOGGING)
{
    Log.d(TAG, "[onCreate] Success");
}

You will probably want to leave these statements on during development, but remove them at release.  In fact, it is good practice to leave logging statements in your source code. It helps with later maintenance when you, and especially others, need to know how your code works. On the other hand, it is bad practice for an application to litter the Android log with your debugging statements. Using these configuration variables allows you to turn the logging on and off, while still leaving the source code intact.

Another great advantage of using this method of logging is that the bytecode contained within the logging statement can be completely removed by a Java bytecode shrinker such as ProGuard, which can be integrated into your build script.  I'll discuss how to do this in a later blog post.

A nice way to set the Config.LOGGING flag is in your build properties.  Add the following to build.properties:

# Turn on or off logging.
config.logging=true

To have this build property be incorporated into our source code, I will use the Ant type filterset with the copy task. What we can do is create a Java template file which has tokens such as @CONFIG.LOGGING@ and copy it to our source directory, replacing the tokens with whatever the build properties values are.  For example, in the sample application I have a file called Config.java in the config/ directory.

public class Config
{
    /** Whether or not to include logging statements in the application. */
    public final static boolean LOGGING = @CONFIG.LOGGING@;
}

Please note that this is not a source file, and that config/Config.java is notthe actual file used when compiling the project. The file src/com/yourpackage/Config.java, which is the copied file destination, is what will be used as a source file.

Now I will alter the build file to copy the template file to the source path, but replace @CONFIG.LOGGING with the value of the property config.logging, which is true. I will create an Ant target called config which will copy the above template to the source directory. This will be called before the compile target.

    <!-- Copy Config.java to our source tree, replacing custom tokens with values in build.properties. The configuration depends on "clean" because otherwise the build system will not detect changes in the configuration. -->
<target name="config">

<property name="config-target-path" value="${source.dir}/com/androidengineer/antbuild"/>

<!-- Copy the configuration file, replacing tokens in the file. -->
<copy file="config/Config.java" todir="${config-target-path}"
     overwrite="true" encoding="utf-8">
<filterset>
<filter token="CONFIG.LOGGING" value="${config.logging}"/>
</filterset>
</copy>

<!-- Now set it to read-only, as we don't want people accidentally
    editing the wrong one. NOTE: This step is unnecessary, but I do
    it so the developers remember that this is not the original file. -->
<chmod file="${config-target-path}/Config.java" perm="-w"/>
<attrib file="${config-target-path}/Config.java" readonly="true"/>

</target>


To make this Ant target execute before the compile target, we simply add config to the dependency of compile: <target name="compile" depends="config, -resource-src, -aidl". We also make the config target call clean, because otherwise the build system will not detect changes in the configuration, and may not recompile the proper classes.

Note: The above Ant task sets the target file (in your source directory) to read-only.  This is not necessary, but I add it as a precaution to remind me that it is not the original file that I need to edit.  When developing, I will change the configuration sometimes without using the build, and Eclipse will automatically change the file from read-only for me.  I also do not check in the target file into version control; only the original template and build.properties.

Version control

Do not check in the local.properties file which is generated by the Android build tools. This is noted in the file itself; it sets paths based on the local machine. Do check in the default.properties file, which is used by the Android tools, and build.properties, which is the file which you edit to customize your project's build.

I also don't check in the target Config.java in the source directory, nor anything else is configured by the build. I don't want local changes to propagate to other developers, so I only check in the original template file in the config/ directory.

In my projects, when I release a new version of a project I always check in the properties file and tag it in the source repository with a tag name such as "VERSION_2.0". That way we are certain of what properties the application was built with, and we can reproduce the application exactly as it was released, if we later need to.

Summary

1. At the command line run android create project, or android update project in your project base directory if it already exists.
2. (Optional) Add key.store and key.alias to build.properties if you want to include the signing step in your build.
3. (Optional) Add key.store.password and key.alias.password to build.properties if you want to include the keystore passwords, to make the build run without any further input needed.
4. (Optional) If you would like to further customize the build, copy the SDK Ant build code from <SDK>/platforms/<target_platform>/templates/android_rules.xmlto your local build.xml and change <setup /> to <setup import="false"/>.
5. Use ant release to build your project. It will create the package in bin/.

Sample Application

The sample application is a simple Hello World application, but it also includes the custom build script as described in this tutorial.  It also includes the Config.java which is configurable by the build. First, you must run "android update project -p ." from the command line in the project's directory to let the tools set the SDK path in local.properties. Then you can turn on and off logging by changing the value of config.logging in build.properties. Finally, run ant release to build the application, which will create the signed bin/MainActivity-release.apk file ready to be released.

Project source code - antbuild.zip (13.4 Kb)