EQUIP2 installation guide

Introduction

The source code

Getting EQUIP2

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

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

• build.xml - the ANT buildfile (see notes below)
• docs/ - the documentation directory, where this and other documents can be found
• etc/ - various configuration files and utility scripts, e.g. the XLST scripts use by the Simple Bean Generator
• src/ - the main Java source hierarchy
• test/ - Java source for testing-only code/applications
• tools/ - Java source for tooling, e.g. the XSLT-running application
• part/ - extension to EQUIP2 which depend on and make use of the IPerG project's PART platform. (old)
• targets/ - target-specific build scripts etc. for C++ translation(s) of EQUIP2 (based on javatrans)
  

• generated/ - various non-class files generated by the build process, e.g. auto-generated Java beans and helpers from the Simple Bean Generator
• dist/ - various packaged files (e.g. JARs) for potential distribution from a completed build
• build/ - J2SE built files, e.g. class files
• build.j2me/ - J2ME-specific built files, e.g. class files
  
• build.cpp/ - C++/Javatrans-specific built files
  

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:

• Any source files which are specific to J2SE builds should appear under a package/directory j2se in the source, e.g. src/equip2/net/j2se/GraphicalMonitor.java, which relies on SWING for its GUI; these will be excluded from J2ME builds.
• Any source files which are specific to J2ME builds should appear under a package/directory j2me in the source, e.g. test/equip2/core/test/j2me/SessionTest1.java, which relies on MIDP/MIDlets for its GUI; these will be excluded from J2SE builds.
• Any source files which are only for testing EQUIP2 should appear under the test/ top-level directory, and normally ALSO under a package/directory test/ (see example on previous point), since currently class files are combined in a single target build directory.
  
• If source files rely on optional 3rd-party libraries, then they should similarly be placed in a package/directory reflecting this, e.g. files which depend on the Hibernate object/relation database mapping system are in packages which include a hibernate/ component in their path/package, e.g. src/equip2/persist/hibernate/j2se/PersistentDataspace.java.
  

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:

• CLDC10 - compilation target is CLDC1.0: floats and doubles should not be used
• CLDC11 - compilation target is CLDC1.1
• MIDP10 - compilation target is MIDP1.0
• MIDP20 - compilation target is MIDP2.0
  
• J2ME - compilation target is any J2ME profile
  
• J2SE - compilation target is J2SE

//#ifndef CLDC10
   ...some code which will not work on CLDC1.0...
//endif

or

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

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

• Apache ANT (build tool)
  
• A Java 2 SE SDK (should work with almost any, but we are currently using 1.5 & 1.6, so thing incompatible with 1.4 may creep in from time to time)

• Apache Xalan (XSL implementation) - in theory the XSL implementation in Java 1.5 should work, but we have had mixed results with this (required for EQUIP2 build support tools: Simple Bean Generator)
  

• Antenna (a version of which should already be found in the lib/ directory)
  
• Sun Java Wireless Toolkit (testing with version 2.3)
  

• the Hibernate object/relational mapping system (testing with version 3.1)
• A relational database management system, currently by default HSQLDB and associated JDBC drivers (if separate). mySQL is also an option, but requires a separate download/install for the database itself, plus the JDBC drivers.
• JSP and servlet APIs and JSTL 1.1
• a number of other dependencies of the EQUIP2 web application framework (e.g. Spring framework, Quartz scheduler).
  

Configuration properties

• dependencies.dir - directory in which dependency JARs are placed - see above (for J2EE only)
  
• xalanhome - directory in which Xalan is installed (optional - if JDK XSL does not work)
  
• wtk.home - directory in which Sun Java Wireless Toolkit is installed (for J2ME only)
  

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 ...):

• none as yet :-)
  

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:

> set CLASSPATH=.

Ant build targets

Core EQUIP2 J2SE/J2EE build targets:

• j2se - good starting point for J2SE (no hibernate) = targets compile,test,jar,tools_jar
• generates dist/equip2.jar & dist/equip2tools.jar
  
• j2ee - good starting point for J2EE = targets compile,hibernate_compile,hibernate_jar,jar,test,tools_jar,taglib
• generates dist/equip2.jar, dist/equip2hibernate.jar, dist/equip2tools.jar & dist/equip2taglib.jar
  
• clean - delete all generated (non-CVS) files

• compile - compiles EQUIP2 for J2SE (excluding tests)
• jar - does compile, then JARs relevant parts of build/ directory (excluding tests, hibernate, etc.) into dist/equip2.jar.
  

• hibernate_compile - compile core parts of EQUIP2 dependent on hibernate, i.e. dataspace implementation.
• hibernate_test - compile hibernate test application (and Simple Bean Generator data class(es)).
• hibernate_run - run the hibernate test application (see EQUIP2_and_Hibernate.html for database configuration requirements).

• test - compile the EQUIP2 J2SE test applications and data classes (some of these are described briefly in EQUIP2_Introduction.html)

• tools_compile - compile tools, currently just XSL translator
• tools_jar - do compile_tools and then create dist/equip2tools.jar
  

• j2me - create dist/equip2-j2me.jar (depends on j2me_preverify which depends on j2me_compile).
• j2me_test - creates J2ME testing MIDlets (depends on j2me_test_preverify which depends on j2me_test_compile which depends on j2me). Currently the test MIDlets are:
• dist/J2MeSessionTest1.jar, with manifest test/equip2/core/test/j2me/SessionTest1.mf
• dist/J2MeNotificationTest1.jar, with manifest test/equip2/core/test/j2me/NotificationTest1.mf
• dist/J2MeRMSTest1.jar, with manifest test/equip2/rms/test/j2me/RMSTest1.mf
• dist/J2MePersistentDataspaceTest1.jar, with manifest test/equip2/persist/rms/test/j2me/PersistentDataspaceTest1.mf
  

Building a distribution

ant clean j2se

ant clean j2ee

Running sample/test applications

• test.bat
• runTupleTest.bat
• runDataspaceServer.bat
• runGraphicalMonitor.bat
• runSimpleMonitor.bat
  

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

• initial version of document complete
  

• document created
  

• more on ant, new targets

• update, e.g. add targets/, clarifiy PART requirement

• change CVS info

• revised dependencies information & ant targets; revised j2ee notes, e.g. separate equip2hibernate.jar
• revised default database to HSQLDB