Android Application Development with Maven

Android is an open source mobile phone and embedded device operating system developed by the Open Handset Alliance. It is based on a Linux kernel with a virtual machine environment for managed application code using Java bytecode for the runtime code generation. The development environment is based on the Java language and JVM/JDK based tooling. The generated Java bytecode is transformed into Dalvik executable code optimized for constrained devices. Once deployed to the device and executed the code will run on the Dalvik virtual machine. Java is the default programming language and the API’s are all Java based.

In most cases, development of Android applications is done within the Eclipse based Android Studio. The optionally generated Apache Ant based build can be used to build applications outside the IDE. The Android Maven Plugin was created to allow development teams to build, deploy and release Android applications with Apache Maven, taking advantage of all the powerful features available like dependency management, reporting, code analysis and much more.

• 14.2.1. Installing the Android SDK
• 14.2.2. Android artifact install into Maven repository

Before you attempt to build your Android libraries and applications with Maven, you will need to install the Android SDK and potentially install the Android API jar files into your local Maven repository or your repository server.

export ANDROID_HOME=/opt/android-sdk-linux

set ANDROID_HOME=C:\opt\android-sdk-linux

cd mosabua-maven-android-sdk-deployer-df824df
mvn clean install

<settings>
    <servers>
        <server>
            <id>android.repo</id>
            <username>your username</username>
            <password>your password</password>
        </server>
    </servers>
</settings>

mvn install -P 3.2

• 14.3.1. Creating New Projects with the Android Maven Archetypes
• 14.3.2. Using Add-Ons
• 14.3.3. Multi Module Android Projects
• 14.3.4. Using external dependencies

The HelloFlashlight example application serves as a starting point to introduce you to the usage of the Android Maven Plugin. The code for the helloflashlight example application as well as various more complex examples are available as part of the plugin samples project.

To enable a Maven based build of an Android project a pom.xml has to be added in the root folder of the project:

The HelloFlashlight pom.xml file. 

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.simpligility.android</groupId>
    <artifactId>helloflashlight</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>apk</packaging>
    <name>HelloFlashlight</name>

    <dependencies>
        <dependency>
            <groupId>com.google.android</groupId>
            <artifactId>android</artifactId>
            <version>1.6_r2</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <build>
        <finalName>${project.artifactId}</finalName>
        <sourceDirectory>src</sourceDirectory>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>com.jayway.maven.plugins.android.generation2</groupId>
                    <artifactId>android-maven-plugin</artifactId>
                    <version>3.0.0-SNAPSHOT</version>
                    <extensions>true</extensions>
                </plugin>
            </plugins>
        </pluginManagement>
        <plugins>
            <plugin>
                <groupId>com.jayway.maven.plugins.android.generation2</groupId>
                <artifactId>android-maven-plugin</artifactId>
                <configuration>
                    <run>
                        <debug>true</debug>
                    </run>
                    <sdk>
                        <platform>4</platform>
                    </sdk>
                    <emulator>
                        <avd>16</avd>
                    </emulator>
                    <undeployBeforeDeploy>true</undeployBeforeDeploy>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

The highlights of this pom.xml are:

The Android Package packaging type apk is what activates the Android-specific lifecycle modifications of the Android Maven Plugin. It takes care of all the specific calls to the Android SDK tools, that process resources, convert Java bytecode and so on. The Android Maven Plugin needs to be configured with extensions set to true for this to work as visible in the pluginManagement section.

The declared dependency to the android platform jar is available in Maven Central with various platform versions. Alternatively you could use an Android jar from the Maven Android SDK Deployer with the modified groupId and artifactId. The documentation of the deployer shows all valid dependencies.

The scope of provided is important. It signals to Maven that the contents of the jar will not need to be packaged into the application package, because they are available at runtime on the device as part of the environment.

In addition the android jar artifacts only contain exception throwing stubs for all methods in order to define the API for the compiler. They can not be executed on the development machine, but rely on an emulator or device runtime environment.

