build/BUILDING.txt

$Id$

                 =============================================
                 Building The Tomcat 5.5 Servlet/JSP Container
                 =============================================

This subproject contains the source code for Tomcat 5.5, a container that
implements the Servlet 2.4 and JSP 2.0 specifications from the Java
Community Process <http://www.jcp.org/>.  In order to build a binary
distribution version of the container from a source distribution, 
do the following:


(0) Download and Install a Java Development Kit

* If the JDK is already installed, skip to (1).

* Download a Java Development Kit (JDK) release (version 1.4.x or later) from:

    http://java.sun.com/j2se/

* Install the JDK according to the instructions included with the release.

* Set an environment variable JAVA_HOME to the pathname of the directory
  into which you installed the JDK release.


(1) Install Apache Ant 1.5.x on your computer

* If Apache Ant 1.5.x is already installed on your computer, skip to (2).

* Download a binary distribution of Ant 1.5.x from:

    http://ant.apache.org/bindownload.cgi

* Unpack the binary distribution into a convenient location so that the
  Ant release resides in its own directory (conventionally named
  "jakarta-ant-1.5.x").  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.

* Create an ANT_HOME environment variable to point the directory
  ${ant.home}.

* Modify the PATH environment variable to include the directory
  ${ant.home}/bin in its list.  This makes the "ant" command line script
  available, which will be used to actually perform the build.


(2) Building Tomcat 5.5

(2.1) Download main build script and build binary distribution

* Download the main build.xml script from:
  http://jakarta.apache.org/tomcat/tomcat-5.5-doc/build.xml

* 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

(2.2) Building

* Go to that directory, and do:

    cd ${tomcat.source}
    ant

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

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

* The build can be controlled by creating a ${tomcat.source}/build.properties
  file, and adding the following content to it:

    # ----- Proxy setup -----
    # Uncomment if using a proxy server
    #proxy.host=proxy.domain
    #proxy.port=8080
    #proxy.use=on

    # ----- Default Base Path for Dependent Packages -----
    # Replace this path with the directory path where dependencies binaries
    # should be downloaded
    base.path=/usr/share/java


(3) Updating sources

It is recommended that you regularly update the downloaded Tomcat 5 sources. 
To do this, execute the following commands:

    cd ${tomcat.source}
    ant checkout


(4) Rebuilds

For a quick rebuild of only modified code you can use 
   
    cd ${tomcat.source}
    ant build

In addition, "ant build-depends" will build packages that 
tomcat depends on ( commons-logging for now ), to ease fixes
and debuging in those packages.

(5) Building The "compat" Package

Tomcat 5.5 is designed to run on J2SE 5.0, but will run on
J2SE versions 1.3 and 1.4 as well as long as the compatability
package is placed in the server classpath.  See "RUNNING.txt"
in this directory for running instructions.  To build the
compat package, do

    cd ${tomcat.source}
    ant build-compat