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 . Note: If you just need to run Apache Tomcat, it is not necessary to build it. You may simply download a binary distribution. It is cross-platform. Read RUNNING.txt for the instruction on how to run it. In order to build a binary distribution version of Apache Tomcat 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) Checkout or obtain the source code for Tomcat 6.0 * Tomcat 5.5 SVN repository URL: http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/ * Download a source package from: http://tomcat.apache.org/download-55.cgi * Checkout the source using SVN, selecting a tag for released version or trunk for the current development code, or unpack a source package. The location where the source has been placed will be referred as ${tomcat.source}. (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] * WARNING: Running "ant download" command will download libraries required to build Tomcat to the /usr/share/java directory. On a typical Linux or MacOX system an ordinary user will not have access to write to this directory, and, even if you do, it may not be appropriate for you to write there. On Windows this usually corresponds to the "C:\usr\share\java" directory, unless Cygwin is used. Read below to learn how to customize the directory used to download the binaries. * NOTE: Users accessing the Internet through a proxy must use a properties file to indicate to Ant the proxy configuration. Read below. * 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=/home/me/some-place-to-download-to (4) Updating sources and Rebuilds It is recommended that you regularly update the downloaded Tomcat 5.5 sources. To do this, execute "svn update" command with your Subversion client. [This does not apply if you are building Tomcat from a source archive]. For a quick rebuild of only modified code you can use cd ${tomcat.source}/build ant In addition, "ant build-depends" will build packages that tomcat depends on ( commons-logging for now ), to ease fixes and debugging in those packages. (5) 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 (6) Building the servlet and jsp API documentation The documentation can be easily rebuild, do cd ${tomcat.source}/build ant dist-javadoc (7) 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. (8) Running tests do cd ${tomcat.source}/build ant clean-tester run-tester