Installation and setup

Installation and setup

Before you proceed, make sure that Git and Maven 3 are installed on your computer.

Obtaining the source code

You may skip this step if you merely intend to use the ignition-support JAR.

The first step is to obtain the project sources. Being hosted on GitHub, you do this, naturally, with Git. Enter your IDE's workspace directory and run:

$git clone git://github.com/mttkay/ignition.git

This will check out the entire project tree into your workspace.

Building the project

POMs are provided with the project that allow you to build it using Maven 3. Enter the project root folder and run:

mvn clean install

NOTE For the location module to build, you need the Google Maps add-on JAR as a Maven artifact (com.google.android.maps:maps:jar:15_r1) in your local repository. Since it contains proprietary code, it is not available from Maven Central, so it will not be downloaded automatically during the build. Refer to the maven-android-sdk-deployer for detailed instructions on how to obtain it.

Make sure you have ANDROID_HOME set for the tests to pass. If for some reason the tests don't pass (maybe because you're building a snapshot version or are messing with the sources), you are still able to install the project artifacts by adding the -Dmaven.test.skip=true switch.

Project natures and dependencies

Before linking the libraries, two more things. One, you must know and understand the different natures of the individual ignition modules, since Android library projects are handled entirely different from ordinary Java projects/JARs. While modules deployed as JARs can simply be linked in binary form to your app project, those that are Android library projects require to be linked to your app project in their entirety, since they are compiled straight into your app.

If you're unfamiliar with Android library projects and how to use them, read up on them now.

Two, you must obtain the dependencies of each library module you want to use. Since Maven installs these automatically to your local Maven cache, and since ideally you will use a Maven plugin for your IDE to import the projects, no further steps should be required. For your reference, however, here's the list of runtime dependencies for each ignition module, along with its project nature:

ignition-core

Project nature: Android library project. Required API level: 4 (Android 1.6). Dependencies: ignition-support.

ignition-support

Project nature: Java project/JAR. Required API level: 4 (Android 1.6) Dependencies: Google Guava Collections r03. Google Guava Base r03

ignition-location

Project nature: Android library project. Required API level: 10 (Android 2.3.3). Dependencies: ignition-support.

Maven artifacts

If you do not use Maven to manage your app's build, you can skip this section.

Project artifacts are currently hosted on our company Nexus (they're not on Central yet):

<repositories>
  <repository>
    <id>ignition-releases</id>
    <url>http://nexus.qype.com/content/repositories/releases</url>
  </repository>
</repositories>

<repositories>
  <repository>
    <id>ignition-snapshots</id>
    <url>http://nexus.qype.com/content/repositories/snapshots</url>
  </repository>
</repositories>

In order to use the core module, add the following dependency to your POM as a child of dependencies:

<dependency>
  <groupId>com.github.ignition</groupId>
  <artifactId>ignition-core</artifactId>
  <version>0.2</version>
  <type>apklib</type>
</dependency>

In order to use the support module, add the following dependency to your POM as a child of dependencies:

<dependency>
  <groupId>com.github.ignition</groupId>
  <artifactId>ignition-support</artifactId>
  <version>0.2</version>
</dependency>

In order to use the location module, add the following dependency to your POM as a child of dependencies:

<dependency>
  <groupId>com.github.ignition</groupId>
  <artifactId>ignition-location</artifactId>
  <version>0.2</version>
  <type>apklib</type>
</dependency>

Eclipse users

At this point, make sure you have the m2eclipse and m2e-android plugins installed. Detailed instructions for dealing with Maven and Maven/Android projects in Eclipse can be found there. NOTE: At the time of this writing the stable m2e-android release does not yet support the latest version (3.x) of the android-maven-plugin. A fix is underway though. (See Issue #60.) For now, please install the dev build using the snapshot update site.

Linking a JAR module

These steps are required to link modules that are deployed as plain JARs, such as ignition-support.

Maven users

Add an ignition-support dependency to your POM (see previous section). You may have to Maven > Update Dependencies.

Others

Copy the JAR to your app (common practice is to store it in the project's lib folder) and add it to your project's build path via Right click > Build Path > Add to Build Path.

Linking an Android library project

These steps are required to link modules that are deployed as an Android library project, such as ignition-core and ignition-location.

Due to the nature of library projects, this actually requires you to import the library project into your Eclipse workspace. Please note that Eclipse project files are not distributed with ignition, so as to not clutter people's workspaces in case they use a different IDE such as IDEA. In Eclipse, with the plugins installed that we mentioned above:

Maven users

Add the library dependency to your POM (see previous section). You may have to Maven > Update Dependencies.

All users

First, import the library project into your workspace via Import... > Maven > Existing Maven Projects. You should end up with a project that looks something like this:

Next, tell your application project to use the library project. Instructions on how to do this are provided here. Your application's folder structure should then be something like this:

IMPORTANT: Make sure that you disable workspace resolution on the library project via Maven > Disable Workspace Resolution. Otherwise it will result in ignition-support being compiled into the library JAR, and you may end up having the ignition-support classes on your app project's classpath twice.

Extra steps required for ignition-location

If you want to use the location module, a few more steps are required. First of all you need to install the AJDT (AspectJ Development Tools). Once you installed it, add the ignition-location library to your project as described above. Now you'll need to add it to the AJDT's Aspect path, this will allow the plugin to weave your classes using the aspects contained in the library. To do so follow these 5 steps:

1. Open the "Android Dependencies" container an select the ignition-location library.
2. Right click on the library and navigate into the "AspectJ Tools" entry.
3. Click on "Add to Aspectpath".
4. A window will open asking you if you want to add the library to the Aspect path.
5. Click "OK".

IDEA users

In IDEA, it should be as simple as performing:

1. Open Project
2. Select the project's pom.xml

Thanks to Malachi de Ælfweald for submitting this, although I'm not sure if that's enough to get e.g. AspectJ working.