<?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_ant_primer">

  <properties>
    <title>Ant Integration</title>
  </properties>

  <body>

    <section title="Continuous integration">

      <note>
        <strong>This tutorial was written when I wrote Cactus 1.2. Since then
        I have improved my command of Ant. However this tutorial has not yet
        been updated. I believe it still provides some very good
        methodology on how to use Ant, although not the latest. If you wish to
        keep track of the latest change, have a look at the Cactus build files,
        found in the source distribution.</strong>
      </note>

      <p>
        A strong principle of eXtreme Programming (XP) is the continuous
        integration aspect (see the
        <link href="http://www.martinfowler.com/articles/continuousIntegration.html">
        Continuous Integration</link> article by Martin Fowler). The traditional
        approach has been
        to developing the code first, then test it and then integrate
        it with other applications. The continuous integration principle is to
        develop code, test and integrate at the same time, i.e. at any point
        in time, you have a functioning code along with tests and integrated.
      </p>
      <p>
        In order to be able to do continuous integration, you need to be able
        to automatically run the build for your application, including passing
        the unit tests (based on JUnit, Cactus, HttpUnit or others). Ant is
        the perfect tool for this task.
      </p>

    </section>

    <section title="Ant benefits">

      <p>
        The benefits of using Ant for running unit tests are as follows:
      </p>
      <table>
        <tr>
          <th>
            Benefits
          </th>
        </tr>
        <tr>
          <td>
            Ant is written in Java and thus the same scripts can be used on
            several systems (Windows and Unix for example). Is is therefore very
            well suited for building java applications.
          </td>
        </tr>
        <tr>
          <td>
            Ant provides enough built-in and optional tasks to be able to
            achieve almost any needed build task without needing to use
            system dependent scripts.
          </td>
        </tr>
        <tr>
          <td>
            By being able to very quickly rerun unit test you can verify that
            your tests still pass when you modify some part of your code (
            regression testing)
          </td>
        </tr>
        <tr>
          <td>
            As it is automated, it fits well in the continuous integration
            principle and your tests can thus be ran automatically and
            continously
          </td>
        </tr>
      </table>

    </section>

    <section title="Writing an Ant build script tutorial">

      <p>
        The sample Ant build file described below is taken from the
        <link href="site:downloads">Cactus Sample for Servlet API 2.2
        </link> project.
      </p>

      <note>
        This section is both a tutorial for automating builds and unit testing
        with Ant and Cactus and also a best practice and methodology guide
        for using Ant in general (independent of Cactus). This is an Ant
        configuration that has been working for me on several project. Of course,
        you are free to adapt/modify it to suit your needs.
      </note>

      <section title="Project directory structure">

        <p>
          Create the following directories:
        </p>
        <table>
          <tr>
            <th>
              Directory name
            </th>
            <th>
              Content of the directory
            </th>
          </tr>
          <tr>
            <td>
              <code>build</code>
            </td>
            <td>
              The Ant build file and some other ancillary files (properties file, ...)
            </td>
          </tr>
          <tr>
            <td>
              <code>conf</code>
            </td>
            <td>
              Configuration files for the project. These are the configuration
              files that will <em>not</em> be put into the runtime jar. They
              are configuration file that need to be visible and modifyable
              by a user of the project. If they were bundled in the jar they
              would be hard to modify. On the other hand, we don't want a
              proliferation of configuration files, so all <em>technical</em>
              configuration files (messages to display for errors, ...)
              should be put in the <code>src</code> directory in correct java
              packages.
            </td>
          </tr>
          <tr>
            <td>
              <code>conf/test</code>
            </td>
            <td>
              Configuration files needed for testing the project only.
            </td>
          </tr>
          <tr>
            <td>
              <code>docs</code>
            </td>
            <td>
              Project documentation.
            </td>
          </tr>
          <tr>
            <td>
              <code>docs/skins</code>
            </td>
            <td>
              Documentation skin for Stylebook (if using Stylebook).
            </td>
          </tr>
          <tr>
            <td>
              <code>docs/xdocs</code>
            </td>
            <td>
              Documentation files (XML files) for Stylebook (if using Stylebook).
            </td>
          </tr>
          <tr>
            <td>
              <code>src</code>
            </td>
            <td>
              The project sources: java files + java test files +
              properties files + test properties files + other files for
              runtime or test (XML files, ...). Note that all test files
              should begin by 'Test' or 'test' in order to easily separate them
              from other files so that in an Ant target we'll be able to include
              only the runtime files.
            </td>
          </tr>
          <tr>
            <td>
              <code>web</code>
            </td>
            <td>
              The project web files: HTML, JSP, ... (if any)
            </td>
          </tr>
        </table>

        <note>
          An <code>out</code> directory will be created by the Ant build. All
          build-generated files will be put in that directory (compiled classes,
          generated javadoc documentation, test configuration files for running
          an application server, ...).
        </note>

        <note>
          We don't have any <code>lib</code> directory because it is always
          better not to include dependent jars in your project whenever
          possible for the following reasons: better continuous integration
          with other libraries (meaning they also evolve and you should test
          as much as possible with the latest version to discover potential
          problems early, more lightweight downloads, less jar proliferation
          (you'll end up with tens of the same jars otherwise), more version
          control and integration checks (if your project uses 2 external
          libraries that need another third library but not in the same version
          you are in trouble !), ...
        </note>

      </section>

      <section title="Ant Target List">

        <p>
          Define the following targets in your <code>build.xml</code>.
        </p>

        <note>
          The <em>Type</em> column specify whether the target is an external
          target that can be called by the user of the build file or if it is
          an internal target, intended to be called internally by another
          target inside the build script.
        </note>

        <table>
          <tr>
            <th>
              Target name
            </th>
            <th>
              Description
            </th>
            <th>
              Type
            </th>
          </tr>
          <tr>
            <td>
              <jump anchor="init"><code>init</code></jump>
            </td>
            <td>
              Defines token filters, timestamp, display some information on
              screen, ...
            </td>
            <td>
              Internal
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="usage"><code>usage</code></jump>
            </td>
            <td>
              Display usage information about the targets.
            </td>
            <td>
              External
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="prepare"><code>prepare</code></jump>
            </td>
            <td>
              Set up the output directory where build generated files will be
              put and copy the java sources to this output directory,
              replacing tokens with the values defined in the <code>init</code>
              target.
            </td>
            <td>
              Internal
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="compile"><code>compile</code></jump>
            </td>
            <td>
              Compile the java sources and put the result in the output
              directory. All copies non java source files such as
              <code>.properties</code> files, XML configuration files, ...
            </td>
            <td>
              Internal
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="source"><code>source</code></jump>
            </td>
            <td>
              Generate a zipped file containing the full sources of the project
              (i.e. the whole directory structure, excluding any build
              generated files).
            </td>
            <td>
              External
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="javadoc"><code>javadoc</code></jump>
            </td>
            <td>
              Generates the javadoc of the project. This javadoc will be part
              of the project documentation, as generated by the <code>doc</code>
              target.
            </td>
            <td>
              Internal
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="doc"><code>doc</code></jump>
            </td>
            <td>
              Generates the full project documentation: javadoc + README files
              + documentation web site (using Stylebook for example).
            </td>
            <td>
              External
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="clean"><code>clean</code></jump>
            </td>
            <td>
              Remove any build generated files. In particular, delete the
              output directory.
            </td>
            <td>
              External
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="jar"><code>jar</code></jump>,
              <jump anchor="war"><code>war</code></jump>,
              <code>ear</code>, ...
            </td>
            <td>
              Generate the project runtime. If the project is a framework, it
              is usually a jar. If the project is a web application, it is
              usually a war file. If the project is an EJB application, it is
              usually either one or several jars or an ear file. Etc ...
            </td>
            <td>
              External
            </td>
          </tr>
          <tr>
            <td>
              <jump anchor="tests"><code>tests_XXX</code></jump> where XXX is
              the name of the servlet engine on which the tests run.
            </td>
            <td>
              Run the Cactus unit tests.
            </td>
            <td>
              External
            </td>
          </tr>
        </table>

      </section>

      <anchor id="basedir"/>

      <section title="Step 1: The Ant project basedir">

        <p>
          You <code>build.xml</code> file being in located in
          <code>build/</code> you should set the <code>project</code> tag
          <code>basedir</code>
          attribute to '<code>..</code>' so that all other paths are relative
          to your project root directory. Indeed, the batch file (shell script)
          that was used to bootstrap Ant is located in
          <code>&lt;root&gt;/build</code>, so '<code>..</code>' is the root
          directory.
        </p>
        <p>
          Example:
        </p>
<source><![CDATA[
<?xml version="1.0"?>
[...]
<project name="Cactus Sample" default="war" basedir="..">
]]></source>

      </section>

      <section title="Step 2: initialization of project properties">

        <p>
          You should define as properties all values that can be factorized
          and which are used often in your build file such as source locations,
          output locations, external jar locations and names, ... You can also
          define useful file patterns there (see the sample below).
        </p>

        <p>
          A good principle is to defined any properties that depend on your
          environment (such as external jar locations) in a file (let's call
          it <code>build.properties</code> located either where
          <code>build.xml</code> is located or in your home directory. The
          properties defined in this file will be loaded by
          <code>build.xml</code> using the following code:
        </p>

<source><![CDATA[
    <!-- Give user a chance to override without editing this file
         (and without typing -D each time it compiles it) -->
    <property file="build/build.properties" />
    <property file="${user.home}/build.properties" />
]]></source>

        <p>
          Here are our properties initializations:
        </p>

<source><![CDATA[
<project name="Cactus Sample" default="war" basedir="..">

    <!-- Give user a chance to override without editing this file
         (and without typing -D each time it compiles it) -->
    <property file="build/build.properties" />
    <property file="${user.home}/build.properties" />

    <!-- Generic project properties -->
    <property name="project.fullname" value="Cactus Sample"/>
    <property name="project.version" value="@version@"/>
    <property name="project.name" value="cactus-sample"/>

    <!-- Miscellaneous settings -->
    <property name="year" value="@year@"/>
    <property name="debug" value="on"/>
    <property name="optimize" value="off"/>
    <property name="deprecation" value="off"/>

    <!--
       ========================================================================
         Set the properties related to the source tree
       ========================================================================
    -->
    <!-- Source locations for the build -->
    <property name="src.dir" value="src"/>
    <property name="src.java.dir" value="${src.dir}/share"/>
    <property name="src.java.servlet.dir" value="${src.dir}/servlet@servlet.api@"/>
    <property name="build.dir" value="build"/>
    <property name="etc.dir" value="${build.dir}/etc"/>
    <property name="lib.dir" value="lib"/>
    <property name="conf.dir" value="conf"/>
    <property name="conf.test.dir" value="conf/test"/>
    <property name="web.dir" value="web"/>

    <!--
       ========================================================================
         Set the properties related to the build area
       ========================================================================
    -->
    <!-- Destination locations for the build (relative to the basedir as -->
    <!-- specified in the basedir attribute of the project tag)          -->
    <property name="out.dir" value="out"/>
    <property name="out.dist.dir" value="${out.dir}/dist"/>
    <property name="out.lib.dir" value="${out.dir}/lib"/>
    <property name="out.test.dir" value="${out.dir}/test"/>
    <property name="out.src.dir" value="${out.dir}/src"/>
    <property name="out.classes.dir" value="${out.dir}/classes"/>
    <property name="out.doc.dir" value="${out.dir}/doc"/>
    <property name="out.javadoc.dir" value="${out.doc.dir}/javadoc"/>
    <property name="out.conf.dir" value="${out.dir}/conf"/>

    <!-- Names of deliverables -->

    <!-- The Cactus Sample war file. This is the file that should be
         used at runtime by end users (it excludes the test classes) -->
    <property name="final.war.name" value="${out.dir}/${project.name}-@servlet.api@.war"/>

    <!-- The full sources of Cactus Sample in a zip file -->
    <property name="final.src.name" value="${out.dir}/${project.name}-src-@servlet.api@.zip"/>

    <!-- The Cactus sample documentation in a zip file -->
    <property name="final.doc.name" value="${out.dir}/${project.name}-doc-@servlet.api@.zip"/>

    <!--
       ========================================================================
         Useful file patterns for targets
       ========================================================================
    -->
    <!-- All source files of the projet. These source files will be copied
         to the destination source directory in the prepare task -->
    <patternset id="all.src.files">

        <!-- All java files -->
        <include name="**/*.java"/>

        <!-- All doc files -->
        <include name="**/package.html"/>
        <include name="**/overview.html"/>

        <!-- All conf files (including test files) -->
        <include name="**/*.txt"/>
        <include name="**/*.xml"/>
        <include name="**/*.properties"/>

    </patternset>

    <!-- All non java files in the src directory -->
    <patternset id="all.nonjava.files">

        <!-- All conf files (including test files) -->
        <include name="**/*.txt"/>
        <include name="**/*.xml"/>
        <include name="**/*.properties"/>

    </patternset>
]]></source>

      </section>

      <anchor id="init"/>

      <section title="Step 3: 'init' target">

        <p>
          Useful for initializing a timestamp (DSTAMP, TODAY, TSTAMP), defining
          token filters, printing some information messages, registering
          custom Ant tasks, ...
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Initialize the build. Must be called by all targets
       ========================================================================
    -->
    <target name="init">

        <!-- So that we can use the ${TSTAMP}, ${DSTAMP}, ... time stamps
             in targets, if need be -->
        <tstamp/>

        <echo message="--------- ${project.fullname} ${project.version} ---------"/>
        <echo message=""/>

        <echo message="java.class.path = ${java.class.path}"/>
        <echo message=""/>
        <echo message="java.home = ${java.home}"/>
        <echo message="user.home = ${user.home}"/>
        <echo message=""/>
        <echo message="basedir = ${basedir}"/>
        <echo message=""/>
        <echo message="servlet.jar = ${servlet.jar}"/>
        <echo message="cactus.jar = ${cactus.jar}"/>
        <echo message="junit.jar = ${junit.jar}"/>
        <echo message="cactus.ant.jar = ${cactus.ant.jar}"/>

        <!-- Filters -->
        <filter token="version" value="${project.version}"/>
        <filter token="year" value="${year}"/>

        <!-- Initialize custom Ant tasks needed for running the server tests -->
        <taskdef resource="cactus.tasks">
            <classpath>
                <pathelement location="${cactus.ant.jar}"/>
                <pathelement path="${java.class.path}"/>
            </classpath>
        </taskdef>

    </target>
]]></source>

      </section>

      <anchor id="usage"/>

      <section title="Step 4: 'usage' targets">

        <p>
          Display a usage message.
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Help on usage. List available targets
       ========================================================================
    -->
    <target name="usage" depends="init">

        <echo message=""/>
        <echo message="${project.fullname} build file"/>
        <echo message="------------------------------------------------------"/>
        <echo message=""/>
        <echo message=" Available targets are:"/>
        <echo message=""/>
        <echo message=" war    --> generates the war file (default)"/>
        <echo message=" clean  --> cleans up the build directory"/>
        <echo message=" source --> generates source zip of the project"/>
        <echo message=" doc    --> generates the docs (javadoc, ...)"/>
        <echo message=" all    --> do it all at once"/>
        <echo message="            (clean, war, source, doc)"/>
        <echo message=""/>
        <echo message=" Targets for running the tests for Servlet API 2.2:"/>
        <echo message=""/>
        <echo message=" tests_resin_12    --> run tests for Resin 1.2"/>
        <echo message=" tests_tomcat_32   --> run tests for Tomcat 3.2"/>
        <echo message=" tests_weblogic_51 --> run tests for WebLogic 5.1"/>
        <echo message=" tests_orion_14    --> run tests for Orion 1.4"/>
        <echo message=""/>

    </target>
]]></source>

      </section>

      <anchor id="prepare"/>

      <section title="Step 5: 'prepare' target">

        <p>
          This target is needed for both compiling and generating the javadoc.
          It copies all the source files from their <code>src/</code> directory
          to the <code>out</code> directory, replacing tokens in the source
          code (replacing the <code>@version@</code> by the version number
          for example).
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Prepare the output directory by copying the source files into it
       ========================================================================
    -->
    <target name="prepare" depends="init">

        <mkdir dir="${out.src.dir}"/>

        <!-- Copy all source files to destination dir. Apply the filters in
             order to replace the tokens for the copyright year and the
             version -->
        <copy todir="${out.src.dir}" filtering="on">
            <fileset dir="${src.java.dir}">
                <patternset refid="all.src.files"/>
            </fileset>
            <fileset dir="${src.java.servlet.dir}">
                <patternset refid="all.src.files"/>
            </fileset>
        </copy>

    </target>
]]></source>

      </section>

      <anchor id="compile"/>

      <section title="Step 6: 'compile' target">

        <p>
          The <code>compile</code> target simply compiles the java files into
          <code>.class</code> files and also copies the support files that are
          in <code>src/</code> to the directory where the class file have been
          generated.
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Compiles the source directory
       ========================================================================
    -->
    <!-- Preparation target for the compile target -->
    <target name="prepare-compile" depends="prepare">

        <mkdir dir="${out.classes.dir}"/>

    </target>

    <!-- Run the java compilation -->
    <target name="compile" depends="prepare-compile">

        <javac srcdir="${out.src.dir}"
            destdir="${out.classes.dir}"
            debug="${debug}"
            deprecation="${deprecation}"
            optimize="${optimize}">

            <!-- Exclude all files that are not .java source files -->

            <!-- All doc files -->
            <exclude name="**/package.html"/>
            <exclude name="**/overview.html"/>

            <!-- All conf files (including test files) -->
            <exclude name="**/*.txt"/>
            <exclude name="**/*.xml"/>
            <exclude name="**/*.properties"/>

            <classpath>
                <pathelement path="${java.class.path}"/>
                <pathelement location="${servlet.jar}"/>
                <pathelement location="${cactus.jar}"/>
            </classpath>

        </javac>

        <!-- Copies non java files that need to be in the classes directory -->
        <copy todir="${out.classes.dir}">
            <fileset dir="${src.java.dir}">
                <patternset refid="all.nonjava.files"/>
            </fileset>
            <fileset dir="${conf.test.dir}">
                <include name="cactus.properties"/>
            </fileset>
        </copy>

    </target>
]]></source>

      </section>

      <anchor id="source"/>

      <section title="Step 7: 'source' target">

        <p>
          Zip up the sources for distribution.
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Generates source zip of the project
       ========================================================================
    -->
    <target name="source" depends="prepare">

        <zip zipfile="${final.src.name}" basedir=".">

            <exclude name="${out.dir}/**"/>
            <exclude name="**/*.log"/>
            <exclude name="**/*.bak"/>
            <exclude name="**/*.class"/>
            <exclude name="${build.dir}/build.properties"/>

        </zip>

    </target>
]]></source>

      </section>

      <anchor id="javadoc"/>

      <section title="Step 8: 'javadoc' target">

        <p>
          Generate the project's javadoc.
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Generate the javadoc
       ========================================================================
    -->
    <!-- Preparation target for the javadoc target -->
    <target name="prepare-javadoc" depends="prepare">

        <mkdir dir="${out.javadoc.dir}"/>

    </target>

    <!-- Generate the javadoc for the current Servlet API -->
    <target name="javadoc" depends="prepare-javadoc">

        <javadoc
            sourcepath="${out.src.dir}"
            packagenames="org.apache.cactus.sample.*"
            destdir="${out.javadoc.dir}"
            author="true"
            public="true"
            version="true"
            use="true"
            windowtitle="${project.fullname} ${project.version} for Servlet @servlet.api@ API"
            doctitle="${project.fullname} ${project.version} for Servlet @servlet.api@ API"
            bottom="Copyright &amp;copy; ${year} Apache Software Foundation. All Rights Reserved.">

            <classpath>
                <pathelement path="${java.class.path}"/>
                <pathelement location="${servlet.jar}"/>
                <pathelement location="${cactus.jar}"/>
            </classpath>

        </javadoc>

    </target>
]]></source>

      </section>

      <anchor id="doc"/>

      <section title="Step 9: 'doc' target">

        <p>
          Generate the project's documentation. It includes the javadoc,
          additional README files (if any) and the documentation web site
        </p>

        <p>
          Example:
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Generate the full documentation
       ========================================================================
    -->
    <!-- Preparation target for the doc target -->
    <target name="prepare-doc" depends="javadoc">

        <mkdir dir="${out.doc.dir}"/>

    </target>

    <!-- Generate the documentation -->
    <target name="doc" depends="prepare-doc">

        <!-- Create the zipped documentation -->
        <zip zipfile="${final.doc.name}" basedir="${out.doc.dir}"/>

    </target>
]]></source>

      </section>

      <anchor id="clean"/>

      <section title="Step 10: 'clean' target">

        <p>
          Removes all build generated files.
        </p>

