Building Android projects from command line using Ant

S. Gökhan Topçu

gtopcu@gmail.com

Eclipse is undoubtedly the most popular way of compiling and building Android projects. It's free, and most Java developers have been using it for years already. But it lacks the capabilities like using customizable, automated build steps, using build configurations and building the release project with a single command. Ant, which is an automated build script can be used to solve these issues and help developers automate building of even large, custom projects in environments where strict versioning controls are also in place.

To be able to compile your project using Ant, you need to follow these simple steps:

A. Java
1. Download and install proper JDK and JRE
2. Add JAVA_HOME environmental variable pointing to your JDK folder
3. Add your <JDK>/bin directory to your Path to be able to use command java from the command line without having to navigate to your <JDK>/bin location

Check: Run java -version from your command prompt, now you should be able to see your java version:

B. Android SDK
1. Download and install Android SDK
2. Install the latest Android SDK tools and Android SDK platform tools from Android SDK manager
3. Install the Android SDK plattform you will be using to develop your project, such as Android 2.3.3(API 10) from Android SDK manager.
4. Add your <SDK>/tools and <SDK>/platform-tools directories to your Path to be able to use commands such as android and adb from the command line without having to navigate to your SDK location

Check 1: Run android from your command prompt, SDK manager should pop-up. You should see SDK tools, platform tools and tools installed from steps 2 and 3:

Check 2: Run adb devices from your command prompt, you should be able to see your Android devices connected:

C. Ant
1. Download the binary Ant distribution and unpack it to any folder you like
2. Add ANT_HOME environmental variable pointing to your Ant folder
3. Add <ANT>/bin  directory to your Path to be able to use the command ant from the command line without having to navigate to your Ant location

Check: Run ant from your command prompt, ant should fail with the error "build.xml not found" if you're not already in a project directory that has an ant build script.

You can also run ant -version to see the Ant version you're using.


Creating and building an Android project with Ant
Now that we have our build environment set up, we can create and build our first project from the command line. To create a new Android project, open command prompt and type:

android create project --name TestProject --activity TestActivity --package com.yourdomain --path /TestProject --target "android-10"

where;
--name : Name of your project
--activity: Name of your main activity
--package: Package Name
--path: Project path (will be created if it doesn't exist)
--target: Android SDK which your project will be compiled against.

Android SDK targets available (which you installed using Android SDK manager) can be found using android list targets (your output may be different than mine if you've installed a different set of SDKs):

If all is well, you should now be able to see the directory you've specified using --path with the Android project files which are listed in the command output. android create project command sets-up a base project for you with the minimum set of files required.

Now that we have a test project in place, we can now use Ant to build our project. Navigate to your newly created project directory and run ant release to build your release project using Ant:

If you can see BUILD SUCCESSFUL at the end of the lengthy Ant output, then you have successfully created and built your first Android project using Ant from command line. If you navigate to /bin folder in your project, you will see an unsigned APK file (ex. Test-release-unsigned.apk) ready to be installed to Android devices. Congratulations!


What's Next
Ant is a very flexible build framework that will let you modify and automate your build processes in many ways. In our newly created project directory, you will see a build.xml file. If you open it, you will see:

<import file="${sdk.dir}/tools/ant/build.xml"/>

as the last tag before file end. If you look closer, sdk.dir is also a variable defined in file local.properties also located under the project path and imported in build.xml:

<property file="local.properties"/>

which in turn points to your Android SDK installation:

sdk.dir=C:\\Users\\hukanege\\Java\\lib\\Android\\android-sdk-windows
(yours will vary based on your SDK installation dir)

As you can see, Ant uses build.xml files and executes the statements and rules listed to build your projects. For Android projects, the local build.xml file references the global android-sdk/tools/ant/build.xml file for instructions. Build steps in Ant are called tasks, and tasks are defined by targets defined in the global build file. In our case, we built for a release target, but we could also be using ant debug for a debug build. An ant clean command would also clean your project binaries.

Using Ant to build your projects, you can include and automate custom tasks which include:
1. Using ProGuard to obfuscate and compress your code
2. Make network calls, include other files, inject custom classes etc.
3. Sign your project automatically using a keystore
4. Create and set configuration variables in a Java class which you can then use at runtime

Using Ant for Android projects, you will be able to have the same capabilities you have while using Ant to build any regular Java project.

Further Reading:
Managing Projects from the Command Line
Building and Running from the Command Line
Apache Ant Manual