Java Installation and Build Process of VisualDCT
Classification:User's Documentation
Copyright © 2002 by Cosylab Ltd. All Rights Reserved.

Document History

1.02002-07-02Matej Sekoranja
1.12002-07-09Matej Sekoranja
1.12002-07-10Matej SekoranjaReleased
1.22005-08-21Matej Sekoranja
1.22005-08-21Matej SekoranjaReleased


This document is a users guide to installing the Java software necessary to perform builds of VisualDCT project. The instructions include steps needed to set up Eclipse IDE, 3rd party software and explanation of how Ant build files are used.


This document is classified as a public document. Redistribution and use, with or without modification, are permitted provided that:

  1. the copyright notice is retained
  2. a reference to the original document is made in case of modifications
  3. this document may not be distributed for profit except as explicitly permitted by valid licenses.


The audience of this document are all developers wishing to build VisualDCT project.


1Gasper TkacikJava Installation and Build Process HowTo1.22002Cosylab
2IBM Corporation and othersEclipse Project2.02002IBM Corporation and others
3Jakarta ANT TeamANT Homepage1.4.12001Apache Software Foundation
4GPLJUnit Testing
5LangdaleStyler ANT Task1.02002Langdale

Table of Contents

1. Introduction

2. 3rd Party Software

3. Eclipse installation

4. Build Process

4.1. Manual builds

4.1.1. Configuring Eclipse

4.1.2. Configuring Ant

4.1.3. Writing Ant build file Versioning and file names Build Parameters Build Targets How to build a VisualDCT.jar (for external users)

5. Conclusion

How to Read this Document

This document's meta-information (authors, revision history, table of contents, ...) can be found above. What follows below is the body of the document. The body is composed of several sections, which may be further composed of subsections.

Typographical styles are used to denote entities of different kinds.

When viewing the document in a non-printed form, it is possible to submit comments regarding a given section to the document's owner. This is achieved by clicking the mail icon next to the section title. For this to work, your mail must be configured to properly handle the mailto URLs.

1.  Introduction

This document is divided into three sections. The first section defines the locations of the 3rd party software, such as Sun runtime libraries, extension libraries etc. The second section describes the Eclipse (or Websphere) installation and setup. The third section describes the use of Ant build files, which are customarily distributed with the VisualDCT project.

2.  3rd Party Software

Third party software for Java is needed for two distinct purposes:

Apart from this division based on the use of the 3rd party software, it can also be divided into platform-independent and platform-specific. Libraries delivered in jar form together with their documentation and resources form the platform-independent software. Executables, such as run-time environments and stand-alone services are usually platform-dependent.

The 3rd part software is located in VDCTROOT/3rdParty directory. All 3rd party software, discussed in this section, is then installed into 3rdParty subdirectory in the following manner:

Platform name is defined by the returned value of uname POSIX command.

Under each directory enumerated above, each 3rd party product is installed into its own directory. The name of the directory is a lower-case product name, followed by a '-' character, followed by a version specification in which dot '.' servers as major / minor separator (e.g. mmmysql-2.0.11).

Every 3rd party product has to have the following directory structure (created if necessary):

3rd party directory structure is used in build files and batches for running programs.

3.  Eclipse installation

This section lists the steps needed to install Eclipse product and get it working with VisualDCT project. This section presupposes that Java Development Kit has already been installed.

  1. Install Eclipse 2.0 or WebSphere into some directory.
  2. Set the PATH environment variable to point to the subdirectory where the JDK (not JRE, but full JDK) is installed. The path should point to the bin subdirectory of the JDK.
  3. Go to   Window  -  Preferences   menu in Eclipse and select   Java  -  Classpath Variables  . Define two variables:
  4. Install the necessary Eclipse extensions (in the form of fragments and plugins). The extensions are available on Cosylab web page. Plugins are installed by unzipping them to the ECLIPSE_HOME/plugins directory and restarting Eclipse. Fragments are installed by unzipping them to the ECLIPSE_HOME/fragments directory and restarting Eclipse. For more information on installing the plugins, see Eclipse documentation.
  5. If projects require Java compiler newer than that provided with Eclipse, go to Eclipse menu   Window  -  Preferences  , select   Java  -  Installed JREs   and set the appropriate Java version there.

4.  Build Process

VisualDCT project is built with Ant build tool. Ant tool is used because it is easier to manage than makefiles and it is customized for use with Java (classpath handling, additional build tasks specified in Java, etc). Ant works by executing an Ant build file in the form of Ant conformant XML.

