remm 2002/10/28 01:36:33 Modified: . BUILDING.txt Log: - Update building to use the new autoconfiguration (less configurable, but far easier). - Of course, developers may choose to do everything manually ;-) Revision Changes Path 1.26 +53 -518 jakarta-tomcat-5/BUILDING.txt Index: BUILDING.txt =================================================================== RCS file: /home/cvs/jakarta-tomcat-5/BUILDING.txt,v retrieving revision 1.25 retrieving revision 1.26 diff -u -r1.25 -r1.26 --- BUILDING.txt 11 Oct 2002 10:59:05 -0000 1.25 +++ BUILDING.txt 28 Oct 2002 09:36:33 -0000 1.26 @@ -7,14 +7,15 @@ This subproject contains the source code for Tomcat 5, a container that implements the Servlet 2.4 and the 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 must have -a Java Development Kit (JDK) for version 1.3 (or later) downloaded and -x installed (version 1.3.1 recommended), and do the following: +distribution version of the container from a source distribution, +do the following: (0) Download and Install a Java Development Kit -* Download a Java Development Kit (JDK) release (version 1.3 or later) from: +* If the JDK is already installed, skip to (1). + +* Download a Java Development Kit (JDK) release (version 1.4 or later) from: http://java.sun.com/j2se/ @@ -24,21 +25,25 @@ into which you installed the JDK release. -(1) Download and Install the Ant Binary Distribution +(1) Install Apache Ant 1.5.1 on your computer + +* If Apache Ant 1.5.1 is already installed on your computer, skip to (2). -* Download a binary distribution of Ant 1.5 from: +(1.1) Download and Install the Ant Binary Distribution - http://jakarta.apache.org/builds/jakarta-ant/release/v1.5/bin/ +* Download a binary distribution of Ant 1.5.1 from: + + http://jakarta.apache.org/builds/jakarta-ant/release/v1.5.1/bin/ On a Windows platform, you will need: - jakarta-ant-1.5-bin.zip + jakarta-ant-1.5.1-bin.zip On a Unix platform, you will need: - jakarta-ant-1.5-bin.tar.gz + jakarta-ant-1.5.1-bin.tar.gz * Unpack the binary distribution into a convenient location so that the Ant release resides in its own directory (conventionally named - "jakarta-ant-1.5"). For the purposes of the remainder of this document, + "jakarta-ant-1.5.1"). 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. @@ -47,45 +52,7 @@ available, which will be used to actually perform the build. -(2) Download and Install the Java XML Pack Binary Distribution - -* Download a binary distribution of Java XML Pack: - - http://java.sun.com/xml/downloads/javaxmlpack.html - -* Unpack the binary distribution into a convenient location so that the - Java XML Pack release resides in its own directory (the JAXP libraries - reside in the jaxp-1.1.3 subdirectory). For the purposes of the - remainder of this document, the symbolic name "${jaxp.home}" is used - to refer to the full pathname to the jaxp-1.1.3 subdirectory of the - Java XML Pack release directory. - -* Make the "xalan.jar" file of this distribution available to Ant (so that - it can be used with the <style> tag) by copying it to "${ant.home}/lib". - -* This is optional with JDK 1.4 or later. - - -(3) Download and Install the JNDI 1.2.1 Reference Implementation - -* Download the Java Naming and Directory Interface (JNDI) package, - (version 1.2.1 or later) from - - http://java.sun.com/products/jndi/ - -* Unpack the reference implementation into a convenient location so that - it resides in its own subdirectory. - -* You will also need the LDAP Service Provider Maintenance package, - (version 1.2.3 or later) available on the same download page. Be sure - that you unpack "ldap.jar" and "jaas.jar" into the "lib" subdirectory of - the JNDI directory, parallel to "jndi.jar". - -* This is optional with JDK 1.3 or later. It is required for building - with full.dist=on. The build process expects this to be in - {base.path}/jndi-1.2.1. - -(4) Download and Install the Xerces 2 Distribution +(1.2) Download and Install the Xerces 2 Distribution * Download a binary distribution of version 2.0.1 from: @@ -101,488 +68,56 @@ distribution resides in its own directory (conventionally named "xerces-x_y_z"). - -(5) Download and Install Subproject Source Code - -* Use Anonymous CVS (as described on the Jakarta web site at - <http://jakarta.apache.org/site/cvsindex.html>, or - download a source distribution from: - - http://jakarta.apache.org/builds/jakarta-tomcat-5/nightly/src/ - - On a Windows platform, you will need: - jakarta-tomcat-5-src-YYYYMMDD.zip - - On a Unix platform, you will need: - jakarta-tomcat-5-src-YYYYMMDD.tar.gz - - (NOTE: Alternatively, you can grab the source distribution from a - formal release, if you wish, by following links on the Jakarta web site). - -* Unpack the source distribution into a convenient location so that the - distribution resides in its own directory (conventionally named - "jakarta-tomcat-5"). For the purposes of the remainder of this document, - the symbolic name "${tomcat.source}" is used to refer to the full - pathname of the release directory. - -* Use Anonymous CVS (as described on the Jakarta web site at - <http://jakarta.apache.org/site/cvsindex.html>, or - download a source distribution of the "jakarta-tomcat-catalina" repository. - -* Unpack the source distribution into a convenient location so that the - distribution resides in its own directory (conventionally named - "jakarta-tomcat-catalina"). By default, the build system will try to find - this repository in the "${tomcat.source}/../jakarta-tomcat-catalina" - directory. Set the "catalina.home" property in the build.properties file - described below (see 30) if it resides in a different directory. - -* Use Anonymous CVS (as described on the Jakarta web site at - <http://jakarta.apache.org/site/cvsindex.html>, or - download a source distribution of the "jakarta-tomcat-connectors" repository. - -* Unpack the source distribution into a convenient location so that the - distribution resides in its own directory (conventionally named - "jakarta-tomcat-connectors"). By default, the build system will try to find - this repository in the "${tomcat.source}/../jakarta-tomcat-connectors" - directory. Set the "jtc.home" property in the build.properties file - described below (see 30) if it resides in a different directory. - -* Use Anonymous CVS (as described on the Jakarta web site at - <http://jakarta.apache.org/site/cvsindex.html>, or - download a source distribution of the "jakarta-tomcat-jasper/jasper2" - repository. - -* Unpack the source distribution into a convenient location so that the - distribution resides in its own directory (conventionally named - "jakarta-tomcat-jasper/jasper2"). By default, the build system will try to - find this repository in the - "${tomcat.source}/../jakarta-tomcat-jasper/jasper2" directory. Set the - "jasper.home" property in the build.properties file described below (see 30) - if it resides in a different directory. - -* Use Anonymous CVS (as described on the Jakarta web site at - <http://jakarta.apache.org/site/cvsindex.html>, or - download a source distribution of the "jakarta-servletapi-5" repository. - -* Unpack the source distribution into a convenient location so that the - distribution resides in its own directory (conventionally named - "jakarta-servletapi-5"). By default, the build system will try to find - this repository in the "${tomcat.source}/../jakarta-servletapi-5" - directory. Set the "api.home" property in the build.properties - file described below (see 30) if it resides in a different directory. - - -(6) Download and Install the Commons Beanutils Binary Distribution - -* Download a binary distribution of Version 1.4 or later from: - - http://jakarta.apache.org/builds/jakarta-commons/release/commons-beanutils - - On a Windows platform, you will need: - commons-beanutils-X.Y.zip - - On a Unix platform, you will need: - commons-beanutils-X.Y.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(7) Download and Install the Commons Collections Binary Distribution - -* Download a binary distribution of Version 2.0 or later from: - - http://jakarta.apache.org/builds/jakarta-commons/release/commons-collections - - On a Windows platform, you will need: - commons-collections-X.Y.zip - - On a Unix platform, you will need: - commons-collections-X.Y.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(8) Download and Install the Commons Digester Binary Distribution - -* Download a binary distribution (version 20020820 or later) from: - http://jakarta.apache.org/builds/jakarta-commons/nightly/commons-digester - - On a Windows platform, you will need: - commons-digester-YYYYMMDD.zip - - On a Unix platform, you will need: - commons-digester-YYYYMMDD.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(9) Download and Install the Commons Logging Binary Distribution - -* Download a binary distribution (version 1.0.1 or later) from: - - http://jakarta.apache.org/builds/jakarta-commons/release/commons-logging - - On a Windows platform, you will need: - commons-logging-X.Y.Z.zip - - On a Unix platform, you will need: - commons-logging-X.Y.Z.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(10) Download and Install the Regexp Binary Distribution - -* Download a binary distribution of Version 1.2 or later from: - - http://jakarta.apache.org/builds/jakarta-regexp/release/ - - On a Windows platform, you will need: - jakarta-regexp-X.Y.zip - - On a Unix platform, you will need: - jakarta-regexp-X.Y.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(11) Download and Install the Commons Launcher Binary Distribution - -* Download a binary distribution of version 20021012 or later from: - - http://jakarta.apache.org/builds/jakarta-commons/nightly/commons-launcher - - On a Windows platform, you will need: - commons-launcher-YYYYMMDD.zip - - On a Unix platform, you will need: - commons-launcher-YYYYMMDD.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(12) Steps (13)-(27) are optional, but are necessary to build a complete binary - distribution of Tomcat 5. Set the "full.dist" property to "on" in the - build.properties file (see 30) to build a complete distribution. - Regular contributors to Tomcat are encouraged to use the complete build - option. - - -(13) Download and Install JDBC Optional Package API Binary Distribution - -* Download the JDBC Optional Pacakge API package (version 2.0) from: - - http://java.sun.com/products/jdbc/download.html - -* Place the jar in a convenient location. The build process expects it - in ${base.path}/jdbc2_0-stdext. - -* No Tomcat class depends on JDBC directly. Tyrex and commons-dbcp - depend on it, and it is distributed with a full distribution. - -(14) Download and Install an implementation of the JMX 1.0 specification. This - can be either MX4J (http://mx4j.sourceforge.net) or Sun JMX 1.0 Reference - Implementation. - -NOTE: This step is only required if you wish to build the Config/Admin -web application. - -NOTE: The Tomcat binaries are distrbuted with MX4J. - -* Download MX4J (version 1.1 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 - -* Unpack MX4J or the reference implementation into a convenient location - so that it resides in its own subdirectory. - -(15) Download and Install the Java Activation Framework 1.0.1 - -* Download the Java Activation Framework package (version 1.0.1 or later) from - - http://java.sun.com/products/javabeans/glasgow/jaf.html - -* Unpack the package into a convenient location so that it - resides in its own subdirectory. The build process expects this by - default to be in ${base.path}/jaf-1.0.1 - -* The Java Activation Framework is used by the JavaMail optional package. - - -(16) Download and Install JavaMail 1.2 - -* Download the JavaMail package (version 1.2 or later) from - - http://java.sun.com/products/javamail/index.html - -* Unpack the package into a convenient location so that - it resides in its own subdirectory. The build process expects this - by default to be in ${base.path}/javamail-1.2 - -* JavaMail is used to provide JNDI named mail sessions. - - -(17) 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/ - -* Unpack the reference implementation into a convenient location so that - it resides in its own subdirectory. The build expects this to be in - ${base.path}/jsse-1.0.2. - -* This is optional with JDK 1.4 and later. - -* Used to provide SSL and Certificate support in Catalina and in Connectors. - - -(18) Download and Install the Java Transaction APIs - -* Download the Java Transaction API (JTA) package (version 1.0.1a) from: - - http://java.sun.com/products/jta/ - -* Unpack the package into a convenient location so that it resides in its - own subdirectory. By default, the Tomcat build expects this to be - {base.path}/jta-1_0_1a/ - -* Used to provide JNDI named transaction factories. - - -(19) Download and Install the Struts Binary Distribution - -* Download a binary distribution of Struts 1.0.2 from: - - http://jakarta.apache.org/builds/jakarta-struts/release/v1.0.2/ - - On a Windows platform, you will need: - jakarta-struts-1.0.2.zip - - On a Unix platform, you will need: - jakarta-struts-1.0.2.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(20) Download and Install the Tyrex Data Source Package - -NOTE: This step is only required if you wish to build the Tyrex connection -pool implementation for JNDI-accessed data sources. - -* Download the Tyrex JAR or release (version 1.0) from: - - http://telia.dl.sourceforge.net/sourceforge/tyrex/tyrex-1.0.jar - -* Unpack the package into a convenient location so that it resides in its - own subdirectory. - - -(21) Download and Install the JUnit Testing Package (OPTIONAL) - -NOTE: This step is only required if you wish to build and execute the unit -tests that are part of the Tomcat 5 source base. - -* Download the JUnit unit test package (version 3.7 or later) from: - - http://www.junit.org/ - -* Unpack the package into a convenient location so that it resides in its - own subdirectory. - - -(22) Download and Install the Commons Modeler Binary Distribution - -NOTE: This step 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 - - On a Windows platform, you will need: - commons-modeler-X.Y.zip - - On a Unix platform, you will need: - commons-modeler-X.Y.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(23) Download and Install the Commons DBCP Binary Distribution - -NOTE: This step 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-dbcp - - On a Windows platform, you will need: - commons-dbcp-X.Y.zip - - On a Unix platform, you will need: - commons-dbcp-X.Y.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - -(24) Download and Install the Commons Pool Binary Distribution - -NOTE: This step is only required if you wish to use the database JDBC data -source factory. - -* Download a binary distribution of version 1.0.1 or later from: - - http://jakarta.apache.org/builds/jakarta-commons/release/commons-pool - - On a Windows platform, you will need: - commons-pool-X.Y.Z.zip - - On a Unix platform, you will need: - commons-pool-X.Y.Z.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(25) Download and Install the PureTLS SSL Distribution - -NOTE: This step is only required if you wish to use an SSL distribution other -than the JSSE distribution. - -* Download a binary distribution of version 0.9b2 or later from: - - http://www.rtfm.com/puretls/ - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(26) Download and Install the JavaService Distribution (Windows Only) - -NOTE: This step is only required if you wish to create a Windows NT service. - -* Download a binary distribution of version 1.2.0 or later from: - - http://www.alexandriasc.com/software/JavaService/JavaService-bin-1.2.0.zip - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(27) Download and Install the Nullsoft Install Distribution (Windows Only) - -NOTE: This step is only required if you wish to create a Windows installer. - -* Download a binary distribution of version 2.0a6 from: - - http://telia.dl.sourceforge.net/sourceforge/nsis2k/nsis20a6.exe - -* Execute the downloaded binary distribution a install in the default - installation directory. - - -(28) Download and Install the Servlet 2.3 Binary Distribution (OPTIONAL) - -NOTE: This step is only required if you wish to build and execute the -Watchdog compliance tests. - -* Download a binary distribution (version 20020801 or later) from: - http://jakarta.apache.org/builds/jakarta-servletapi-4/nightly - - On a Windows platform, you will need: - jakarta-servletapi-4-YYYYMMDD.zip - - On a Unix platform, you will need: - jakarta-servletapi-4-YYYYMMDD.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. - - -(29) Download and Install the Watchdog Binary Distribution (OPTIONAL) - -NOTE: This step is only required if you wish to build and execute the -Watchdog compliance tests. - -* Download a binary distribution (version 20020801 or later) from: - http://jakarta.apache.org/builds/jakarta-watchdog-4.0/nightly - - On a Windows platform, you will need: - jakarta-watchdog-4.0-YYYYMMDD.zip - - On a Unix platform, you will need: - jakarta-watchdog-4.0-YYYYMMDD.tar.gz - -* Unpack the binary distribution into a convenient location so that the - distribution resides in its own directory. +* Copy the xalan.jar file from that distribution to the "${ant.home}/lib" + directory. -(30) Customize Build Properties For This Subproject +(2) Building Tomcat 5 -Most Jakarta subprojects allow you to customize Ant 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 for this. +(2.1) Download main build script and build binary distribution -Tomcat has many external dependencies that are satisfied by configuring -appropriate values in your build.properties file. The easiest -way to satisfy these dependencies is to copy the "build.properties.sample" -file (in the top-level Tomcat source directory) to "build.properties", and -then edit it to suit your environment. On Unix, this would be done as: +* Download the main build.xml script from: + http://jakarta.apache.org/builds/jakarta-tomcat/build-5/build.xml - cd ${tomcat.source} - cp build.properties.sample build.properties - emacs build.properties +* 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 -NOTE: 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. +(2.2) Building +* Go to that directory, and do: -(31) Build A Binary Distribution + cd ${tomcat.source} + ant -Open a command line shell, and issue the following commands: +* NOTE: Users accessing the Internet through a proxy must use a properties + file to indicate to Ant the proxy configuration. Read below. - cd ${tomcat.source} - ant -projecthelp +* WARNING: Running this command will checkout the Tomcat 5 sources from CVS, as + well as download binaries to the "/usr/local" directory. Make sure this is + appropriate to do so on your computer. On Windows, this usually corresponds + to the "C:\usr\local" directory, unless Cygwin is used. Read below to + customize the directory used to download the binaries. -If everything is installed correctly, you should see a list of the Ant -"targets" that represent different commands you might wish to build. +* The build can be controlled by creating a ${tomcat.source}/build.properties + file, and adding the following content to it: -You can check that all dependencies are correctly installed by using -the following commands: + # ----- Proxy setup ----- + # Uncomment if using a proxy server + #proxy.host=proxy.domain + #proxy.port=8080 + #proxy.use=on - cd ${tomcat.source} - ant detect + # ----- Default Base Path for Dependent Packages ----- + # Replace this path with the directory path where dependencies binaries + # should be downloaded + base.path=/usr/local -By convention, the "dist" target creates a complete binary distribution. To -execute it, type the following commands: - cd ${tomcat.source} - ant dist +(3) Updating sources -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. +It is recommended to regularly update the downloaded Tomcat 5 sources. +To do this, execute the following commands: -See the document RUNNING.txt for instructions on how to start up and shut down -the Tomcat 5 Servlet/JSP container. + cd ${tomcat.source} + ant checkout
-- To unsubscribe, e-mail: <mailto:tomcat-dev-unsubscribe@;jakarta.apache.org> For additional commands, e-mail: <mailto:tomcat-dev-help@;jakarta.apache.org>