<source><![CDATA[
    <!--
       ========================================================================
         Remove all build generated files
       ========================================================================
    -->
    <target name="clean" depends="init">

        <!-- Deletes all files ending with '~' -->
        <delete>
            <fileset dir="." includes="**/*~" defaultexcludes="no"/>
        </delete>

        <!-- Remove the out directory -->
        <delete dir="${out.dir}"/>

        <!-- Delete log files -->
        <delete>
            <fileset dir=".">
                <include name="**/*.log"/>
            </fileset>
        </delete>

    </target>
]]></source>

      </section>

      <section title="Step 11: 'jar', 'war' targets">

        <anchor id="jar"/>

        <section title="'jar' target">

          <p>
            This target is useful if your project is a framework for example and
            you need to deliver a jar file. We also include a manifest file
            in the jar, with version information. We copy the manifest to the
            output directory in order to replace the <code>@version@</code>
            token with its value.
          </p>

          <p>
            Example (from the Cactus build file):
          </p>

<source><![CDATA[
    <!--
       ========================================================================
         Create the runtime jar file
       ========================================================================
    -->
    <!-- Preparation target for the jar target -->
    <target name="prepare-jar" depends="compile">

        <mkdir dir="${out.conf.dir}"/>
        <mkdir dir="${out.lib.dir}"/>

        <!-- Copy the manifest in order to replace the version token filter -->
        <copy todir="${out.conf.dir}" filtering="on">
            <fileset dir="${conf.dir}" >
                <include name="manifest"/>
            </fileset>
        </copy>

    </target>

    <!-- Generate the jar file -->
    <target name="jar" depends="prepare-jar">

        <jar jarfile="${final.jar.name}" basedir="${out.classes.dir}"
            manifest="${out.conf.dir}/manifest">

            <!-- Do not include test files in the runtime jar -->
            <exclude name="**/Test*.*"/>
            <exclude name="**/test*.*"/>

        </jar>

    </target>
]]></source>

        </section>

        <anchor id="war"/>

        <section title="'war' target">

          <p>
            This target is useful if you're building a web application.
            We also include a manifest file in the war, with version
            information. We copy the manifest to the output directory in order
            to replace the <code>@version@</code> token with it's value.
          </p>

          <p>
            Example (from the Cactus sample):
          </p>