The configuration of the Android Maven Plugin is done in the build section. Initially only the sdk platform parameter is required to be specified. You can use either a platform version number or a API level number as documented on the Android developer documentation.

To build the application and run it on an already started emulator or attached device you could use

mvn install android:deploy android:run

For many applications the normal Android SDK artifact (android.jar) will be sufficient, however some applications require add-ons. One of the more commonly used add-ons is the Google Maps add-on, which provides access to the Google Maps API. The Maps add-on is deployed to your Maven repository by the Maven Android SDK Deployer tool. To use an add on you just have to add the respective dependency to your pom file.

The dependency to the Google Maps API. 

<dependency>
    <groupId>com.google.android.maps</groupId>
    <artifactId>maps</artifactId>
    <version>7_r1</version>
    <scope>provided</scope>
</dependency>

Another common add-on is the compatibility library. It needs to be included in the produced apk and there does not have provided scope.

The dependency to the compatibility library for API v4 and up. 

<dependency>
  <groupId>android.support</groupId>
  <artifactId>compatibility-v4</artifactId>
  <version>r3</version>
</dependency>

The Android Maven Plugin customizes the lifecycle based on the packaging. If your project has a packaging of type apk the customized lifecycle will be used.

The customized lifecycle has the following additional executions in the default lifecycle.

generate-sources Phase

Use the Android Asset Packaging Tool (aapt) of the platform version specified in the pom to package the Android specific resources like AndroidManifest.xml, assets and resources. Additional parameters can be passed to aapt with the parameter aaptExtraArgs.

process-classes Phase

Run the dx tool of the platform version specified in the pom to convert all classes (libraries, resources and project code) into davlik executable format.

package Phase

Run the Android Package tool (apk) of the Android SDK to create and sign the Android package file (apk) for installation on the emulator or device.

pre-integration-test Phase

Deploy the currently built Android application package (apk) as well as any other dependencies with packaging type apk to the emulator/device.

integration-test Phase

Run the instrumentation test classes against the deployed application.

The Android Maven Plugin supports a large number of configuration parameters. They can typically be passed into the execution as plugin configuration, as properties defined in the pom or settings file or as command line parameters.

An example of a plugin configuration. 

<configuration>
    <sdk>
        <platform>2.1</platform>
    </sdk>
    <emulator>
        <avd>21</avd>
        <options>-no-skin</options>
    </emulator>
</configuration>

Configuration as properties in pom.xml. 

<properties>
    <android.emulator.avd>21</android.emulator.avd>
<properties>

Configuration on command line invocation. 

mvn android:emulator-start -Dandroid.emulator.avd=21

A number of other parameters have defaults that point to the default location as used by the standard Android/Eclipse project layout, but can be customized if desired.

Some of the other useful parameters are

device

Specify usb, emulator or a specific serial number. Read Section 14.6, “Device Interaction” for more information.

undeployBeforeDeploy

This parameter will cause the application as well as the test application to be undeployed from the device before each deployment.

• 14.6.1. Emulator Interaction

The Android Maven Plugin has powerful features for interacting with attached devices and emulators implemented in a number of goals. They use the android.device parameter to determine a specific device as specified by the serial number, all connected emulators or all connected devices should be affected. A value of emulator will trigger execution on all emulators connected via adb and a value of usb will affect all devices.

The following goals support the device parameter and sequential execution against all devices.

android:deploy

The deploy goal deploys the built apk file, or another specified apk, to the connected device(s). This goal is automatically performed when running through the integration-test lifecycle phase on a project with instrumentation tests (e.g. mvn install or mvn integration-test).

android:undeploy

The undeploy goal removes the apk of the current project, or another specified apk, from the connected devices and emulators.

android:redeploy

The redeploy goal executes undeploy and deploy consecutively on all specified devices and emulators.

android:instrument

The instrument goal runs the instrumentation tests after automatically deploying the test application and the tests. It honors the standard Maven skip test properties as well as android.test.skip. It supports a number of further parameters that are explained in more detail in Section 14.9, “Testing Android Application Code”.

