This is the revised BUILDING.txt that I propose:
Building The Tomcat 4.1 Servlet/JSP Container
=============================================
This subproject contains the source code Tomcat 4.1, a server that implements
the Servlet 2.3 and JSP 1.2 Specifications from Java Software. In order to build
a binary distribution version of the container from a source distribution, you
must have a Java Development Kit (JDK) for version 1.3 (or later) downloaded and
installed (version 1.3.1 recommended).
Each package described below should be unpacked into its own subdirectory. To
minimize the changes to the build.properties file, it is convenient to store the
separate distributions below in subdirectories of one and the same directory.
E.g.
../jakarta
../jakarta/jakarta-ant-1.5
../jakarta/jakarta-tomcat-4.1.7-src
etc.
Building Jakarta-Tomcat 4.1 from source requires approximately 180 MB disk
space, varying with how many of the depending packages you compile from source.
(0) Download and Install a Java Development Kit
* Download a Java Development Kit (JDK) version 1.3 or later or a Standard
Edition Software Development Kit (J2SE SDK) version 1.4 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) Download and Install Ant
* Ant 1.5 or later is required. Download a binary distribution from
http://jakarta.apache.org/builds/jakarta-ant/release/v1.5/bin/
* Unpack the binary distribution into a convenient location so that the Ant
release resides in its own directory (conventionally named "jakarta-ant-1.5").
The symbolic name "${ant.home}" refers to the full pathname of the Ant release
directory.
* 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.
* You can test your installation of Ant by typing "ant -help" at the command prompt.
(2) Download and Install the Tomcat Subproject Source Code
* Use anonymous CVS as described on http://jakarta.apache.org/site/cvsindex.html
or download a current source distribution from:
http://jakarta.apache.org/builds/jakarta-tomcat-4.0/nightly/src/
If you want to compile the latest release, you will find the sources at
http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/
Unpack the files into a convenient location, preferably in an empty
subdirectory (that will later also be populated with supporting packages and
distributions.)
* The symbolic name "${tomcat.source}" is used to refer to the full pathname of
the release directory.
(3) Automatic download of libraries and subprojects
* To build Tomcat, several libraries and subprojects are needed. The easiest way
to get them is to use the download build target to do automated download.
As the download proceeds, ant will use CVS to download sources that have not
yet had formal releases. For this to work, you need to have the cvs command
available in your PATH environment variable. If you don't have a CVS command-
line client, you can download sources or binaries from
http://www.cvshome.org/downloads.html
To automatically download the needed packages into, issue the command
ant download
This will fetch the packages described below for building the complete Tomcat
distribution into a directory hierarchy rooted in ../ resulting in a
convenient structure.
If the downloads completes without errors, you can now continue with step (27),
"Building a binary distribution".
If you are behind a firewall or using a proxy, you can edit the network
settings in build.properties.
(4) Manual download and installation
* If the download fails or for some reason you want to fetch the files manually,
read on.
* If you are working in a Microsoft Windows environment, you may want to use the
zip files available from the directories listed below. If you are working in a
Unix- like environment the tar.gz-files may suit you better.
(5) Download and Install Packages for JDK Version 1.3
* If you are using J2SDK version 1.4 or later you can skip this step
* If you are using the JDK version 1.3 you need to download
- The JNDI Reference Implementation version 1.2.1 or later and
- The LDAP Service Provider Maintenance package version 1.2.3 or later
They can both be found at
http://java.sun.com/products/jndi/
These files unpack into the current directory. It is therefore convenient to
create a directory (conventionally named jndi-1.2.1) and unpack them both
there so that "ldap.jar" and "jaas.jar" (from the LDAP package) resides in
the "lib" subdirectory of the JNDI directory, parallel to "jndi.jar".
- The Java XML Pack Binary Distribution version 1.1.3 or later
It can be found at
http://java.sun.com/xml/downloads/javaxmlpack.html
The symbolic name "${jaxp.home}" is used to refer to the full pathname to
the jaxp-1.x subdirectory of the Java XML Pack release directory.
Make the "xalan.jar" file in the of this distribution available to Ant (so
that it can be used with the <style> tag) by copying it to
"${ant.home}/lib". It is located in the jaxp-1.x subdirectory of the
distribution.
- Xerces version 1 or 2 binary distribution
It can be found at
http://xml.apache.org/dist/xerces-j/
In your build.properties file, you will need to set properties differently
based on which version of Xerces you are using:
- For versions 1.3.1 up through and including 2.0.0beta3, uncomment the
Xerces 1.4.4... section in the build.properties file.
- If you have defined both sets of properties, the newer (two files)
packaging will be loaded into the Tomcat you are building
(6) Download and Install the Jakarta-Tomcat-Connectors Subproject
* Use anonymous CVS as described on http://jakarta.apache.org/site/cvsindex.html
or download a source or binary distribution from:
http://jakarta.apache.org/builds/jakarta-tomcat-4.0/release/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../jakarta-tomcat-connectors" directory.
* The symbolic name "${jtc.home}" is used to refer to the full pathname of the
release directory.
(7) Download and Install the Servlet API Distribution
* Download a source or binary distribution from:
http://jakarta.apache.org/builds/jakarta-servletapi-4/nightly/
* Alternatively, use the binary distribution that is available with binary
distributions of Tomcat 4.0.
* By default, the build system will try to find this repository in the
"${tomcat.source}/../jakarta-servletapi-4" directory.
(8) Download and Install the Commons Beanutils Distribution
* Download a source or binary distribution of version 1.1 or later from:
http://jakarta.apache.org/builds/jakarta-commons/release/commons-beanutils
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-beanutils-1.3" directory.
(9) Download and Install the Commons Collections Distribution
* Download a soure or binary distribution of version 1.0 or later from:
http://jakarta.apache.org/builds/jakarta-commons/release/commons-collections
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-collections-2.0" directory.
(10) Download and Install the Commons Digester Distribution
* Download a source or binary distribution of version 1.1.1 or later from:
http://jakarta.apache.org/builds/jakarta-commons/release/commons-digester
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-digester-1.2" directory.
(11) Download and Install the Commons Logging Distribution
* Download a source or binary distribution of version 1.0.1 or later (nightly
build for now) from:
http://jakarta.apache.org/builds/jakarta-commons/nightly/commons-logging
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-logging-1.0.1" directory.
(12) Download and Install the Regexp Distribution
* Download a source or binary distribution of version 1.2 or later from:
http://jakarta.apache.org/builds/jakarta-regexp/release/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../jakarta-regexp-1.2" directory.
(13) Downloading for a complete Tomcat distribution
* Steps 13-25 are optional, but are necessary to build a complete binary
distribution of Tomcat 4.0.
* Set the "full.dist" property to "on" in the build.properties file (see step
26) to build a complete distribution. Regular contributors to Tomcat are
encouraged to use the complete build option.
(14) Download and Install Packages for JDK Version 1.3
* If you are using J2SDK version 1.4.0 or later you can skip this step.
* If you are using the JDK version 1.3 you need to download
- The JDBC Optional Package API
It can be found at
http://java.sun.com/products/jdbc/download.html
If necessary, rename the .jar file to jdbc2_0-stdext.jar.
By default, the build system will try to find this repository in the
"${tomcat.source}/../jdbc2_0-stdext" directory.
- Download and Install the JSSE 1.0.2 Reference Implementation
Download the Java Secure Sockets Extension (JSSE) package version 1.0.2 or
later from
http://java.sun.com/products/jsse/
By default, the build system will try to find this repository in the
"${tomcat.source}/../jsse-1.0.2" directory.
(15) Download and Install an Implementation of the JMX 1.0 Specification.
* This is only required if you wish to build the Config/Admin web application.
* This can be either MX4J (http://mx4j.sourceforge.net) or Sun JMX 1.0 Reference
Implementation. The Tomcat binaries are distributed with MX4J.
- Download MX4J (version 1.0 or later) from
http://sourceforge.net/project/showfiles.php?group_id=47745
- Alternately, download the JMX Instrumentation and Agent Reference
Implementation (version 1.0 or later) from
http://java.sun.com/products/JavaManagement/download.html
* By default, the build system will try to find this repository in the
"${tomcat.source}/../mx4j-1.1" directory.
(16) Download and Install the Java Activation Framework
* Download the Java Activation Framework package version 1.0.1 or later from
http://java.sun.com/products/javabeans/glasgow/jaf.html
* By default, the build system will try to find this repository in the
"${tomcat.source}/../jaf-1.0.2" directory.
(17) Download and Install JavaMail 1.2
* Download the JavaMail package version 1.2 or later from
http://java.sun.com/products/javamail/index.html
* By default, the build system will try to find this repository in the
"${tomcat.source}/../javamail-1.2" directory.
(18) Download and Install the Java Transaction APIs
* Download the Java Transaction API (JTA) package version 1.0.1 or later from:
http://java.sun.com/products/jta/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../jta-spec1_0_1" directory.
(19) Download and Install the Struts Binary Distribution
* Download a binary distribution of Struts 1.0.1 or later from:
http://jakarta.apache.org/builds/jakarta-struts/release/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../jakarta-struts-1.0.2" directory.
(20) Download and Install the Tyrex Data Source Package
* Download the Tyrex JAR or release version 1.0 or later from:
http://tyrex.exolab.org/download.html
* By default, the build system will try to find this repository in the
"${tomcat.source}/../tyrex-1.0" directory.
(21) Download and Install the JUnit Testing Package
* This is only required if you wish to build and execute the unit tests that are
part of the Tomcat 4.0 source base.
* Download the JUnit unit test package version 3.7 or later from:
http://www.junit.org/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../junit3.7" directory.
(22) Download and Install the Commons Modeler Binary Distribution
* This is only required if you wish to build the Config/Admin web application.
* Download a binary distribution of version 1.0 or later from:
http://jakarta.apache.org/builds/jakarta-commons/release/commons-modeler
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-modeler-1.0" directory.
(23) Download and Install the Commons DBCP Binary Distribution
* This is only required if you wish to use the database JDBC data source
factory.
* Download a source or binary distribution from:
http://jakarta.apache.org/builds/jakarta-commons/nightly/commons-dbcp/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-dbcp" directory.
(24) Download and Install the Commons Pool Binary Distribution
* This is only required if you wish to use the database JDBC data source
factory.)
* Download a binary distribution of version 1.0 or later from:
http://jakarta.apache.org/builds/jakarta-commons/release/commons-pool/
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-pool-1.0" directory.
(25) Download and Install the Commons Daemon Binary Distribution
* This is only required if you wish to be able to run Tomcat as a native
operating system daemon using commons-daemon.
* Use anonymous CVS as described on http://jakarta.apache.org/site/cvsindex.html
to download a source distribution of version 20020219 or later.
* By default, the build system will try to find this repository in the
"${tomcat.source}/../commons-daemon" directory.
(26) Customize Build Properties for this Subproject
* Most Jakarta subprojects allow you to customize build properties (with default
values defined in the "build.xml" file. This is done by creating a text file
named "build.properties" in the source distribution directory (for property
definitions local to this subproject) and/or your user home directory (for
property definitions shared across subprojects).
* You can use the included "build.properties.sample" file as a starting point
and adjust the properties, e.g. the locations of the packages described above.
* Be *sure* that you do not check "build.properties" in to the CVS repository.
This file is local to your own development environment, and each developer
will have their own version.
(27) Build A Binary Distribution
* Assuming you have a command shell open with ${tomcat.source} as the current
directory, you can issue the following command:
ant -projecthelp
* If everything is installed correctly, you should see a list of the Ant
"targets" you might wish to build and short explanations for them.
* You can check that all dependencies are correctly installed by using the
following command:
ant detect
* By convention, the "dist" target creates a complete binary distribution. To
execute it, type the following commands:
ant dist
* This will create a complete binary distribution of the subproject (equivalent
in structure to the corresponding binary distribution downloadable from the
Jakarta web site), in the "${tomcat.source}/dist" directory. It will have the
contents described in the corresponding "README.txt" file.
* See the document RUNNING.txt for instructions on how to start up and shut down
the servlet/JSP container.
(28) Keeping your source up-to-date and contributing to the project
* If you want access to the latest sources for any reason, you should definitely
consider using CVS to get the source tree. You can find more information on
using CVS with the Jakarta project at
http://jakarta.apache.org/site/cvsindex.html
* If you want to contribute to the project in any way, you will find essential
information at
http://jakarta.apache.org/site/guidelines.html
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
