<?xml version="1.0"?>
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document>

    &project;

    <properties>
      <author>Remy Maucherat</author>
      <title>Building Tomcat</title>
    </properties>

<body>

<section name="Introduction">

<p>
Building Tomcat from CVS is very easy, and is the first step to contributing to
Tomcat. The following is a step by step TODO list.
</p>

</section>

<section name="Download and install a Java Development Kit 1.4.x or later">

<p>
Earlier releases would also work, but are harder to work with due to the need to
download additional dependencies. Tomcat also runs much faster on 
the latest 1.4 JDK.
</p>

<p>
The Sun JDK can be downloaded <a href="http://java.sun.com/j2se/">here</a>.
</p>

<p>
<b>IMPORTANT</b>: Set an environment variable JAVA_HOME to the pathname of the 
directory into which you installed the JDK release.
</p>

</section>

<section name="Install Apache Ant 1.5.x">

<p>
Download a binary distribution of Ant 1.5.x from 
<a href="http://ant.apache.org/bindownload.cgi">here</a>.
</p>

<p>
Unpack the binary distribution into a convenient location so that the
Ant release resides in its own directory (conventionally named
"jakarta-ant-1.5.1").  For the purposes of the remainder of this document,
the symbolic name "${ant.home}" is used to refer to the full pathname of
 the release directory.
</p>

<p>
Create an ANT_HOME environment variable to point the directory ${ant.home}, 
and modify the PATH environment variable to include directory
"${ant.home}/bin" in its list.  This makes the "ant" command line script
available, which will be used to actually perform the build.
</p>

</section>

<section name="Building Tomcat">

<p>
Download the main build.xml script from <a href="build.xml">here</a>.
</p>

<p>
Create a new directory, and copy the newly download build.xml to it. This
  directory will be referred to as the ${tomcat.source} directory in the rest
  of this document.
</p>

<p>
Go to that directory, and do:
<code><br/>
    cd ${tomcat.source}<br/>
    ant<br/>
</code>
</p>

<p>
NOTE: Users accessing the Internet through a proxy must use a properties
  file to indicate to Ant the proxy configuration. Read below.
</p>

<p>
WARNING: Running this command will checkout the Tomcat 5 sources from CVS, as
  well as download binaries to the <code>/usr/share/java</code> directory. 
  Make sure this is appropriate to do so on your computer. On Windows, 
  this usually corresponds to the <code>C:\usr\share\java</code> directory, 
  unless Cygwin is used. Read below to customize the directory used 
  to download the binaries.
</p>

<p>
The build can be controlled by creating a ${tomcat.source}/build.properties
  file, and adding the following content to it:
<code><br/>
    # ----- Proxy setup -----<br/>
    # Uncomment if using a proxy server.<br/>
    #proxy.host=proxy.domain<br/>
    #proxy.port=8080<br/>
    #proxy.use=on<br/>
<br/>
    # ----- Default Base Path for Dependent Packages -----<br/>
    # Replace this path with the directory path where<br/>
    # dependencies binaries should be downloaded.<br/>
    base.path=/usr/share/java<br/>
</code>
</p>

</section>

<section name="Updating and rebuilding Tomcat sources">

<p>
It is recommended to regularly update the downloaded Tomcat 5 sources. 
To do this, execute the following commands:

<code><br/>
    cd ${tomcat.source}<br/>
    ant checkout<br/>
</code>
</p>

<p>
For a quick rebuild of only modified code you can use:
<code><br/>
    cd ${tomcat.source}<br/>
    ant build<br/>
</code>

</p>

</section>

</body>
</document>
