Scope

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.

Audience

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

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

4.1.3.1. Versioning and file names

4.1.3.2. Build Parameters

4.1.3.3. Build Targets

4.1.3.4. How to build a VisualDCT.jar (for external users)

5. Conclusion

References

Document History

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. For a full list of entities and their respective typographic conventions, please refer to the Styles section of the XML Documentation document.

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:

• Build process. During the build process, the libraries (jar files) are needed, as well as additional utilities, such as compilers, test frameworks, XSLT transformers etc.
• Program execution. For successful execution of the programs built in the previous phase, a subset of 3rd party software is needed. This subset includes libraries and can include some executables (like stand-alone services), but excludes build tools (compilers and so on).

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:

• A directory VDCTROOT/3rdParty/Common contains the platform-independent software.
• A directory VDCTROOT/3rdParty/Win32 contains the platform-dependent software for Windows platform.
• A directory VDCTROOT/3rdParty/Linux contains the platform-dependent software for Linux platform.
• A directory VDCTROOT/3rdParty/SunOS contains the platform-dependent software for Solaris platform.
• A directory VDCTROOT/3rdParty/HP-UX contains the platform-dependent software for HP-UX platform.
• ...

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

• A directory src contains all the sources (e.g. java, cpp, c, py files).
• A directory include contains all the includes (e.g. h, hpp files).
• A directory test contains all necessary test files and scripts.
• A directory idl contains all interface definition files (e.g. idl, midl files).
• A directory lib contains all libraries and also libraries built from sources (e.g. so, a, dll files).
• A directory bin contains all binaries and also binaries built from sources.
• A directory object contains all (temporary) object files.
• A directory doc contains all documentation.
• A directory man contains all manual pages.

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:
   • ECLIPSE_HOME. Define this if it is not already defined. The variable should point to directory of Eclipse (WebSphere) installation.
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_<ver> 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
or
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:
   • passing additional classpath -cp parameter with necessary jars to JRE when running Ant, or
   • copying all necessary jars to <Ant root>/lib directory and running Ant with scripts located in <Ant root>/bin directory, which do this automatically.

VisualDCT Ant build scripts need the following external task libraries:

• JUnit Testing Framework

And some optional, necessary to do VisualDCT integration builds and releases (needed only by Cosylab to generate VisualDCT WWW pages):

• VisualDCT-Common
• Styler ANT Task
• MySQL JDBC driver

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:

• Set some properties required by the VDCTBuild.xml master build file.
• Set the classpath required by the build process.
• Call the targets within the master build file to produce the actual build. Which targets are called depends on the nature of the project. If the project is a production project, the usual targets will be all or jar.

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

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

	<property name="project.name" value="${ant.project.name}"/>

	<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"/>
	</path>
	
	<property name="build.classpath.ext" refid="build.classpath"/>
	
	<target name="release">
		<ant antfile="VDCTBuild.xml" dir="." target="release"/>
	</target>
	
	<target name="build">
		<ant antfile="VDCTBuild.xml" dir="." target="build"/>
	</target>

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

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

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

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

• In the first line, we specify the project name. We also specify the default target, i.e. the build target that will be marked as default when Ant build file is started.
• The next line which defines the property project.name is mandatory and must not be changed. It cannot be moved to the master build file.
• Property test.class defines the java class that contains automatic tests, as defined by JUnit testing framework. No automatic tests are performed if this property is not set.
• Property javadoc.packages defines the package names of all packages, for which javadoc documentation will be generated. No javadocs are generated if this property is not set.
• In the next few lines, the classpath is defined. Classpath should specify all directories, files and jar files (as described in Ant documentation) for the classes used during the build process. Default build directory and java classpath as well as classpath for JUnit are already included in the master build file. In this place, specify only the classpaths for additional classes used by the project.
• The next line, setting the build.classpath.ext property is mandatory and must not be changed.
• The remaining lines define the targets for build.xml file simply by delegation to the master build file VDCTBuild.xml. The project developer decides which targets to define in the build.xml file depending on the nature of the project. In this example we specify target release which makes a complete distribution. Other targets from VDCTBuild.xml could be called as easily and completely new targets could be defined as well.

4.1.3.1. 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 <project name>-<type>-<version>.<ext> convention, where type can be src, doc, dist, e.g. VisualDCT-doc-2.0.1232.zip
The only exception is a binary file, which is composed of <project name>.<ext>, e.g. VisualDCT.jar

4.1.3.2. 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.

• build.output - Set this property to point to the directory that will contain the results of the build process.
build.version - Set this property to override automatical versioning (optional, used rarely).

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"/>

4.1.3.3. Build Targets

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

• jar - builds Java ARchive (jar) file, i.e. java binaries [default].
• *all - builds all (jar, tests, source jar, docs, web content)
• *build - builds new integration build (generates new build version, jar, tests, source jar, docs, full web content)
• *release - builds new release (generates new build version, jar, tests, source jar, docs, full web content)

[Matej Sekoranja] * - to be used only by Cosylab.

4.1.3.4. 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.

Document History

References