| <?xml version="1.0"?> |
| <!-- |
| 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. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document> |
| |
| &project; |
| |
| <properties> |
| <author>Remy Maucherat</author> |
| <title>Building Tomcat</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| |
| <section name="README"> |
| <p> |
| This document duplicates some of the information from the BUILDING.txt file |
| included in every Tomcat distribution. You may want to consult both. |
| </p> |
| </section> |
| |
| <section name="Introduction"> |
| |
| <p> |
| Building Tomcat from SVN 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> |
| 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. |
| </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.6.2 or later"> |
| |
| <p> |
| Download a binary distribution of Ant 1.6.2 or later 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 |
| "apache-ant-1.6.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. |
| </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="Checkout or obtain the source code for Tomcat 5.5"> |
| |
| <p> |
| Tomcat 5.5 SVN repository URL: |
| <a href="http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/">http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/</a> |
| </p> |
| <p> |
| Tomcat 5.5 source packages: |
| <a href="http://tomcat.apache.org/download-55.cgi">http://tomcat.apache.org/download-55.cgi</a>. |
| </p> |
| |
| <p> |
| Checkout the source using SVN, selecting a tag for released version or |
| trunk for the current development code, or download and unpack a |
| source package. For the remainder of this guide, the symbolic name |
| <code>${tomcat.source}</code> is used to refer to the |
| location where the source has been placed. |
| </p> |
| |
| </section> |
| |
| <section name="Building Tomcat"> |
| |
| <p> |
| Use the following commands: |
| <code><br/> |
| cd ${tomcat.source}/build<br/> |
| ant download<br/> |
| ant<br/> |
| </code> |
| </p> |
| |
| <p> |
| <b>WARNING:</b> Running "ant download" command will download libraries required |
| to build Tomcat to the <code>/usr/share/java</code> directory by default. |
| 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 <code>C:\usr\share\java</code> directory, |
| unless Cygwin is used. Read below to learn how to customize the directory |
| used to download the binaries. |
| </p> |
| |
| <p> |
| <b>NOTE:</b> Users accessing the Internet through a proxy must use a properties |
| file to indicate to Ant the proxy configuration. Read below. |
| </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=/home/me/some-place-to-download-to<br/> |
| </code> |
| </p> |
| |
| <p> |
| Once the build has completed successfully, a usable Tomcat installation will have been |
| produced in the <code>${tomcat.source}/output/build</code> directory, and can be started |
| and stopped with the usual scripts. |
| </p> |
| |
| <p>See <code>BUILDING.txt</code> file in Tomcat source code for additional |
| build options.</p> |
| |
| </section> |
| |
| <section name="Updating and rebuilding Tomcat sources"> |
| |
| <p> |
| It is recommended to regularly update the downloaded Tomcat 5.5 sources. |
| To do this, execute <code>svn update</code> command with your Subversion client. |
| </p> |
| |
| <p> |
| For a quick rebuild of only modified code you can use: |
| <code><br/> |
| cd ${tomcat.source}/build<br/> |
| ant<br/> |
| </code> |
| |
| </p> |
| |
| </section> |
| |
| <section name="Building with Eclipse"> |
| |
| <p> |
| <b>Important:</b> |
| This is not a supported means of building Tomcat; this information is |
| provided without warranty :-). |
| The only supported means of building Tomcat is with the "ant build" |
| described above. |
| However, some developers like to work on Java code with a Java IDE, |
| and the following steps have been used by some developers. |
| </p> |
| |
| <p> |
| Note that you <b>must</b> complete all the above steps to fetch |
| dependent libraries and build some JAR files the first time. |
| After you have completed the above steps, you can set up an |
| Eclipse project. |
| <b>Note</b> that this will not let you build everything under Eclipse; |
| the build process requires use of Ant for the many stages that aren't |
| simple Java compilations. |
| However, it will allow you to view and edit the Java code, |
| get warnings, reformat code, perform refactorings, run Tomcat |
| under the IDE, and so on. |
| </p> |
| |
| <p> |
| Use Windows->Preferences and then Java->Build Path->Classpath |
| Variables to add two new Classpath variables: |
| </p> |
| |
| <p> |
| <table border="1"> |
| <tr><td>TOMCAT_LIBS_BASE</td><td>the base path where the binary dependencies have been downloaded</td></tr> |
| <tr><td>ANT_HOME</td><td>the base path of Ant 1.6.2 or later</td></tr> |
| </table> |
| </p> |
| |
| <p> |
| There are two files in the root directory, <code>eclipse.classpath</code> and |
| <code>eclipse.project</code>. Create their copies with new names, |
| <code>.classpath</code> and <code>.project</code> respectively. |
| </p> |
| |
| <p> |
| Use File->Import and chose "Existing Projects into Workspace". |
| From there import the root directory where you have checked out tomcat. |
| </p> |
| |
| <p> |
| Eclipse .project and .classpath files provided in the root directory of |
| tomcat repository should allow Eclipse to find all source trees and jars, and |
| hopefully compile without problems. <b>Note</b> that these |
| files assume you are using Eclipse with a 5.0 or later JDK. |
| </p> |
| |
| <p> |
| To run Tomcat without a special IDE plug-in, you can simply use Run->Run... |
| enter "org.apache.catalina.startup.Catalina" as the main class, |
| "start" as program arguments, and |
| "-Dcatalina.home=..." (with the name of your build directory) |
| as VM arguments. |
| </p> |
| |
| </section> |
| |
| <section name="Building with other IDEs"> |
| <p> |
| The same caveats apply as for Eclipse, above. |
| </p> |
| |
| <p> |
| The same general idea should work in most IDEs; it has been reported |
| to work in Idea, for example. |
| </p> |
| |
| </section> |
| |
| </body> |
| </document> |