Introduction
This tutorial explains how to build Cactus from CVS or from a source download.
If you just want to use Cactus, it will be easier to simply download a nightly build (if you need the latest and greatest), or the latest stable release otherwise.
Getting the Source
There are two ways to obtain the source code for Cactus: either directly from CVS, or by downloading a prepackaged source archive.
CVS
To get the current development version of the Cactus source code, you'll need to download the source from CVS. To do this, you'll need to have a CVS client installed.
Detailled instructions about accessing the Apache CVS repository can be found here. The module name for Cactus is
jakarta-cactus
.Prepackaged Source Archives
If you don't have access to the Apache CVS repository (because you're behind a firewall, for example), or you don't need to be absolutely up to date, you can download an archive containing a snapshot of the Cactus code base.
Such archives are made available for each release as well as for the nightly builds. Go here to find out about the download locations.
Prerequisites
To build Cactus from source, you'll need to have Ant 1.5.1 (or later) installed. Please make sure that the distribution also includes the JAR containing the optional tasks (
optional.jar
). In addition, please add an XSLT processor (like Xalan to thelib
directory of your Ant installation.In addition, Cactus depends on a number of additional external libraries at build time. When not otherwise mentioned, these libraries can be used by either placing them in the
lib
directory of your Ant installation, or by explicitly specifying their location in abuild.properties
file at the root of the Cactus source distribution.Required Libraries
The following libraries are required to compile the Cactus framework. The integration modules and samples have additional dependancies that are listed as optional libraries below.
Name Version Description aspectjrt.jar 1.0.6 or later The AspectJ runtime. aspectjtools.jar 1.0.6 or later The AspectJ compiler and other tools. aspectj-ant.jar 1.0.6 or later The AspectJ Ant tasks.
Since version 1.1 of AspectJ, the Ant tasks are included inaspectjtools.jar
.commons-httpclient.jar 2.0 beta 1 or later Jakarta Commons HttpClient. commons-logging.jar 1.0 or later Jakarta Commons Logging. junit.jar 3.7 or later The JUnit framework.
This JAR file must be placed in thelib
directory of your Ant installation, or Ant will not be able to load the required classes.servlet.jar 2.2 or 2.3 The Servlet/JSP API.
This JAR file comes with your servlet container or application server. To perform a complete build of Cactus, you'll need to have JARs for both version 2.2 and 2.3 of the servlet API.Optional Libraries
Name Version Description checkstyle.jar 3.1 or later The Checkstyle code auditing tool. antlr.jar 2.7.2 or later The ANTLR translator generator (required by Checkstyle).
If you use thecheckstyle-all-[version].jar
distribution of Checkstyle, the classes from this JAR are already included.commons-beanutils.jar 1.5 or later Jakarta Commons BeanUtils (required by Checkstyle).
If you use thecheckstyle-all-[version].jar
distribution of Checkstyle, the classes from this JAR are already included.commons-collections.jar 2.1 or later Jakarta Commons Collections (required by Checkstyle).
If you use thecheckstyle-all-[version].jar
distribution of Checkstyle, the classes from this JAR are already included.regexp.jar 1.2 or later Jakarta RegExp (required by Checkstyle).
If you use thecheckstyle-all-[version].jar
distribution of Checkstyle, the classes from this JAR are already included.clover.jar 1.1 or later Clover code coverage tool.
This JAR file must be placed in thelib
directory of your Ant installation, or Ant will not be able to load the required classes.httpunit.jar 1.5 or later HttpUnit. Required for testing the HttpUnit integration. nekohtml.jar 0.7 or later The Cyberneko HTML parser (required by HttpUnit). log4j.jar 1.2 or later Jakarta Log4j. Required for packaging the Cactus distribution. jstl.jar 1.0 JSP Standard Tag Library. Required for compiling and running the servlet sample test suite on J2EE 1.3. standard.jar 1.0 or later Jakarta Standard Taglib. Required for compiling and running the servlet sample test suite on J2EE 1.3. If you don't want to experience version conflicts, you need to get the versions corresponding to Cactus releases. For example, If you're building Cactus 1.4.1 from its sources, you'll need to get the jars found in the corresponding Cactus distribution. If you are building from CVS, you can get the latest jars from the Gump nightly builds.In the future we might make this process easier by moving our build system to Maven.Make sure you have only one XML parser. If you had the Crimson jar you will need to remove it.
Understanding the Directory Structure
The Cactus project is divided into several modules, each having its own build:
- documentation
The Cactus documentation.
- framework
The Cactus framework.
- integration
Various tool integration modules.
- ant
Ant tasks and support classes provided by Cactus.
- eclipse
Plugins for integration with the open-source IDE Eclipse.
- samples
Sample applications using Cactus.
- jetty
Sample application that demonstrates the use of the Jetty integration.
- servlet
Sample web-application using Cactus. It currently also acts as functional and regression test suite for the Cactus framework.
All modules follow a similar directory structure and they all use Ant as the build tool.
Performing Builds
First, you need to create a
build.properties
file in the directory of the module you wish to build. You will find existingbuild.properties.sample
files in module directories. Simply copy them tobuild.properties
and edit the file. Mostly, it asks for locations of jars that you will need to have put somewhere on your local filesystem.Alternatively you can provide abuild.properties
file in the top-level directory. This file will be used by all modules.Then, open a shell, change into the module directory and execute
ant -projecthelp
. That will give you the list of available Ant targets:$ cd framework $ ant -projecthelp Buildfile: build.xml Cactus Framework --------------------------------------------------------- Contains the core classes of the Cactus in-container testing framework. Main targets: checkstyle Perform a code audit using Checkstyle clean Clean all generated files compile Compile the sources dist Generate the distributable files doc Generates the API documentation jar Generate the library jar test Run the unit tests Default target: distSimply execute the target you need. To build the framework, you can invoke
ant dist
or justant
(because dist is the default target). If you just want to build the framework JAR or the API documentation, invokeant jar
orant doc
, respectively.$ cd framework $ ant distSome projects depend on others and thus you may need to run the build for those projects first. For example, the servlet sample depends on the framework and the Ant integration, so these will need to be built before the servlet sample is built.The top-level directory contains a master build file that can be used to build all modules in the correct order (
ant dist
) and package release archives (ant release
).Before creating a patch, and especially before committing changes, be sure to run both the checkstyle and test targets of the corresponding module. Often we will also need to run the servlet sample tests, because they effectively represent the regression test suite for Cactus. You might want to simply perform a full rebuild to be sure that nothing has been negatively affected by your changes.