Skip to content

Commit

Permalink
Add the tutorial on the Android and Apklib supports.
Browse files Browse the repository at this point in the history
  • Loading branch information
@gallandarakhneorg
gallandarakhneorg committed Nov 19, 2013
1 parent 9cef8a3 commit 615b64d
Showing 1 changed file with 220 additions and 0 deletions.
220 changes: 220 additions & 0 deletions neteditor-androidpanel/howto-apk_apkplib_with_maven_eclipse.textile
View file
@@ -0,0 +1,220 @@
h1=. HOW TO COMPILE APK/APKLIB WITH MAVEN

p>. Version: 2013-06-01
Author: "Stéphane Galland":http://www.arakhne.org/homes/galland.html

This file explains how to compile Apk or Apklib on CLI with Maven and how to do the same thing inside Eclipse IDE.

h2. 1. How to compile Apk/Apklib on CLI with Maven?

It is assumed that you want to create a Apk/Apklib using Maven. You must create the correct directory/file structure for your Maven project.

h3. 1.1. General Properties

To have a unique location where to update parameters for the Android plugins, I recommend to define the following properties in you @pom.xml@:

<pre><code><properties>
...
<android.sdk.path>/opt/android-sdk</android.sdk.path>
<android.platform>15</android.platform>
<android.emulator>acer500</android.emulator>
...
</properties></code></pre>

h3. 1.2. Adding dependencies to Android API

To compile you Apk/Apklib, you need to be dependent on the Android API. Add the following dependencies in your @pom.xml@. The first is mandatory, second is usefull for compatibility purpose.

<pre><code><dependencies>
...
<dependency>
<groupId>com.google.</groupId>
<artifactId>android</artifactId>
<scope>provided</scope>
<version>4.1.1.4</version>
</dependency>
<dependency>
<groupId>com.google.android</groupId>
<artifactId>support-v4</artifactId>
<version>r7</version>
</dependency>
...
</dependencies></code></pre>

The provided version numbers may be not the last available versions. Please find the last version number from "The Central Repository":http://search.maven.org.

h3. 1.3. Maven Plugin Configuration

You add and configure the android-maven-plugin to generate the correct Apk/Apklib files. Add the following code in the @pom.xml@; and update it according to your configuration.

<pre><code><build>
<plugins>
...
<plugin>
<groupId>com.jayway.maven.plugins.android.generation2</groupId>
<artifactId>android-maven-plugin</artifactId>
<version>3.6.0</version>
<configuration>
<androidManifestFile>${project.basedir}/AndroidManifest.xml</androidManifestFile>
<assetsDirectory>${project.basedir}/assets</assetsDirectory>
<resourceDirectory>${project.basedir}/res</resourceDirectory>
<nativeLibrariesDirectory>${project.basedir}/native</nativeLibrariesDirectory>
<deleteConflictingFiles>true</deleteConflictingFiles>
<undeployBeforeDeploy>true</undeployBeforeDeploy>
<sdk>
<path>${android.sdk.path}</path>
<platform>${android.platform}</platform>
</sdk>
<emulator>
<avd>${android.emulator}</avd>
</emulator>
</configuration>
<extensions>true</extensions>
<!-- Update the Manifest according to currenty Maven configuration -->
<executions>
<execution>
<id>update-manifest</id>
<phase>process-resources</phase>
<goals><goal>manifest-update</goal></goals>
<configuration>
<manifest>
<versionCodeUpdateFromVersion>true</versionCodeUpdateFromVersion>
</manifest>
</configuration>
</execution>
</executions>
</plugin>
...
</plugins>
</build></code></pre>

The @execution@ section above permits to the @android-maven-plugin@ to automatically update the version code of your project according to the version of your project.

h3. 1.4. Type of Maven module

Change the type of the project in @pom.xml@ according to the type of your project:
* For Apk: @<packaging>apk</packaging>@
* For Apklib: @<packaging>apklib</packaging>@

h3. 1.5. Maven Dependencies

In the dependency section of your @pom.xml@, add all the dependencies to other Jar files (not Apklibs):

<pre><code><dependencies>
...
<dependency>
<groupId>...</groupId>
<artifactId>...</artifactId>
<version>...</version>
</dependency>
...
</dependencies></code></pre>


Additionnally, you must add a dependency for each Apklib you want to use in your project:

