<?xml version="1.0"?>

<!--
 * ========================================================================
 * 
 * Copyright 2001-2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * ========================================================================
-->

<document id="howto_build">

  <properties>
    <title>Building Cactus from the Source</title>
  </properties>

  <body>

    <section title="Introduction">
      <p>
        This tutorial explains how to build Cactus from CVS or from a source
        download.
      </p>
      <note>
        If you just want to use Cactus, it will be easier to simply download
        a <link href="site:downloads">nightly build</link> (if you need the
        latest and greatest), or the latest 
        <link href="site:downloads">stable release</link> otherwise.
      </note>
    </section>

    <section title="Getting the Source">
      <p>
        There are two ways to obtain the source code for Cactus: either 
        directly from CVS, or by downloading a prepackaged source archive.
      </p>

      <section title="CVS">
      	<p>
          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.
        </p>
        <p>
          Detailed instructions about accessing the Apache CVS repository can
          be found
          <link href="ext:cvs">here</link>. The module name for Cactus is 
          <code>jakarta-cactus</code>.
        </p>
      </section>

      <section title="Prepackaged Source Archives">
        <p>
          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.
        </p>
        <p>
          Such archives are made available for each release as well as for the
          nightly builds. Go <link href="site:downloads">here</link> to find 
          out about the download locations.
        </p>
      </section>

    </section>

    <section title="Prerequisites">

      <p>
        The following sections list java libraries that you need to have
        present in your local filesystem for the build. 
        <strong>Do not worry!</strong> 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 <jump anchor="build">Performing Builds</jump>
        explains how to use it.
      </p>

      <section title="Ant">

        <p>
          To build Cactus from source, you'll need to have
          <link href="ext:ant">Ant</link> 1.6.1 (or later) installed. For
          building the Maven plugin you'll need to have 
          <link href="ext:maven">Maven</link> 1.0 (or later) installed.
        </p>

        <p>
          You'll need to have the following libraries put in your 
          <code>[ANT_HOME]/lib/</code> directory.
        </p>
        
        <table>
          <tr>
            <th>Name</th>
            <th>Optional?</th>
            <th>Version</th>
            <th>Description</th>
          </tr>
          <tr>
            <td nowrap="true">
              <link href="ext:junit">junit.jar</link>
            </td>
            <td>
              No
            </td>
            <td nowrap="true">
              3.8.1 or later
            </td>
            <td>
              The JUnit unit testing framework.
            </td>
          </tr>
          <tr>
            <td nowrap="true">
              <link href="ext:xalanj">xalan.jar</link>
            </td>
            <td>
              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.
            </td>
            <td nowrap="true">
              (not sure - we need to find the version)
            </td>
            <td>
              A XSLT processor.
            </td>
          </tr>
          <tr>
            <td nowrap="true">
              <link href="ext:clover">clover.jar</link>
            </td>
            <td>
              Yes. Required only to run the release build of Cactus or if you 
              have turned on "clovering" (<code>clover.enable = true</code>).
            </td>
            <td nowrap="true">1.2.3</td>
            <td>
              Clover code coverage tool.
            </td>
          </tr>
        </table>

      </section>
      
      <section title="Required Libraries">

        <p>
          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
          <code>build.properties</code> file at the root of the Cactus 
          source distribution. The next section on 
          <jump anchor="build">Performing Builds</jump> explains how to
          automatically download these libraries.
        </p>

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

    </section>

    <section title="Understanding the Directory Structure">
      <p>
        The Cactus project is divided into several modules, each having 
        its own build:
      </p>
      <dl>
      	<dt>documentation/</dt>
      	<dd>
      	  The Cactus documentation.
      	</dd>
        <dt>framework/</dt>
        <dd>
          The Cactus framework.
        </dd>
        <dt>integration/</dt>
        <dd>
          Various tool integration modules.
          <dl>
            <dt>ant/</dt>
            <dd>
              <link href="ext:ant">Ant</link> tasks and support classes
              provided by Cactus.
            </dd>
            <dt>eclipse/</dt>
            <dd>
              Plugins for integration with the open-source IDE
              <link href="ext:eclipse">Eclipse</link>.
            </dd>
            <dt>maven/</dt>
            <dd>
              <link href="ext:maven">Maven</link> plugins for Cactus.
            </dd>
          </dl>
        </dd>
        <dt>samples/</dt>
        <dd>
          Sample applications using Cactus.
          <dl>
            <dt>jetty</dt>
            <dd>
              Sample application that demonstrates the use of the 
              <link href="site:integration_jetty">Jetty integration</link>.
            </dd>
            <dt>servlet</dt>
            <dd>
              Sample web-application using Cactus. It currently also acts as
              functional and regression test suite for the Cactus framework.
            </dd>
            <dt>ejb</dt>
            <dd>
              Sample EJB using Cactus. It currently also acts as
              functional and regression test suite for the Cactus framework.
            </dd>
          </dl>
        </dd>
      </dl>
      <p>
        All modules follow a similar directory structure and they all use
        Ant as the build tool (except for the <code>maven/</code> module
        which is built with Maven.
      </p>
    </section>

    <section title="Performing Ant builds">

      <p>
        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:
      </p>
      <ul>
        <li>
          <strong><code>ant -f download.xml</code></strong>: 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 <code>build.properties</code>
          file and supply proxy information.
        </li>
        <li>
          <strong><code>ant</code></strong> 
          or <strong><code>ant dist</code></strong>: This will build
          the different Cactus modules for the default J2EE API (at the 
          time of this writing the default is J2EE 1.3).
        </li>
      </ul>
      <p>
        The build result will be located in the <code>dist-*</code> directories
        of the different Cactud subprojects.
      </p>

      <p>
        Now, there are 2 files that you may wish to copy and edit if you wish
        to customize the Cactus build:
      </p>
      <ul>
        <li>
          <strong><code>build.properties.default</code></strong>: This file 
          contains the default Cactus build configuration properties. You should
          not edit it. Rather you should copy it to a file named 
          <code>build.properties</code> which you can then edit. The file is
          self-documented.
        </li>
        <li>
          <strong><code>dependencies.xml.default</code></strong>: 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
          <code>dependencies.xml</code> which you can then edit.
        </li>
      </ul>

      <p>
        To get help about the Ant targets available to build a given subproject,
        open a shell, change into the module directory and execute
        <code>ant -projecthelp</code>. That will give you the list of 
        available Ant targets:
      </p>

<source><![CDATA[
$ 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]]>
</source>
        
      <p>
        Then, simply execute the target you need. To build the framework, you
      	can invoke <code>ant dist</code> or just <code>ant</code> (because
      	<em>dist</em> is the default target). If you just want to build the
      	framework JAR or the API documentation, invoke <code>ant jar</code>
      	or <code>ant doc</code>, respectively.
      </p>
<source><![CDATA[
$ cd framework
$ ant dist]]>
</source>
      <note>
        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 <code>ant dist</code> at the top level as it builds the
        different projects in the correct order.
      </note>

      <p>
        Before creating a patch, and especially before committing changes, be
        sure to run both the <em>checkstyle</em> and <em>test</em> 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.
      </p>
    </section>

    <section title="Generating the Maven plugin">

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

    </section>

  </body>

</document>
