build/BUILDING.txt

  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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.

$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, 
you will need to perform the build on a Windows machine (Windows XP/SP2
is known to work). Do the following:


(0) Download and Install a Java Development Kit

* The default distribution of Tomcat 5.5.x requires a 5.0 or later JDK. 
  Tomcat can be built using a 1.4.x JDK but you will need to copy the contents
  of the compat directory (created by the build process) to your build directory
  before Tomcat will start.

  The standard ASF distributions are built with a 1.4.x JDK.

* 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.6.2 or later on your computer

* If Apache Ant 1.6.2 or later is already installed on your computer, skip to (2).

* Download a binary distribution of Ant 1.6.2 or later 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
  "apache-ant-[version]").  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) Install Subversion 1.3.x or later on your computer

* Subversion is only needed if you wish to checkout the source from SVN.
  It is not needed when building Tomcat from source.

* If Subversion 1.3.x or later is already installed on your computer, skip to (3).

* Download a binary distribution of Subversion 1.3.x or later from:

    http://subversion.tigris.org/getting.html

* Unpack the binary distribution into a convenient location so that the
  Subversion release resides in its own directory.

* Modify the PATH environment variable to include the directory 
  ${svn.home}/bin in its list, where "${svn.home}" is the full pathname 
  of the subversion release directory. This makes the "svn" command
  available, which will be used to checkout the tomcat sources.

(3) Building Tomcat 5.5

* This assumes that the Tomcat source is available in the directory tree starting
  at ${tomcat.source}. 
  
    cd ${tomcat.source}/build
    ant download
    ant [deploy]

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

* WARNING: 
  Running the "ant download" command will 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


(4) Updating sources

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

    cd ${tomcat.source}
    svn update

[This does not apply if you are building Tomcat from a source archive].

(5) Rebuilds

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

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

(6) Building The "compat" Package

Tomcat 5.5 is designed to run on J2SE 5.0, but will run on
J2SE version 1.4 as well as long as the compatibility 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}/build
    ant compat

(7) Building the servlet and jsp API documentation

The documentation can be easily rebuild, do
    cd ${tomcat.source}/build
    ant dist-javadoc

(8) Building a release running tests:

Ensure that 'full.dist=on' is set in build.properties
and do
    cd ${tomcat.source}/build
    ant release

Note that this deletes any existing build output.

(9) Running tests

do
    cd ${tomcat.source}/build
    ant clean-tester run-tester