<pre><code><dependencies>
...
<dependency>
<groupId>...</groupId>
<artifactId>...</artifactId>
<version>...</version>
<type>apklib</type>
</dependency>
...
</dependencies></code></pre>

h2. 2. How to compile an Apk/Apklib in Eclipse?

This section describes how to compile an Apk/Apklib inside Eclipse with Maven.

h3. 2.1. Installation

Install the ADT development platform and the Android-m2e plugin. See "this tutorial":http://www.janus-project.org/Android_SDK_Tutorial for details.

h3. 2.2. Source checkout

Check out the source of the current project into an Maven project inside your Eclipse workspace. Let say the name of the project @MyApkLib@.

*You must configure your project to be compilable on CLI* (see the previous section).

h3. 2.3. Supporting Apklib in Eclipse IDE

Until now, the ADT and the android-m2e plugins is not able to find the Java source code of an Apklib that your project is using. They do not download and install the source code of the Apklibs, as it is done by the android-maven-plugin.
The main symptom of this problem is a compilation error such as _Class not defined/found_ on a class given by the Apklibs.

To fix this problem, you need to following the sections below. The main idea is to force Eclipse (and the ADT/Maven plugin) to use the Jar file of the Apklib, and not the Apklib files themelves.

h4. 2.3.1. Add dependencies to the Jar files

Add the following code into the @pom.xml@ by copying the dependencies of the apklibs *only* that are mentionned in the CLI configuration.

After copying and pasting the dependencies, change the types of the dependencies from @apklib@ to @jar@.

<pre><code><profiles>
...
<profile>
<id>m2e</id>
<activation>
<activeByDefault>false</activeByDefault>
</activation>
<dependencies>
<dependency>
<groupId>...</groupId>
<artifactId>...</artifactId>
<type>jar</type>
</dependency>
</dependencies>
</profile>
...
</profiles></code></pre>

This code include the Jar files of the Apklibs only if the Maven profile @m2e@ is manually activated. We will activate it inside Eclipse to avoid compilation problems on the CLI.

h4. 2.3.2. Apklib imports

For each Apklib in the dependencies of your project:
# check out or import the sources of the dependency into a Maven/Android project inside your current workspace. Let say this project has the name @MyDep@.
# Configure the project @MyDep@ properly, if not already done.

h4. 2.3.3. Activation of the profile <code>m2e</code>

# Right-click on the project to open the popup menu.
# Select _Properties_.
# In the dialog box, select _Maven_.
# Put @m2e@ in the field _Active Maven Profiles_, and click on _ok_.

h4. 2.3.4. Fixing the paths of the Android references

Android projects contains the file @project.properties@, which contains several informations on the project. The relative paths to the included Apklibs are mentionned inside. Unfortunatelly, the default value of these paths may be wrong if you are coding your Apklib as a Maven submodule.

To fix this problem, you need to:
# Right-click on the project to open the popup menu.
# Select _Properties_.
# In the dialog box, select _Android_.
# Remove all the broken references in the _Library_ section.
# Add the reference path to the @MyDep@ project in the _Library_ section.

*CAUTION:* When you have _"unexpected compilation errors"_, check if the ADT tools have not put again some incorrect values for these reference paths.

h3. 2.4. Finalization

Clean and compile your project.

h3. 2.5. Examples

You could find examples of @pom.xml@ in the following projects:
* Apk: "Android Editor for Finite State Machine":https://github.com/gallandarakhneorg/neteditor/blob/master/neteditor-fsm/fsm-droideditor/pom.xml;
* Apklib: "Android Graph Editor View":https://github.com/gallandarakhneorg/neteditor/blob/master/neteditor-androidpanel/pom.xml.

h3. 2.6. Cannot find source code in Eclipse

When debugging, Eclipse may indicates that it cannot find the source code of an Apklib (because the source code seems to be provided by the Android dependencies that are read-only).
In this case, we recommend to edit the lookup of the sources during the debugging.
# Put a breakpoint
# Run the program in debug mode until the breakpoint is reached.
# Open the debug view, where the stack trace is output.
# Right-click on the root item (the application) in the tree of the stack trace.
# Select _Edit lookup source_.
# Add the Apklib project(s) in the displayed list, if missed.
# Move the Apklib projects at the top of the list.

0 comments on commit 615b64d

Please sign in to comment.