Docs for: v1.7.2 | v1.7 Last update: March 26 2006

# 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`.