During the development process VisualDCT is build automatically by Eclipse without Ant, this way is easier and faster. All other tasks such as test process, integration builds and releases should be done with Ant.

4.1.  Manual builds

4.1.1.  Configuring Eclipse

This section lists the steps needed to configure Eclipse product to build internal VisualDCT-Common project.

  1. Right mouse click over   VisualDCT   node and select   Properties  .
  2. Select   Libraries   node and click   Add Variable...   button.
  3. Select   ECLIPSE_HOME   variable and click   Add Extended...   button.
  4. Browse through plugins/org.apache.ant_ and select ant.jar JAR file.

[Matej Sekoranja] This is not necessary, since all these kind of settings are stored in .classpath file.

[Matej Sekoranja] In Eclipse   Windows  -  Perferences  -  External Tools  -  Ant   add external task jars in classpath.

[Matej Sekoranja] Ant may give the following error message:
"Cannot use classic compiler, as it is not available. A common solution is to set the environment variable JAVA_HOME to your JDK directory."
To avoid this problem go to   Window  -  Preferences  -  Ant  -  Customize   and add tools.jar
run the Ant script with argument -Dbuild.compiler=org.eclipse.jdt.core.JDTCompilerAdapter tu run Ant with Eclipse's JRE.

4.1.2.  Configuring Ant

This section lists the steps needed to install Ant product and get it working with VisualDCT project. This section presupposes that Java Development Kit has already been installed.

  1. Install Ant into some directory.
  2. Set the PATH environment variable to point to the subdirectory where the Ant is installed. The path should point to the bin subdirectory of the Ant.
  3. Ant requires JAVA_HOME environment variable to point to the subdirectory where the JRE is installed.
  4. Add external task libraries to Ant classpath. This can be done by:

VisualDCT Ant build scripts need the following external task libraries:

All necessary libraries are located in 3rdparty directory.

4.1.3.  Writing Ant build file

In order to build the VisualDCT project manually, the developer responsible for the project must write the build.xml file and place it in the root directory of the project. This file must:

For more insight, a sample build.xml file is provided below.

    <project name="VisualDCT sample build example" default="all" basedir=".">

	<property name="" value="${}"/>

	<property name="test.class" value="com.cosylab.vdct.sample.test.AllTests"/>
	<property name="javadoc.packages" value="com.cosylab.vdct.sample"/>
	<path id="build.classpath">
		<pathelement location="./3rdParty/Common/infobus1.2/infobus.jar"/>
		<pathelement location="./3rdParty/Common/jnlp1.0.1/jnlp.jar"/>
	<property name="build.classpath.ext" refid="build.classpath"/>
	<target name="release">
		<ant antfile="VDCTBuild.xml" dir="." target="release"/>
	<target name="build">
		<ant antfile="VDCTBuild.xml" dir="." target="build"/>

	<target name="all">
		<ant antfile="VDCTBuild.xml" dir="." target="all"/>

	<target name="jar">
		<ant antfile="VDCTBuild.xml" dir="." target="jar"/>

	<target name="doc">
		<ant antfile="VDCTBuild.xml" dir="." target="doc"/>

Here we provide a brief discussion of the sample build file:  Versioning and file names

VisualDCT Ant build script VDCTBuild.xml has auto-versioning capability. Script searches for the past builds thourch the directory structure and returns build version. If build or release target is used, it generates a new version, otherwise the latest is used. This feature can be also overriden by setting build.version property as described in Build Parameters section.

Version is composed of major, minor and build version. All three components are numbers and are seperated by a dot '.', e.g. 2.0.1232. Also filenames follows the --. convention, where type can be src, doc, dist, e.g.
The only exception is a binary file, which is composed of ., e.g. VisualDCT.jar  Build Parameters

In order for the build process to work correctly, two parameters must be provided to the JVM or ANT using the -D parameter passing mechanism.

For example, if target directory is ~/dist and version 2.0.1232, the parameters for the JVM look like this:

-Dbuild.output=~/dist -Dbuild.version=2.0.1232

Parameters can be also provided by hardcoding it into build.xml file simply by adding lines:

    <property name="build.output" value="~/dist"/>
    <property name="build.version" value="2.0.1232"/>  Build Targets

VisualDCT Ant build script VDCTBuild.xml has defined the following targets:

[Matej Sekoranja] * - to be used only by Cosylab.  How to build a VisualDCT.jar (for external users)

Simply go to the VisualDCT source root directory and type ant.
You do not need any additional (external) libraries.

5.  Conclusion

This document will probably change in the future. When known, the explicit WWW locations will be included.