Novoda

Continuous feedback on how our changes affect the current code allow us to confidently add functionality. Documentation around testing on the Android platform continuous or otherwise is scarce so here we explain how to continuously compile your Android project’s tests in a central area for the benefit of the whole team and it’s clients.

The main components of our continuous integration system are:

Here we wish to share and document our set up and explore some capabilities of the android maven plugin. If you are brand new to it you may wish to first check out Maven in 5 minutes and maven-android-plugin’s useful Getting Started guide.

Android maven plugin helps us with the following android deployment tasks:

We want to show you a real example of an application built with the help of the maven-android-plugin. It’s an Avatar Creator app for WeeWorld.

The app is now on the market, so go ahead and check it out! (0.99$)

If you’re quite familiar with maven and the android plugin, you might want to jump straight to the Real Life Example at the end of this post and check out the full configuration.

Building your App

To buid an apk, your app first needs to cite a version of android platform as a build path dependency in your application’s pom file (as provided scope). More on dependency scope.

<dependency>
  <groupId>com.google.android</groupId>
  <artifactId>android</artifactId>
  <version>2.2.1</version>
  <scope>provided</scope>
  <type>jar</type> <!-- optional -->
</dependency>
<!--Currently valid values: 1.5_r3,1.6_r2,2.0_r1,2.0.1_r1,2.1_r1,2.2.1-->
<!--Those packages are on the maven central repository-->

The project must then reference the maven android plugin within the project’s pom along with the android API level targeted, here we cite version 2.2 (api level 8 )

<plugin>
  <groupId>com.jayway.maven.plugins.android.generation2</groupId>
  <artifactId>maven-android-plugin</artifactId>
  <configuration>
    <sdk>
      <platform>8</platform>
    </sdk>
    <deleteConflictingFiles>true</deleteConflictingFiles>
  </configuration>
  <extensions>true</extensions>
</plugin>

Reference a java compiler version, since the default source and target values are 1.3 and 1.1 respectively, and android uses annotations conforming to java 5

<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <source>1.5</source>
    <target>1.5</target>
  </configuration>
</plugin>

If your project uses Any android platform plugins for instance Google maps, additional dependencies will also require referencing in the project’s pom:

<dependency>
  <groupId>com.google.android.maps</groupId>
  <artifactId>maps</artifactId>
  <version>8_r1</version>
  <type>jar</type>
</dependency>
<!-- Current versions:  3, 4_r2, 7_r1, 8_r1 -->
<!-- NOTE: those are the ones defined by goole and are  NOT in the maven
central repository and need to be installed manually with:
mvn install:install-file wih proper parepeters as decribed here:

http://maven.apache.org/plugins/maven-install-plugin/usage.html

e.g. mvn install:install-file
-Dfile=$ANDROID_HOME/add-ons/addon_google_apis_google_inc_8/libs/maps.jar
-DgroupId=com.google.android.maps -DartifactId=maps -Dversion=8_r1
-Dpackaging=jar -->

Additionally one should remember to specify the source directory if the folder structure does not follow the default maven structure:

<sourceDirectory>${project.basedir}/src</sourceDirectory>

At the same time remember NOT to specify the resource directory, as maven-android-plugin handles Android-specific resources on its own, and we don’t wnt duplicates.

This will already get your project building, but there’s much more that maven can do for You. Let’s look at some of that now.

Testing your App with an Instrumentation

You most hopefully have an accompanying instrumentation test instrumentation project for your Android application and maven can build and run these against your previously compiled project. Maven can build the test project, deploy both the app and the test, and run the instrumentation on an attached device or an emulator.

Within the instrumentation test project it will need the following dependency:

<dependency>
   <groupId>com.google.android</groupId>
  <artifactId>android-test</artifactId>
  <version>2.2.1</version>
</dependency>
<!-- Allowed values same as for android package -->
 

If it depends upon the source code of the application which it tests:

<dependency>
  <!-- optional: compile time dependency, in this case so that we can -->
  <!-- read from the R.java for example. -->
  <groupId>my.app.group</groupId>
  <artifactId>myapp</artifactId>
  <version>${project.version}</version>
  <scope>compile</scope>
  <type>jar</type>
</dependency>

Instrumentations are run through a series of interactions within a pseudo environment so you will need to specify the Device/AVD(Android virtual Device) upon which you wish to run tests:

