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.

Detailed 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

The following sections list java libraries that you need to have present in your local filesystem for the build. Do not worry! We won't ask you to fish around to get these libraries :-) We have created an Ant script that does this automatically. The next section on Performing Builds explains how to use it.

Ant

To build Cactus from source, you'll need to have Ant 1.6.1 (or later) installed. For building the Maven plugin you'll need to have Maven 1.0 (or later) installed.

You'll need to have the following libraries put in your [ANT_HOME]/lib/ directory.

Name Optional? Version Description
junit.jar No 3.8.1 or later The JUnit unit testing framework.
xalan.jar Yes. Required only if you're building with a JDK version lower than 1.4. You should also be able to use a different XSLT processor. (not sure - we need to find the version) A XSLT processor.
clover.jar Yes. Required only to run the release build of Cactus or if you have turned on "clovering" (clover.enable = true). 1.2.3 Clover code coverage tool.

Required Libraries

In addition, Cactus depends on a number of additional external libraries at build time. The locations of these libraries on your file system should be specified in your build.properties file at the root of the Cactus source distribution. The next section on Performing Builds explains how to automatically download these libraries.

Name Version Description
aspectjrt.jar 1.1.1 The AspectJ runtime.
aspectjtools.jar 1.1.1 The AspectJ compiler and other tools.
commons-httpclient.jar 2.0 Jakarta Commons HttpClient.
commons-logging.jar 1.0.3 Jakarta Commons Logging.
junit.jar 3.8.1 The JUnit framework.
This JAR file must be placed in the lib directory of your Ant installation, or Ant will not be able to load the required classes.
servlet.jar 2.2, 2.3 or 2.4 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 versions 2.2, 2.3 and 2.4 of the servlet API.
checkstyle.jar 3.4 The Checkstyle code auditing tool.
antlr.jar 2.7.2 The ANTLR translator generator (required by Checkstyle).
commons-beanutils.jar 1.6.1 Jakarta Commons BeanUtils (required by Checkstyle).
commons-collections.jar 2.1 Jakarta Commons Collections (required by Checkstyle).
regexp.jar 1.3 Jakarta RegExp (required by Checkstyle).
httpunit.jar 1.5.4 HttpUnit. Required for testing the HttpUnit integration.
nekohtml.jar 0.8.1 The Cyberneko HTML parser (required by HttpUnit).
log4j.jar 1.2.8 Jakarta Log4j. Required for packaging the Cactus distribution.
jstl.jar 1.0.2 JSP Standard Tag Library. Required for compiling and running the servlet sample test suite on J2EE 1.3.
standard.jar 1.0.2 Jakarta Standard Taglib. Required for compiling and running the servlet sample test suite on J2EE 1.3.
jetty.jar 4.2.17 Jetty Servlet container. Required to build and run the Jetty sample project.
jasper-compiler.jar 4.1.30 JSP engine required by Jetty to process JSPs. Required to build and run the Jetty sample project.
jasper-runtime.jar 4.1.30 JSP engine required by Jetty to process JSPs. Required to build and run the Jetty sample project.
mockobjects-core.jar 0.09 Mock object library used by several unit tests.

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.
    • maven/
    • Maven plugins for Cactus.
  • 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.
    • ejb
    • Sample EJB 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 (except for the maven/ module which is built with Maven.

Performing Ant builds

Good news: it should be extremely easy to build Cactus from the sources! :-) After ensuring that you connected to internet, type the following 2 commands one after another:

  • ant -f download.xml: This will automatically download all the required libraries. It takes about 5 minutes on a 512 kbps internet connection the first time. If you're behind a firewall, you'll need to read below how to customize the Cactus build as you'll need to edit your build.properties file and supply proxy information.
  • ant or ant dist: This will build the different Cactus modules for the default J2EE API (at the time of this writing the default is J2EE 1.3).

The build result will be located in the dist-* directories of the different Cactud subprojects.

Now, there are 2 files that you may wish to copy and edit if you wish to customize the Cactus build:

  • build.properties.default: This file contains the default Cactus build configuration properties. You should not edit it. Rather you should copy it to a file named build.properties which you can then edit. The file is self-documented.
  • dependencies.xml.default: This file contains the list of Cactus library dependencies along with their versions. You should not edit this file. Rather, if you wish to use other versions, you should copy this file to a file named dependencies.xml which you can then edit.

To get help about the Ant targets available to build a given subproject, 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: dist

Then, simply execute the target you need. To build the framework, you can invoke ant dist or just ant (because dist is the default target). If you just want to build the framework JAR or the API documentation, invoke ant jar or ant doc, respectively.

$ cd framework
$ ant dist
Some 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. To avoid these problems you can simply type ant dist at the top level as it builds the different projects in the correct order.

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.

Generating the Maven plugin

To generate the maven plugin, you must first perform the Ant build (see above). Than you just need to go to the integration/maven sub-directory and run maven plugin:install.