<source><![CDATA[
    <!--
       ========================================================================
         Create the runtime war file
       ========================================================================
    -->
    <!-- Preparation target for the war target -->
    <target name="prepare-war" depends="compile">

        <mkdir dir="${out.conf.dir}"/>

        <!-- Copy the manifest in order to replace the version token filter  -->
        <copy todir="${out.conf.dir}" filtering="on">
            <fileset dir="${conf.dir}" >
                <include name="manifest"/>
            </fileset>
        </copy>

    </target>

    <!-- Generate the war file -->
    <target name="war" depends="prepare-war">

        <war warfile="${final.war.name}"
             webxml="${conf.dir}/web.xml"
             manifest="${out.conf.dir}/manifest">

            <classes dir="${out.classes.dir}">
                <!-- Do not include test files in the runtime jar -->
                <exclude name="**/Test*.*"/>
                <exclude name="**/test*.*"/>

                <!-- Also exclude the test cactus.properties file -->
                <exclude name="cactus.properties"/>
            </classes>

            <fileset dir="${web.dir}">
                <exclude name="test/**"/>
            </fileset>
        </war>

    </target>
]]></source>

        </section>

      </section>

      <anchor id="tests"/>

      <section title="Step 12: 'tests_XXX' target">

        <p>
          The <code>tests_XXX</code> target is in charge of running the
          Cactus unit tests. It must prepare the test environment for a
          given servlet engine and package the tests, start that servlet
          engine, run the tests by starting the JUnit runner and stop the
          servlet engine.
        </p>

        <p>
          See the <link href="site:howto_ant_cactus">Using Cactus with
          Ant</link> tutorial for details on to do this.
        </p>

      </section>

    </section>

  </body>
</document>
