Usage

In addition to these instructions, you can refer to this simple real-world example build script that uses the Rectangular Antlib. For a more complicated example that shows how to build multiple version of the same app, see this build.xml file.

Add the Rectangular Antlib JAR and Dependencies

Currently (version 1.x), Rectangular Antlib expects to be added to the project’s lib/compiletime directory with its dependencies in their own sub-directories. This restriction is likely to be removed in a subsequent version.

Set the Antlib Namespace and Project Name

Add the Android namespace to the root project element (you can use any namespace identifier you choose, it doesn’t have to be “android”):

<project name="myapp" xmlns:android="antlib:com.rectangularsoftware.antlib">

Note that, by default, the name you assign to the name attribute of the <project> element will be used to name project artifacts unless overridden for individual macros.

Load the Macros

<taskdef uri="antlib:com.rectangularsoftware.antlib"
classpath="${lib.compiletime}/rectangular-antlib-1.0.jar"/>

Set the Build Properties

The Rectangular Antlib requires a number of properties to be set in order for the macros to function correctly. For the majority of these properties you can simply accept the default values, which are set to conform to the default Antlib conventions. However, there are certain properties that don’t have default values and must be set explicitly.

<property name="sdk.dir" value="/Users/dan/Development/android-sdk-macosx"/>
<property name="target" value="android-18"/>
<!-- Key store properties are required to generate release builds. -->
<property name="key.store" value="/Users/dan/android.keystore"/>
<property name="key.alias" value="Android">

In practice, some of these properties, such as sdk.dir, may vary between developers on the same team, so you may not want to specify them directly in build.xml but instead have each developer set them in a local.properties file, which will be automatically read by the Antlib if it exists.

Use the Macros

<android:clean />
<android:resources />
<android:compile />
<android:jar />
<android:test mincoverage="80" />
<android:obfuscate />
<android:package-release />

This example will delete any existing build artifacts, generate the required R.java source file, compile all sources and test sources (with a classpath that includes any JARs in the lib directory) and build a file called “myapp.jar”. It then runs the unit test suites specified by “testng.xml”, generating test and coverage HTML reports. The build will fail if any of the tests fail or if branch or line coverage is below 80%.

Assuming the tests pass, the previously generated JAR file will be obfuscated and a release APK file built (if your release keystore is password protected, as it should be, you will be prompted for the password). Alternatively, you can generate a debug APK using the package-debug macro (this won’t prompt for a password as it will use the debug keystore), in which case you will probably want to omit the obfuscation step.

You can arrange these macro calls into separate targets as you see fit and/or insert other Ant task invocations in between. However, you will probably want to perform the steps in the order shown above. In particular, the resources macro should be called prior to compilation and it is necessary to invoke jar before any of the subsequently listed macros. You may choose to omit obfuscation or to perform tests after building the APK.

Most of the macros support attributes for customising the build to fit your needs. If you don’t specify any attribute values you will get the default behaviour, which is suitable for the majority of projects.