~ubuntu-branches/ubuntu/precise/tomcat7/precise

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

$Id: BUILDING.txt 1232451 2012-01-17 16:00:07Z kkolinko $

            ====================================================
            Building The Apache Tomcat @VERSION_MAJOR_MINOR@ Servlet/JSP Container
            ====================================================

This subproject contains the source code for Tomcat @VERSION_MAJOR_MINOR@, a container that
implements the Servlet 3.0 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:


(1) Download and Install a Java Development Kit

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

 2. Download a Java Development Kit (JDK) release (version 1.6.x or later)
    from:

        http://www.oracle.com/technetwork/java/javase/downloads/index.html

 3. Install the JDK according to the instructions included with the release.

 4. Set an environment variable JAVA_HOME to the pathname of the directory
    into which you installed the JDK release.


(2) Install Apache Ant 1.8.x on your computer

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

 2. Download a binary distribution of Ant 1.8.x from:

        http://ant.apache.org/bindownload.cgi

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

 4. Create an ANT_HOME environment variable to point the directory
    ${ant.home}.

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


(3) Building Tomcat @VERSION_MAJOR_MINOR@

(3.1) Checkout or obtain the source code for Tomcat @VERSION_MAJOR_MINOR@

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.

 *  Tomcat SVN repository URL:

        http://svn.apache.org/repos/asf/tomcat/tc@VERSION_MAJOR_MINOR@.x/trunk/

 *  Source packages can be downloaded from:

        http://tomcat.apache.org/download-@VERSION_MAJOR@0.cgi

The location where the source has been placed will be further referred as
${tomcat.source}.

(3.2) Building

 1. The build is controlled by creating a ${tomcat.source}/build.properties
    file.

    It is recommended to always create the file, because of unfortunate
    default value of base.path property. You may start with the following
    content for the file:

        # ----- 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

 2. Configure base.path property by adding it to the
    ${tomcat.source}/build.properties file.

    The base.path property specifies the place where Tomcat dependencies
    required by the build are downloaded. It is recommended to place this
    directory outside of the source tree, so that you do not waste your
    time re-downloading the libraries.

* WARNING: The default value of base.path property makes the build script
  to 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. Even if you do have access to
  that directory, it is likely not appropriate for you to write there.

  On Windows this usually corresponds to the "C:\usr\share\java"
  directory, unless Cygwin is used.

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

  The following properties should be added to the ${tomcat.source}/build.properties
  file.

        proxy.use=on
        proxy.host=proxy.domain
        proxy.port=8080
        proxy.user=username
        proxy.password=password

  See Apache Ant documentation for the <setproxy> task for details.

 3. Go to the sources directory and run Ant:

        cd ${tomcat.source}
        ant

    This will execute the "deploy" target in build.xml.

    Once the build has completed successfully, a usable Tomcat installation
    will have been produced in the ${tomcat.source}/output/build directory,
    and can be started and stopped with the usual scripts.

    Note that the build includes Tomcat documentation, which can be found
    in the output/build/webapps/docs directory.

    The path of the output directory can be controlled by specifying the
    "tomcat.output" property in the build.properties file.

* NOTE: Do not run the build as the root user. Building and running Tomcat
  does not require root privileges.


(4) Updating sources and rebuilding

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

For a quick rebuild of only modified code you can use:

    cd ${tomcat.source}
    ant


(5) Special builds

Some Tomcat components, that are included in the full release, but are not
built during the default "deploy" build, can also be built separately.

(5.1) Building API documentation (Javadoc)

The API documentation can be easily built:

    cd ${tomcat.source}
    ant javadoc

The output of this command will be found in the following directories:

    output/dist/webapps/docs/api
    output/dist/webapps/docs/elapi
    output/dist/webapps/docs/jspapi
    output/dist/webapps/docs/servletapi

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

    cd ${tomcat.source}
    ant extras

(5.3) Building the embedded packages

    cd ${tomcat.source}
    ant embed


(6) Building a full release (as provided via the ASF download pages)

 1. Configure GPG, if needed

    If the released artifacts have to be cryptographically signed with a
    PGP signature, like the official ASF releases are, the following
    property can be added to the build.properties file:

        # Location of GPG executable (used only for releases)
        gpg.exec=/path/to/gpg

    You do not need it if you do not plan to sign the release.

    If "gpg.exec" property does not point to an existing file, it will be
    ignored and this feature will be disabled.

    You will be prompted for the GPG passphrase when the release build
    starts, unless "gpg.passphrase" property is set.

 2. Build the release:

    cd ${tomcat.source}
    ant release


(7) Enabling Checkstyle

Tomcat comes with a Checkstyle configuration that tests its source code
for certain conventions, like presence of the license header.

To enable Checkstyle checks during Tomcat build, add the following property
to build.properties file:

    execute.validate=true

* NOTE: Checkstyle is licensed under LGPL. Using Checkstyle during Tomcat
  build is optional and is off by default.


(8) Running the tests

The tests are not run when a release is built. There is separate command
for running the tests.

To run the testsuite use the following command:

    cd ${tomcat.source}
    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


(8.1) Testing with APR connector

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 class

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


(8.3) Other options

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

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

 3. It is possible to configure formatter used by JUnit reports. For
 example the following property disables generation of separate report
 files:

        junit.formatter.usefile=false