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

  <properties>
    <title>Installing Ant</title>
  </properties>

  <body>

    <section title="Forewords">

      <note>
        <strong>You need to have a good understanding of Ant before
        reading this tutorial. If you don't, I suggest you read the
        <link href="ext:ant_manual">Ant User Manual</link> first</strong>.
      </note>

      <p>
        This tutorial explains how to install Ant properly to be able to
        run the Sample application provided with the Cactus distribution and
        also build the Cactus distribution from the sources.
      </p>

    </section>

    <section title="Ant tasks needed by Cactus">

      <p>
        Cactus uses the following optional tasks of Ant:
      </p>
      <ul>
        <li>
          The <strong><code>junit</code></strong> task: it is used to run
          the unit tests of Cactus itself and the Cactus unit tests of the
          Sample application. This task is
          normally found in the <code>optional.jar</code> Ant jar.
        </li>
        <li>
          The Cactus Sample application uses some Ant custom tasks provided
          by Cactus in the <code>cactus-ant.jar</code> jar file (
          found in the <code>lib/</code> directory where you unpacked the
          Cactus distribution).
        </li>
        <li>
          The <strong><code>checkstyle</code></strong> task: it is used only
          to build Cactus from the sources (i.e. not needed for building the
          Cactus sample application). The version of
          <link href="ext:checkstyle">Checkstyle</link> used is 3.0+.
        </li>
      </ul>

      <p>
        In order to simplify the installation of Ant and the gathering of
        the required Ant tasks as described above, we provide a
        prepackaged zip containing everything needed. This is available from
        the <link href="site:downloads">downloads</link> section.
      </p>

    </section>

    <section title="Installing Ant on Windows systems">

      <p>
        Follow the steps below to install Ant:
      </p>
      <ol>
        <li>
          Download Jakarta Ant
          (<code>jakarta-ant-&lt;version&gt;-bin.zip</code>) from
          <link href="ext:ant">here</link>. We recommend version 1.5.3 or 
          above. Alternatively you can download the
          prepackaged Ant version, as mentioned above.
        </li>
        <li>
          Unzip it in a directory. Let's call this directory
          <code>antroot</code>,
        </li>
        <li>
          Create an environment variable named <code>ANT_HOME</code> that
          points to the <code>antroot</code> directory,
        </li>
        <li>
          Modify the <code>PATH</code> environment variable to include the
          <code>%ANT_HOME%\bin</code> directory (so that you'll be able to type
          <code>ant</code> in a DOS shell, in whatever directory and it will
          call the <code>%ANT_HOME%\bin\ant.bat</code> script,
        </li>
        <li>
          Download the Ant optional task jar
          (<code>jakarta-ant-&lt;version&gt;-optional.jar</code>) from
          <link href="ext:ant">here</link>
          and put it in <code>%ANT_HOME%\lib</code>. <em>Note that this step
          is needed only if you haven't downloaded the prepackaged zip</em>,
        </li>
        <li>
          If you haven't downloaded the prepackaged Ant zip, you'll need to
          download the Stylebook 1.0b3 for Xalan 2 jar, the latest
          <link href="ext:xalanj">Xalan</link>, the latest
          <link href="http://xml.apache.org/xerces-j">Xerces</link>, the
          latest <link href="ext:junit">JUnit</link> and the latest
          <link href="ext:checkstyle">Checkstyle</link> jars. You'll
          also need to ensure that you use a JAXP 1.1 parser. You can download
          one (crimson) from
          <link href="http://java.sun.com/xml/download.html">here</link>. Put
          all these jars in <code>%ANT_HOME%\lib</code>.
        </li>
      </ol>

    </section>

  </body>
</document>
