Chapter 2. Building

Explains the steps involved in building Jalopy from the sources.

2.1. Prerequisites

The following software must be installed separately, in order to build from the sources:

Table 2.1. Software needed to build from the sources

Jakarta Ant	Jalopy comes with a simple, Ant-based build system. So you first need to obtain and install Ant as outlined in the Ant manual. The build system is only tested against the Ant 1.5.4 release, but later releases of Ant may also work.
Oasis DocBook XML DTD	All documentation is written using DocBook Version 4.2 markup. You can get the DTD from the OASIS web site. Unpack the sources into a folder of your choice and remember this path as it will be needed for configuration later on.
An XSLT processor	The DocBook markup needs to be transformed in order to make some user-friendly appearance. This is done via XSLT and Michael Kay's Saxon is the processor I found working with the Stylesheet package I use. You should download the current stable production release from SourceForge (http://saxon.sf.net) and extract the file `saxon.jar` into the `/lib` folder of your Ant installation directory. I also had to setup saxon to use Xerces as the XML parser by editing the META-INF/services/javax.xml.parsers.SAXParserFactory file inside of saxon.jar and replacing the alfred parser with org.apache.xerces.jaxp.SAXParserFactoryImpl
DocBook XSL Stylesheets	To perform the markup translation you need Norman Walsh's XSL Stylesheet package. The version that works for me is 1.62.4. You can get it from SourceForge (http://docbook.sf.net). Copy the file `extensions/saxon651.jar` that comes with the distribution into the `/lib` folder of your Ant installation directory as this file is needed for sophisticated table generation.
A CVS client (optional)	If you plan to get the sources directly from CVS you need a CVS client. If your system does not come with one pre-installed (most Linux machines at least have the command-line client installed by default), you will certainly want to visit any of several good sites such as http://www.cvshome.org/ which lists available CVS clients for different platforms, their strengths and weaknesses. For what it's worth, I prefer SmartCVS.

2.2. Building

The basic steps to build Jalopy from the sources are:

Get and install the needed software as outlined in Section 2.1, “Prerequisites”. Make sure Ant is set up correctly.
Get the sources. Either download and unpack the Jalopy source distribution which contains the complete Jalopy sources. Or grab the needed modules directly from the CVS tree.

Change to the directory where your Jalopy sources reside. You should find a directory layout somewhat similar to the following (each directory represents a module; the minimal needed modules are printed in bold):

 ..
   ant/                  The Ant Plug-in
   build/                The Jalopy build system
   console/
   docu/                 All documentation sources
   eclipse/              The Eclipse Plug-in
   jbuilder/             The JBuilder Plug-in
   jdeveloper/           The JDeveloper Plug-in
   jedit/                The jEdit Plug-in
   main/                 The core Jalopy sources
   netbeans/             The NetBeans/Sun ONE Studio Plug-in

Change directory into /build where the master build script lurks.

Adjust the global build properties to match your installation. The build system uses quite a few properties to control the build process and specify additional needed resources. You can find and adjust these properties in the file build.properties.

Luckily you only have to change some common properties to get things running:

Common build properties
DIR.DOCBOOK.XSL

Specifies the installation directory of the DocBook XSL Stylesheets package. Note that you have to specify a protocol, e.g. file:///G:/XML/docbook-xsl-1.62.4.

DIR.DOCBOOK.DTD

Specifies the path where to find the DocBook XSL DTD. You have to adjust the default path to match your installation.

LIB.PATH.<modulename>

Specifies additional library path(s) needed to build a certain module. You have to adjust the default path(s) to match your installation.

PACKAGE.PATH.<libraryname>

Specifies the location to a directory containing the package-list file for a given library. This is optional and only needed by Javadoc to resolve links to documentation for externally referenced classes. Change the default path(s) to match your installation.
Once everything is set up, you can start a build using ant target where target describes one of the main build targets (those with a description, use ant -projecthelp to display the available targets). Just typing ant will build the Jalopy core runtime distribution.
When a build is done, you can find the created distribution(s) in the tmp~/dist folder. The build system creates and stores all intermediate files and subdirectories under the tmp~ directory.
If you make changes to the source code, just run Ant again; this will perform a faster incremental rebuild of the target.