zutubi android ant

Contents

Introduction

Zutubi Android Ant is a collection of Ant tasks we've found useful for Android projects. The Android SDK uses Ant for command-line builds, providing a base build file with standard targets. These tasks are intended to supplement the SDK tooling, making it easier to expand your command line builds to cover release management, testing and continuous integration.

For the Impatient

Just want to get started? Refer to the quick start instructions on the project home page.

License

This code is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Importing the Tasks

Obtaining the Jar

First you will need to obtain a release jar file containing the tasks. You can build from source (see below), but it's probably easier to just grab the latest jar from the downloads page. You can also grab the latest release build directly from our Pulse build server (click on "jar" in the "featured artifacts" table on the right of the page.)

Adding to Your Build

The tasks are packaged as an antlib. To use the tasks in your build, you need to define a namespace with an antlib: URI, and make sure the zutubi-android-ant jar is in your Ant classpath. The easiest way to achieve the latter is by adding the jar into your source tree and importing it using the Taskdef task.

An example makes this a lot clearer. In your build.xml (or custom_rules.xml) file, edit the root <project> element to define the namespace prefix:

<project name="my-android-project"
         xmlns:zaa="antlib:com.zutubi.android.ant">
Then nested within this element, add a taskdef that points to the zutubi-android-ant jar and matches the URI:
<taskdef uri="antlib:com.zutubi.android.ant"
	 resource="com/zutubi/android/ant/antlib.xml"
	 classpath="path/to/zutubi-android-ant.jar"/>
Replace path/to/zutubi-android-ant.jar with the path of the jar in your source tree (relative to the build file). Now all of the tasks are available under the zaa: prefix (this prefix is arbitrary but we adopt it throughout the documentation).

Tasks

Available tasks are described below:

addusedpermission

Description

Adds a <uses-permission> element to an Android manifest file, referencing a specified permission. This can be used, for example, to temporarily add permissions during development for testing. The task attempts to add the element just after existing uses-permission elements with the same indent.

Attributes

Attribute Description Required
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)
permission The name of the permission to add, e.g. android.permission.INTERNET. yes

Nested Elements

None.

Example

<target name="allow-internet">
    <zaa:addusedpermission permission="android.permission.INTERNET"/>
</target>

bumpversion

Description

Increments the versionCode attribute of a manifest file, and optionally the versionName attribute. As the versionName is an arbitrary string, it can only be incremented if it uses a dotted-decimal format (e.g. 1.4.1).

Attributes

Attribute Description Required
bumpname If true, the last element of a dotted-decimal version name will also be incremented. no (defaults to false)
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)

Nested Elements

None.

Example

<target name="bump">
    <zaa:bumpversion bumpname="true"/>
</target>

getversion

Description

Captures the values of the versionCode and versionName of a manifest file to Ant properties. These may then be used in the build (either directly in the Ant file or by echoing the values).

Attributes

Attribute Description Required
codeproperty The name of the Ant property to set with the versionCode value. no (defaults to versionCode)
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)
nameproperty The name of the Ant property to set with the versionName value. no (defaults to versionName)

Nested Elements

None.

Example

<target name="version">
    <zaa:getversion/>
    <echo message="Version is ${versionName} (code ${versionCode})."/>
</target>

jsonversion

Description

Outputs a JSON file suitable for use with cwac-updater, in particular the SimpleHttpVersionCheckStrategy (this JSON file could be served by a HTTP server for use by that strategy).

Attributes

Attribute Description Required
jsonfile Path of the JSON output file. yes
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)
updateurl Value of the updateURL field to output in the JSON file. yes

Nested Elements

None.

Example

<target name="json">
    <zaa:jsonversion jsonfile="update.json"
                     updateurl="http://example.com/myapp/versioncheck"/>
</target>

libproperties

Description

Generates .properties files alongside library .jar files that point to the source jars for those libraries. This allows the ADT tools to link the library to the sources in Eclipse. This task is set up by default to link a jar libs/alib.jar to sources at libs/src/alib-sources.jar (if the sources are found).

The ability to link sources to libraries in Eclipse is not well known, and is a bit annoying to configure. With this task you can establish a convention for source jars so you don't have to manually create properties files every time. You can also enforce that all libraries have sources available if you like.

Attributes

Attribute Description Required
failOnMissingSrc If true, the build will be failed if a library jar is found with no corresponding sources jar. no (defaults to false)
jarPattern A regular expression used to identify library jars. All files in the libraries directory with names that match this pattern are taken as jars. This pattern typically includes capturing groups for reference in srcReplacement. no (defaults to (.+)\.jar i.e. all .jars capturing the name)
libDir Path, relative to the base of the build, of the directory containing the library jars. no (defaults to libs)
srcReplacement A replacement string used to generate the path of a source jar from the name of the corresponding library jar. Typically the replacement references groups captured by jarPattern. no (defaults to src/$1-sources.jar)

