| 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 |