BUILDING.txt

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

            ====================================================
            Building The Apache Tomcat 6.0 Servlet/JSP Container
            ====================================================

This subproject contains the source code for Tomcat 6.0, a container that
implements the Servlet 2.5 and JSP 2.1 specifications from the Java
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, do the following:


(0) Download and Install a Java Development Kit

* If the JDK is already installed, skip to (1).

* Download a Java Development Kit (JDK) of Java SE version 5 from

    http://www.oracle.com/technetwork/java/javase/downloads/index.html
    or from another JDK vendor.

  Note regarding versions of Java later than Java SE 5:

    As documented elsewhere, one of components in Apache Tomcat includes
    a private copy of the Apache Commons DBCP library. The source code
    for this library is downloaded, processed by the build script
    (renaming the packages) and compiled.

    Due to changes in JDBC interfaces implemented by the library between
    versions of Java SE specification, the library has to target specific
    version of Java and can be compiled only with the JDK version
    implementing this version of specification.

    See Apache Commons DBCP project web site for more details on
    available versions of the library and its requirements,

      http://commons.apache.org/dbcp/

  It is possible to use later versions of JDK to build Tomcat 6.0, but the
  building of that component (tomcat-dbcp.jar) will be skipped and a
  warning will be printed.

* 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.8.x on your computer

* If Apache Ant 1.8.x is already installed on your computer, skip to (2).

* Download a binary distribution of Ant 1.8.x 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) Building Tomcat 6.0

(2.1) Checkout or obtain the source code for Tomcat 6.0

* Tomcat 6.0 SVN repository URL:
  http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/

* Download a source package from:
  http://tomcat.apache.org/download-60.cgi

* Checkout the source using SVN, selecting a tag for released version or
  trunk for the current development code, or unpack a source package. The
  location where the source has been placed will be referred as
  ${tomcat.source}.

(2.2) Building

* Go to that directory, and do:

    cd ${tomcat.source}
    ant download
    ant

* NOTE: Running the "ant download" command will download the libraries required
  to build Tomcat to the ${user.home}/tomcat-build-libs directory.

* NOTE: Users accessing the Internet through a proxy must use a properties
  file to indicate to Ant the proxy configuration. Read below.

* 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=/home/me/some-place-to-download-to


(3) Updating sources

It is recommended that you regularly update the downloaded Tomcat 6 sources
using your SVN client.

(4) Rebuilds

For a quick rebuild of only modified code you can use:
   
    cd ${tomcat.source}
    ant

(5) Building the servlet and jsp API documentation

    cd ${tomcat.source}
    ant -f dist.xml dist-javadoc

(6) Building the extras (commons-logging, webservices etc.).

    cd ${tomcat.source}
    ant -f extras.xml

(7) Building a release:

    A full release includes the Windows installer which requires a Windows
    environment to be available to create it. If not building in a Windows
    environment, the build scripts assume that Wine is available. If this is not
    the case, the skip.installer property may be set to skip the creation of the
    Windows installer.

    cd ${tomcat.source}
    ant -f dist.xml release

(8) Tests

(8.1) Running Tomcat tests

Tomcat 6 includes a small number of junit tests. (A lot more are available
with Tomcat 7 onwards).

The tests are not run when a release is built. There is separate command to
run them.

To run the testsuite use the following command:

    cd ${tomcat.source}
    ant download
    ant test

It is advisable to redirect output of the above command to a file for later
inspection.

The JUnit reports generated by the tests will be written to the following
directory:

    output/build/logs

By default the testsuite is run three times to test 3 different
implementations of Tomcat connectors: BIO, NIO and APR. (If you are not
familiar with Tomcat connectors, see config/http.html in documentation for
details).

The 3 runs are enabled and disabled individually by the following
properties, which all are "true" by default:

    execute.test.bio=true
    execute.test.nio=true
    execute.test.apr=true

The APR connector can be tested only if Tomcat-Native library binaries are
found by the testsuite. The "test.apr.loc" property specifies the directory
where the library binaries are located.

By default the "test.apr.loc" property specifies the following location:

    output/build/bin/native/

If you are on Windows and want to test the APR connector you can put the
tcnative-1.dll file into ${tomcat.source}/bin/native/ and it will be copied
into the above directory when the build runs.


(8.2) Running a single test

It is possible to run a single JUnit test class by adding the "test.entry"
property to the build.properties file. The property specifies the name of
the test class.

For example:

    test.entry=org.apache.catalina.util.TestServerInfo

It is possible to further limit such run to a number of selected test
methods by adding "test.entry.methods" property. The property specifies a
comma-separated list of test case methods.

For example:

    test.entry=org.apache.el.lang.TestELArithmetic
    test.entry.methods=testMultiply01,testMultiply02


(8.3) Running a set of tests

It is possible to run a set of JUnit test classes by adding the "test.name"
property to the build.properties file. The property specifies an Ant
includes pattern for the fileset of test class files to run.

The default value is "**/Test*.java", so all test classes are being
executed (with few exceptions - see build.xml for several exclude patterns).

You can include multiple patterns by concatenating them with a comma (",")
as the separator.

For example:

    test.name=**/TestTomcat.java,**/TestApplicationHttpRequest.java


(8.4) Other configuration options

 1. It is possible to configure the directory where JUnit reports are
 written to. It is configured by "test.reports" property. The default
 value is

        output/build/logs

 2. It is possible to enable generation of access log file when the tests
 are run. This is off by default and can be enabled by the following
 property:

        test.accesslog=true

 The "access_log.<date>" file will be written to the same directory as
 JUnit reports,

        output/build/logs

 3. The testsuite respects logging configuration as configured by
 ${tomcat.source}/conf/logging.properties

 The log files will be written to the temporary directory used by the
 tests,

        output/test-tmp/logs

 4. It is possible to configure formatter used by JUnit reports.
 Configuration properties are "junit.formatter.type",
 "junit.formatter.extension" and "junit.formatter.usefile".

 For example the following property disables generation of separate report
 files:

        junit.formatter.usefile=false