Nested Elements

None.

Example

<target name="link-sources">
    <-- libs/alib-1.3.jar maps to libs/src/alib-src-1.3.jar -->
    <zaa:libproperties failOnMissingSrc="true"
                       jarPattern="(.+)-([0-9.]+)\.jar"
                       srcReplacement="src/$1-src-$2.jar"/>
</target>

lint

Description

An extension of the Ant exec task that makes it easy to run the lint tool based on the sdk.dir peroperty value and the host operating system. If sdk.dir is not set (which would be unusual for an Android project), the task tries to run lint anyway, and it must be on the PATH.

Attributes

All attributes for the exec task are supported, but the executable attribute is not required: the main purpose of this task is to set it for you.

Nested Elements

All elements for the exec task are supported. You are most likely to want to specify commmand-line arguments with nested <arg> elements.

Example

<target name="lint">
    <zaa:lint>
        <arg line="--disable UnusedIds --html reports/lint.html"/>
    </zaa:lint>
</target>

ndkbuild

Description

An extension of the Ant exec task that makes it easy to run ndkbuild based on ndk.dir and the host operating system. If ndk.dir is not set (it normally would be if you have native code), the task tries to run ndkbuild anyway, and it must be on the PATH.

Attributes

All attributes for the exec task are supported, but the executable attribute is not required: the main purpose of this task is to set it for you.

Nested Elements

All elements for the exec task are supported. You are most likely to want to specify commmand-line arguments with nested <arg> elements.

Example

<target name="rebuild-native">
    <zaa:ndkbuild>
        <arg line="-B V=1"/>
    </zaa:ndkbuild>
</target>

removeusedpermission

Description

Removes all existing <uses-permission> elements that reference a specified permission from an Android manifest file. This can be used, for example, to remove permissions used during development before publishing your application. The task attempts to also remove the newline and indent that precede the elements to preserve decent formatting.

Attributes

Attribute Description Required
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)
permission The name of the permission to remove, e.g. android.permission.INTERNET. yes

Nested Elements

None.

Example

<target name="strip-internet">
    <zaa:removeusedpermission permission="android.permission.INTERNET"/>
</target>

setmanifestattributes

Description

Sets arbitrary attributes on the <manifest> element in a manifest file. The attributes need not exist already, if not they will be added.

Attributes

Attribute Description Required
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)

Nested Elements

attribute element
Attribute Description Required
name Name of the attribute to set. yes
value Value of the attribute to set. no (defaults to the empty string)

Example

<target name="enabledebug">
    <zaa:setmanifestattributes>
        <attribute name="android:debuggable" value="true"/>
    </zaa:setmanifestattributes>
</target>

setversion

Description

Sets the versionCode and/or the versionName attributes in a manifest file. The code can optionally be generated based on the version name, provided you are using dotted-decimal names. To enable this, set code to "auto" and the code will be generated by combining the elements of the dotted version, multiplying by a configurable factor (1000 by default) based on the position of the element. For example, with the default factor, the version name 2.0.42.3 would generate code 2000042003. As long as each individual version element does not exceed the multiplier, this scheme ensures each version name generates a unique code and higher versions get higher codes.

Attributes

Attribute Description Required
code If set, the new value of the versionCode attribute. If set to "auto", the code is generated based on the dotted-decimal version name and the codemultiplier. no
codemultiplier The factor by which to multiply each element of a generated version code based on its position. When generating a code, each element of the version name is multiplied by codemultiplier^i, where i is the index of the element starting from zero for the least significant element, then added together. no (defaults to 1000)
manifestfile Path, relative to the build file, of the manifest file to edit. no (defaults to AndroidManifest.xml)
name If set, the new value of the versionName attribute. no

Nested Elements

None.

Example

<target name="update-version">
    <zaa:setversion code="10" name="1.0"/>
</target>

Building From Source

If you would like to modify the runner, or build it yourself for any other reason, you will need:

  • A JDK, version 1.5 or later.
  • Apache Ant version 1.7 or later.

To compile and package as a jar run:

$ ant jar
The jar will appear under target/dist.

More ant targets are available, for details run:

$ ant -p
The build uses the Ant Script Library for those that wish to understand further.

Feedback

If you have any thoughts, questions etc about the tasks, you can contact me at:

jason@zutubi.com

Or you can submit an issue or pull request via GitHub. All feedback is welcome.