<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>maven-android-plugin</artifactId>
  <configuration>
  <emulator>
    <avd>22</avd>
    <!-- name of the avd to deploy to and run the instrumentation on -->
    <wait>150000</wait> <!-- wait time for the emulator to start -->
    <options>-partition-size 128 -wipe-data</options>
    <!-- additional options to run the emulator with-->
  </emulator>
  <undeployBeforeDeploy>true</undeployBeforeDeploy>
</configuration>

Devices to deploy to can be specified by a serial number but generic “usb” and “emulator” values are also valid. More detailed documentation can be found here.

Instrumentation environment

Instrumentations can interact at various hook in points during the a devices connected lifecycle. Execution and binding it to a maven lifecycle phase is specified like:

<executions>
  <!-- android plugin execution that starts the emulator. -->
  <execution>
    <id>startemulator</id>
    <!-- bound to the 'initialize' phase -->
    <phase>initialize</phase>
    <goals>
      <goal>emulator-start</goal>
    </goals>
  </execution>
</executions>

The configuration above binds the android plugin’s ‘emulator-start’ goal to the ‘initialize’ phase of the maven lifecycle. This is the equivalent of manually executing mvn android:emulator-start, from a directory with a pom containing valid configuration for it. Stopping the emulator does not require this and can be run anywhere and anytime with mvn android:emulator-stop.

If we would like to stop the emulator after running the instrumentation tests, we would add the following execution:

<execution>
  <!-- android plugin execution that starts the emulator. -->
  <id>stopemulator</id>
  <!-- bound to the 'install' phase -->
  <phase>install</phase>
  <goals>
    <goal>emulator-stop</goal>
  </goals>
<execution>

Signing your release

By default, the plugin will sign the apk with the debug key. This can be disabled, producing an unsigned apk.

<configuration>
  <sign>
    <debug>false</debug>
  </sign>
<configuration>

To sign and apk with your key, we will need to use the maven-jarsigner-plugin. Although it’s a different plugin, since it’s very relevant here’s how we did it:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jarsigner-plugin</artifactId>
  <version>1.2</version>
  <executions>
    <execution>
      <id>signing</id>
      <goals>
        <goal>sign</goal>
      </goals>
      <phase>package</phase>
      <inherited>true</inherited>
      <configuration>
        <includes>
          <include>
${project.build.directory}/target/${project.artifactId}-${project.version}.apk
          </include>
        </includes>
        <keystore>${keystore.location}</keystore>
        <storepass>${keystore.password}</storepass>
        <keypass>${keystore.keypass}</keypass>
        <alias>${keystore.alias}</alias>
        <verbose>true</verbose>
      </configuration>
    </execution>
  </executions>
</plugin>

Configures the jarsigner plugin with the files (input, output), and the keystore details. Binds the plugin’s ‘sign’ goal to the ‘package’ phase of the maven lifecycle.

The ${kestore.*} variables above come from the settings.xml file, and look:

<properties>
  <keystore.location>path/to/test.keystore</keystore.location>
  <keystore.password>teststorepass</keystore.password>
  <keystore.keypass>testpass</keystore.keypass>
  <keystore.alias>testkey</keystore.alias>
</properties>

Optimization .apk files via zipalign.

The last stage of a deployment, but also very important is zipaligning the apk after it’s been signed. This aligns archived data in such a way that upon runtime memory can more efficiently store the related data. After this your apk is ready to go to the market. our configuration:

<plugin>
  <groupId>com.jayway.maven.plugins.android.generation2</groupId>
  <artifactId>maven-android-plugin</artifactId>
  <configuration>
    <zipalign>
      <verbose>true</verbose>
      <skip>false</skip><!-- defaults to true -->
      <inputApk>
    ${project.build.directory}/${project.artifactId}-${project.version}.apk
      </inputApk>
      <outputApk>
    ${project.build.directory}/${project.artifactId}_v${project.version}.apk
      </outputApk>
    </zipalign>
  </configuration>
  <executions>
    <execution>
      <id>zipalign</id>
      <phase>verify</phase>
      <goals>
        <goal>zipalign</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Configures the plugin for the zipalign goal and binds that goal the the ‘verify’ phase of the maven lifecycle.

Real Life Example

The above describes taking full control over how maven-android-plugin builds and tests your android application. In reality though, one wouldn’t really use all of the above settings in one pom. Here’s an example of a fully-configured real-life project using ALL of the above:

The project makes use of a parent-child structure and maven profiles to manage both App and Instrumentation projects and handle different cases of builds. Feel free to have a look and se how we’ve done it. For more guides and tips about android development and continuous integrations check back to our blog – we’ll have something here soon!

