Author: kkolinko
Date: Tue Nov 15 15:20:17 2011
New Revision: 1202235
URL: http://svn.apache.org/viewvc?rev=1202235&view=rev
Log:
CTR: docs
Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=52172
Update build instructions
- Clarified download behaviour (BZ 52172)
- Added note that building is not necessary to run it.
- Removed mention of using additional build file to download Tomcat sources and
launch build. Our svn structure is simple now and that step is not needed.
Using build/build.xml everywhere.
- Updated instruction for Eclipse IDE. It is a single project now, instead of 4
distinct projects earlier.
Modified:
tomcat/tc5.5.x/trunk/build/BUILDING.txt
tomcat/tc5.5.x/trunk/container/webapps/docs/building.xml
tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml
Modified: tomcat/tc5.5.x/trunk/build/BUILDING.txt
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/build/BUILDING.txt?rev=1202235&r1=1202234&r2=1202235&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/build/BUILDING.txt (original)
+++ tomcat/tc5.5.x/trunk/build/BUILDING.txt Tue Nov 15 15:20:17 2011
@@ -21,10 +21,15 @@ $Id$
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:
+Community Process <http://www.jcp.org/>.
+
+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
@@ -70,44 +75,43 @@ is known to work). Do the following:
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.
+(2) Checkout or obtain the source code for Tomcat 6.0
-* If Subversion 1.3.x or later is already installed on your computer, skip to
(3).
+* Tomcat 5.5 SVN repository URL:
+ http://svn.apache.org/repos/asf/tomcat/tc5.5.x/
-* Download a binary distribution of Subversion 1.3.x or later from:
+* Download a source package from:
+ http://tomcat.apache.org/download-55.cgi
- http://subversion.tigris.org/getting.html
+* Checkout the source using SVN, selecting the desired version or
+ branch (current development source is at
+ http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/), or
+ unpack the source package. The location where the source has been
+ placed will be referred as ${tomcat.source}.
-* 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]
+* 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.
-* 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:
@@ -120,31 +124,26 @@ is known to work). Do the following:
# ----- Default Base Path for Dependent Packages -----
# Replace this path with the directory path where dependencies binaries
# should be downloaded
- base.path=/usr/share/java
+ base.path=/home/me/some-place-to-download-to
-(4) Updating sources
+(4) Updating sources and Rebuilds
-It is recommended that you regularly update the downloaded Tomcat 5 sources.
-To do this, execute the following commands:
-
- cd ${tomcat.source}
- svn update
+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].
-(5) Rebuilds
-
For a quick rebuild of only modified code you can use
cd ${tomcat.source}/build
- ant 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.
-(6) Building The "compat" Package
+(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
@@ -155,13 +154,13 @@ package, do
cd ${tomcat.source}/build
ant compat
-(7) Building the servlet and jsp API documentation
+(6) 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:
+(7) Building a release running tests:
Ensure that 'full.dist=on' is set in build.properties
and do
@@ -170,7 +169,7 @@ and do
Note that this deletes any existing build output.
-(9) Running tests
+(8) Running tests
do
cd ${tomcat.source}/build
Modified: tomcat/tc5.5.x/trunk/container/webapps/docs/building.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/building.xml?rev=1202235&r1=1202234&r2=1202235&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/building.xml (original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/building.xml Tue Nov 15
15:20:17 2011
@@ -93,38 +93,50 @@ available, which will be used to actuall
</section>
-<section name="Building Tomcat">
+<section name="Checkout or obtain the source code for Tomcat 5.5">
<p>
-Download the main build.xml script from <a href="build.xml">here</a>.
+Tomcat 5.5 SVN repository URL:
+<code>http://svn.apache.org/repos/asf/tomcat/tc5.5.x/trunk/</code>
+</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>
-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.
+Checkout the source using SVN, 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>
-Go to that directory, and do:
+Use the following commands:
<code><br/>
- cd ${tomcat.source}<br/>
+ cd ${tomcat.source}/build<br/>
+ ant download<br/>
ant<br/>
</code>
</p>
<p>
-NOTE: Users accessing the Internet through a proxy must use a properties
- file to indicate to Ant the proxy configuration. Read below.
+<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>
-WARNING: Running this command will checkout the Tomcat 5 sources from SVN, as
- well as download binaries to the <code>/usr/share/java</code> directory.
- Make sure this is appropriate to do so on your computer. On Windows,
- this usually corresponds to the <code>C:\usr\share\java</code> directory,
- unless Cygwin is used. Read below to customize the directory used
- to download the binaries.
+<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>
@@ -140,29 +152,33 @@ The build can be controlled by creating
# ----- Default Base Path for Dependent Packages -----<br/>
# Replace this path with the directory path where<br/>
# dependencies binaries should be downloaded.<br/>
- base.path=/usr/share/java<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 sources.
-To do this, execute the following commands:
-
-<code><br/>
- cd ${tomcat.source}<br/>
- ant checkout<br/>
-</code>
+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}<br/>
- ant build<br/>
+ cd ${tomcat.source}/build<br/>
+ ant<br/>
</code>
</p>
@@ -183,9 +199,9 @@ and the following steps have been used b
<p>
Note that you <b>must</b> complete all the above steps to fetch
-the repositories and build some JAR files the first time.
-After you have completed the above steps, you can set up a
-series of Eclipse 4 projects.
+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.
@@ -194,10 +210,6 @@ get warnings, reformat code, perform ref
under the IDE, and so on.
</p>
-<p>You will want to set up your Eclipse project for building Tomcat such that
-${tomcatSource} is the Workspace folder.
-</p>
-
<p>
Use Windows->Preferences and then Java->Build Path->Classpath
Variables to add two new Classpath variables:
@@ -211,21 +223,21 @@ Variables to add two new Classpath varia
</p>
<p>
-Use File->New Project to create a new Java project
-for each of the binaries repository (e.g., /usr/share/java),
-container, connectors, jasper, servletapi.
-If you didn't already set up the Eclipse project such that ${tomcat.source}
-is the Workspace folder, do so now:
-tell Eclipse the external location using "Import/Export...",
-General->Existing Project into Workspace.
+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>
-Eclipse .project and .classpath files are provided in each of these
-directories so Eclipse should find all source trees and jars, and
+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; also, the
-connectors module must be built with a compiler compliance level of 5.0.
+files assume you are using Eclipse with a 5.0 or later JDK.
</p>
<p>
@@ -236,15 +248,6 @@ enter "org.apache.catalina.startup.Catal
as VM arguments.
</p>
-<p>
-Note also that due to the way the Tomcat source is assembled
-from several SVN projects, you may not be able to use the Eclipse
-SVN client to update (nor to commit, if you are a committer).
-Use the external SVN client of your choice, then use the
-Eclipse PackageExplorer or Navigator "Refresh" context menu item
-to tell Eclipse that you've updated the files.
-</p>
-
</section>
<section name="Building with other IDEs">
Modified: tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml?rev=1202235&r1=1202234&r2=1202235&view=diff
==============================================================================
--- tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml (original)
+++ tomcat/tc5.5.x/trunk/container/webapps/docs/changelog.xml Tue Nov 15
15:20:17 2011
@@ -54,6 +54,10 @@
service: correct information on how a JRE is identified and selected.
(kkolinko)
</fix>
+ <update>
+ <bug>52172</bug>: Update Tomcat build instructions. Includes changes
+ proposed by bmargulies. (kkolinko)
+ </update>
</changelog>
</subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