android:pull

The pull goal can be used to copy a file or directory from the device. Source and destination file have to be specified with the android.pull.source and android.pull.destination configuration parameters.

android:push

The push goal can be used to copy a file or directory to the device. Configuration is done with the android.push.source and android.push.destination parameters.

android:run

The run goal will start the application on the device. If the run.debug paramter is set to true starting will wait for a debugger to connect.

• 14.7.1. Manifest-update
• 14.7.2. Zipalign
• 14.7.3. Help

A number of plugin goals are useful for manual execution or custom binding to a lifecycle phase e.g. in a release profile.

The Android Maven Plugin supports a number of goals that are part of the default lifecycle and are invoked automatically. In most cases you will not have to invoke these goals directly, but it can be useful to know about them and their configuration options.

android:apk

The apk goal creates the android package (apk) file. By default the plugin signs the file with the debug keystore. The configuration parameter <sign><debug>false<debug><sign> can be used to disable the signing process.

android:deploy-dependencies

The deploy-dependencies goal deploys all directly declared dependencies of <type>apk</type> in this project. This goal is usually used in a project with instrumentation tests, to deploy the apk to test onto the device before running the deploying and running the instrumentation tests apk. The goal is automatically performed when running through the integration-test life cycle phase on a project with instrumentation tests (e.g. mvn install or mvn integration-test).

android:dex

The dex goal converts compiled Java classes to the Android Dalivk Executable (dex) format. The dex execution can be configured with the parameters dex.jvmArguments, dex.coreLibrary, dex.noLocals and dex.optimize.

android:generate-sources

The generate-sources goal generates R.java based on the resources specified by the resources configuration parameter. It generates Java files based on aidl files. If the configuration parameter deleteConflictingFiles is true (which it is by default), this goal has also deletes any R.java files found in the source directory, deletes any .java files with the same name as an .aidl file found in the source directory and deletes any Thumbs.db files found in the resource directory.

android:internal-integration-test

The internal-integration-test goal is called automatically when the lifecycle reaches the integration-test phase. It determines whether to call the goal instrument in this phase based on the existence of instrumentation test classes in the current project. The goal is internal to the plugin lifecycle and should not be used as separate invocation on the command line.

android:internal-pre-integration-test

The internal-pre-integration-test goal is called automatically when the lifecycle reaches pre-integration-test phase. It determines whether to call the goals android:deploy-dependencies and android:deploy in this phase and if necessary invokes them. The goal is internal to the plugin lifecycle and should not be used as separate invocation on the command line.

• 14.9.1. Unit tests
• 14.9.2. Instrumentation tests

Testing Android Application code can be done in a unit test fashion with rich junit support as part of the Android SDK as well as integration type testing called instrumentation testing.

<build>
    <testSourceDirectory>test</testSourceDirectory>
    ...

<dependency>
    <groupId>com.simpligility.android</groupId>
    <artifactId>intents</artifactId>
    <version>0.1</version>
    <type>apk</type>
</dependency>

<test>
  <skip>true|false|auto</skip>
  <instrumentationPackage>packageName</instrumentationPackage>
  <instrumentationRunner>className</instrumentationRunner>
  <debug>true|false</debug>
  <coverage>true|false</coverage>
  <logonly>true|false</logonly>  avd
  <testsize>small|medium|large</testsize>
  <createreport>true|false</createreport>
  <classes>
    <class>your.package.name.YourTestClass</class>
  </classes>
  <packages>
    <package>your.package.name</package>
  </packages>
</test>

The Android Maven Plugin supports building application that include native code as well. Define the environment variable ANDROID_NDK_HOME to point to the required Android NDK installation and have a look at the native projects in the samples of the plugin for more details.

• 14.11.1. Other Maven Plugins
• 14.11.2. Performing a Release Build
• 14.11.3. Configuring command line usage

<pluginGroups>
    <pluginGroup>
        com.jayway.maven.plugins.android.generation2
    </pluginGroup>
</pluginGroups>