Compiling OpenIMAJ from Source

Jonathon Hare edited this page Jun 14, 2016 · 2 revisions
Clone this wiki locally

Introduction

The OpenIMAJ framework was written with varying levels of interest and development use cases in mind. If you are looking for simplified functionality for a specific task, we recommend the [OpenIMAJ Tools] which details the set of tools that allow for command line access to most of the functionality in the OpenIMAJ library. If you want to properly integrate a stable or development version of OpenIMAJ into your java project as a library, please follow the instructions in [Using the OpenIMAJ Library] which deals with the process of using Maven to import OpenIMAJ jar files into your existing projects. If you are trying to develop core OpenIMAJ functionality, hack around with its inner workings or simply compile OpenIMAJ from scratch, you are in the right place. This page will detail the compilation and installation process of OpenIMAJ on any unix-like development environment. These instructions should also be basically unchanged for windows machines.

The source for the project is available from our sourceforge svn repository. If you already have subversion installed you can download the source using this command.

> git clone https://github.com/openimaj/openimaj.git

The rest of these instructions concern themselves with building the project using a project management tool called Maven. If you want to use the code without Maven, (read as: "you like doing things by hand") you can! All the code is in the subversion repository and the dependencies of each sub project (both on other sub-projects and external jars) are outlined in the subproject's pom.xml file. There are some generated source files which must be generated using a maven compile script. To install java, maven, build OpenIMAJ using maven and import OpenIMAJ to an eclipse development environment, please follow the rest of these instructions.

These instructions were created by installing OpenIMAJ on Mac OS X, however they should be platform agnostic. They include the process of installing java, maven, git and eclipse leaving you with a working development copy of OpenIMAJ. The process is as verbose as possible to guarantee correct results. If any steps go wrong please say something in the comments and we'll tell the world. Installing stuff should be easy!

Prerequisites - java and maven

Java

The OpenIMAJ library is written entirely in Java 1.7. Therefore first thing which should be installed on your system is a version>=1.7 of the java jdk (most likely Java 8 at the time of writing).

Installation

To install the latest version of the Java JDK please follow the instructions found here.

Once this is complete you should be able to do:

> java -version
> javac -version

and get something along the lines of:

> java -version
java version "1.8.0_31"
Java(TM) SE Runtime Environment (build 1.8.0_31-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)
> javac -version
javac 1.8.0_31

Maven

Once Java is installed, you can install Maven. Apache Maven is a project management and build automation tool. The OpenIMAJ project uses maven as its project builder. Maven takes care of many things including the download and installation of all the jar requirements of all OpenIMAJ projects and sub projects.

Installation

To install maven on please follow your development environment's instructions here.

Once maven is properly installed, you should be able to do:

> mvn -version

and get something along the lines of:

> mvn -version
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=128m; support was removed in 8.0
Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T12:57:37+01:00)
Maven home: /usr/local/Cellar/maven/3.3.3/libexec
Java version: 1.8.0_31, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_31.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.10.5", arch: "x86_64", family: "mac"

Git

If everything went well so far you can install git. The current bleeding edge version of our sourcecode can be found on our git repository hosted on github at https://github.com/openimaj/openimaj.

Installation

You can install git on any environment by following your development environment instructions here.

At this point you should be able to do:

> git --version

and get something along the lines of:

> git --version
git version 2.3.2 (Apple Git-55)

At this point you are ready to download the OpenIMAJ sourcecode and prepare the project allowing for development and integration with other projects.

Eclipse

The eclipse IDE was used to develop OpenIMAJ and we highly recommend it for any development you do.

Installation

For all operating systems the eclipse IDE can be downloaded from the eclipse website. We recommend the Eclipse IDE for Java Developers version of eclipse.

Downloading and Installing

Cloning the OpenIMAJ repository

To clone a version of the OpenIMAJ codebase you can use the command:

> git clone https://github.com/openimaj/openimaj.git

By doing this a new directory will be created called openimaj. This directory is the root of the openimaj project. Inside this directory there are several sub directories containing the modules and sub-modules of the OpenIMAJ project. The dependencies can be explored by reading the pom.xml files in each directory.

Installing OpenIMAJ

To compile, test and install OpenIMAJ, navigate to the root of the project:

> cd openimaj

and run the maven command:

> mvn install

The same command can be run within the directories of individual subprojects for finer grain project compilation. From the root of the project, this may take some time, especially on the first run as this process will systematically download each dependency of each project and also run all the tests for each project. To install the projects and download all necessary jar files without running tests use:

mvn install -Dmaven.test.skip=true

OpenIMAJ and Eclipse

Once this process is complete, the OpenIMAJ project is compiled and installed. The jar files for each project can be found in their respective target directories. However, for more effective development you may want to import OpenIMAJ into eclipse.

Once imported into eclipse all submodules should correctly reference each other's eclipse projects and therefore changes between subprojects should be useable without the need for a maven recompilation.

Summary

OpenIMAJ was written in Java 1.7 and is useable with most java applications. For ease of compilation, installation and use: maven was used to manage the project and for distribution subversion was used. These instructions allow the creation of a working OpenIMAJ development environment. To use OpenIMAJ as a library follow [OpenIMAJ Library] instead and to use the OpenIMAJ command line tools please consult [OpenIMAJ Tools]