EQUIP2 installation guide

Chris Greenhalgh, 2006-04-25; last updated 2007-10-24


This document describes (at least some of) how to build, test and use EQUIP2. The EQUIP2 API and capabilities are descibed in EQUIP2_Introduction.html.

The source code

Getting EQUIP2

Javatrans is in the EQUIP sourceforge CVS accessible as:

CVSROOT: :pserver:anonymous@equip.cvs.sourceforge.net:/cvsroot/equip
Module: equip2

Some additional dependencies (mainly for J2EE development) are in same repository, as module dependencies.

It is licensed under the (so-called) new or modified BSD Open Source license.

Directory structure

EQUIP2 is primarily (currently) targetted at Java, both J2SE (for PCs and servers) and J2ME (for mobile phones and the like). Its Java versions are normally built using the Apache ANT tool.

Top-level directory, e.g. Equator/equip2/

The following directories may be created during the build process but are not (normally) in CVS:

Source code organisation

The main packages in the source (src/ and test/) directory hierarchies are described in the EQUIP2 introduction.

In addition, some common heuristics are used to organise the code for multi-platform building:

With the various options for J2ME (CLDC1.0/1.1, MIDP1.0/2.0, etc.) it is very unwealdy to try to separate out all target-dependencies into distinct files (e.g. using subclassing). In particular, the absense of JVM (strictly KVM) support for floats & doubles on CLDC1.0 is hard to program around. Consequently, for J2ME builds the Antenna Java preprocessor to preprocess the Java source files for different J2ME target profiles. In particular, the following Antenna preprocessor symbols are used to control compilation of profile-specific code:

Note that Antenna is NOT currently used to preprocess source files for J2SE; consequently all code in files not in j2me subdirectories should be compilable under J2SE. Consequently the only Antenna constructions that should be used in such files will be of the following form:
//#ifndef CLDC10
...some code which will not work on CLDC1.0...


//#ifndef J2ME
...some code which will not work on J2ME atall...

In J2ME files (under a j2me packages/directories) any of the symbols and Antenna conditional constructions may be used, since these source files will always be preprocessed (and are only used for J2ME targets).

Building EQUIP2

External dependencies

In addition to the sourcecode for all platforms/targets you will need:
In addition you may need:
For J2ME development you will also need:
For J2EE support (including Taglib and persistence over a relational database) you will also need a number of other things. Sufficient dependency JARs to build and deploy should be found in the EQUIP2 dependencies module. This can be obtained from the same CVS as module 'dependencies', or downloaded as an archive file from the web site file downloads area. This includes
By default the dependencies are looked for via the path ../dependencies/lib (see build.properties).

Configuration properties

The build is configured by properties in build.properties:

Note: if you are using a different version of Hibernate (or other dependencies) then you may need to change the classpath(s) in build.xml, especially 'classpath_hibernate' and perhaps 'classpath_tools'.

In addition, the following properties may be set when ant is run (using ant -Dprop=value ...):

Using Ant

Ant is the Apache Java build tool. It is simple to use:

> ant TARGETNAME ...

You may need to configure the environment variables JAVA_HOME to point to the Java SDK installation directory and ANT_HOME to point to the Ant installation directory, and then add the Java and Ant bin/ directories in each of those to your PATH. On windows...

> set JAVA_HOME=...
> set ANT_HOME=...
> set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%

Sometimes (if ant doesn't seem to work) you may also need to (re)set the CLASSPATH environment variable; just setting it to '.' should work:


Ant build targets

Core EQUIP2 J2SE/J2EE build targets:

Core EQUIP2 internal build targets
Hibernate (RDBMS persistence) J2SE build targets:
J2SE test build targets:
J2SE tool build targets:
J2ME build targets:

Building a distribution

For a J2SE distribution (comprising dist/equip2.jar & dist/equip2tools.jar) (without Hibernate persistence, EQUIP2/PART (remote dataspace access) or tests):
ant clean j2se
For a J2EE distribution (comprising dist/equip2.jar, dist/equip2hibernate.jar & dist/equip2taglib.jar) with Hibernate persistence and tests:
ant clean j2ee

Running sample/test applications

There are currently a number of (Windows) batch files in the top-level directory which can be used to run test applications, normally using the classfiles in the build/ directory (i.e. after ant compile test):

Building with PART

All code which depends on PART to compile is in the part/ subdirectory - see EQUIP2_PART_Integration_Notes.html. Building that code requires that EQUIP2 has already been build in this directory (ant jar for J2SE or ant j2me for J2ME).

PART is only used as one option for remote dataspace communication. There is now a native equip2-only remote dataspace access option, so this is not strictly required. The version of PART on which this is based is also relatively old (mid 2006). However this should still work as another remote dataspace access option. Note that any applications which host or access remote dataspaces require supporting classes (in this case EQUIP2/PART) to run but not to compile - the remote dataspace API is generic, and run-time class loading is used to load the EQUIP2/PART or EQUIP2 native implementation.

Change log