Topics to expect:

References:

maven-android-plugin site, the Getting Started guide and their wiki page.
Installing a specific file into a local maven repository
Signing apk files with maven
Zipalign apk files with maven-android-plugin

Other relevant and important resources:

Maven: The complete reference book and it’s Android Chapter

A vanilla android installation is a bare bones affair aimed solely at the mobile device. This comes at the initial expense of our development environment. This platform is only intended for only the smallest devices and so searching amongst ‘system/bin‘ reveals only a cherry picking of Linux system administrator staples, even the most common binaries such as ‘ls‘, ‘mv‘ and ‘rm‘ have been stripped of all but their essential options and recompiled. Installing third party tools on Android offers a range of additional productive tools and options for ease of development within the Android shell.

Android shell

Invoking the android emulator from within an IDE is the ideal setup but developers will find need to interact with the emulator through other means for scripting, integration testing and just practical reasons. The SDK tools are located in the tools directory and I’d recommend regular users of the sdk to add this directory to their shell’s export path.

I develop on a mac so I have added the android-sdk-mac_x86-1.0_r1/tools to my .profile but you could equally add it to your .bashrc or .kornrc within your user’s home area giving you convenient direct access to all of android’s development tools via the binary names such as $adb, $emulator or $ddms. If you are on a windows machine these variables would instead be set via your system settings -> environment variables.

With the tools on the shells $PATH, the emulator can now be invoked:

$emulator

Now to telnet to the running device image:

$adb shell

BusyBox

BusyBox is a single multicall binary that packages the functionality of many popular standard Unix tools. The aim of the BusyBox project is to keep the total package size overhead as small as possible by sharing commonly used gnu libC libraries via a single set of ELF headers and stripping down gnu’s libc so as only to provide the functions necessary to support Busybox and the other executables.

Side note – Standing up for GNU with legal action

Busybox author’s have gained a reputation for their commendable efforts to uphold the legal rights of the GNU public license as they have brought about court action as plaintiffs on a series of cases where they believed companies were not holding to the terms of GNU public license. Companies they have appealed against include Verizon, High-Gain Antennas and Xterasys. Most notably they are commonly credited with the first GNU public licence related court action against Monsoon Multimedia for their use of BusyBox within it’s HAVA streaming video software (Hava have since made their alterations available). So far all cases have been settled before they reached the court.

Installing busy box on Android

It is common place for developers to check out the source of BusyBox and compile a tailor made build with any preferred tools and options. There are others like myself who just use whatever they can find and I have settled with a build generously donated with the intent of android deployment by Ben Leslie available from both his site and the run buddy code wiki.

First aquire your build and then add it to the running android device like so:

$adb shell mkdir /data/busybox
$adb push busybox /data/busybox
$adb shell

Now within the android Emulator shell:

$cd /data/busybox
$chmod 775 busybox
$./busybox –install

Now you have installed BusyBox!

For ease of use I would add this to the shell’s $PATH

export PATH=/data/busybox:$PATH

Now invoking busybox will reveal all your new commands!

$busybox

Some highlights of this particular binary of BusyBox are:
chown, chgrp: change permission ownership.
awk, sed: languages to both process & transform text
grep: a text search utility
du: shows disk usage
vi: a shell based text editor
pidof: return the pid of a running process
less: text reader with back and forward nav
tail: trail the end of a file for activity
gunzip, gzip, tar, bzip2: archival compression software
clear: clear screen
crontab, crond: task scheduling
diff: compare files
httpd: a light webserver
telnet: basic TCP remote login
xargs: use the output of a command as the arguments for another
su: masquerade as another system user
wget: retrieves content from a web server
which: identifies the location of an executable
For info on these or any linux commands check the man pages online.

Have I missed any of your shell essentials? If you have any BusyBox builds for Android then we’d love to hear about how you are using them in your development environment.

Android SDK at time of writing was: android-sdk-mac_x86-1.0_r1

Citations & Research

• http://www.busybox.net/
• Official Busy box documentaion
• Busy box Source code repository
• I sourced the build of BusyBox from Ben Leslie’s site – Thanks!
• BusyBox article on dev works by M. Tim Jones
• An Animated guide to BusyBox
• Busybox takes another step up GPL protection ladder
• GPL lawsuits: A reason to rejoice(?), not panic
• Do the Busybox cases change anything?