================================================================================ 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 1545079 2013-11-24 21:26:17Z kkolinko $

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

This subproject contains the source code for Tomcat 7.0, a container thatimplements the Servlet 3.0 and JSP 2.2 specifications from the JavaCommunity Process <http://www.jcp.org/>.

Note: If you just need to run Apache Tomcat, it is not necessary to buildit. 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 asource distribution, do the following:

(1) Download and Install a Java 6 and Java 7 Development Kit

1. If the JDKs are already installed, skip to (2).

2. Download a version 6 of the Java Development Kit (JDK) release (use the latest update available for your chosen version) from

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

Note regarding later versions of Java:

As documented elsewhere, one of the 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. Therefore, the build Tomcat build process must be executed with a Java 6 JDK.

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

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

If you really want to use a later version of JDK to build Tomcat, several workarounds are possible. One of them is to skip building the component (tomcat-dbcp.jar).

3. Install the Java 6 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.

5. Download a version 7 of the Java Development Kit (JDK) release (use the latest update available for your chosen version) from

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

6. Install the Java 7 JDK according to the instructions included with the release.

* NOTE: The Java 7 JDK is only required if you wish to build Tomcat with JSR-356 (Java WebSocket 1.0) support.

(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 7.0

(3.1) Checkout or obtain the source code for Tomcat 7.0

Checkout the source using SVN, selecting a tag for released version ortrunk for the current development code, or download and unpack a sourcepackage.

* Tomcat SVN repository URL:

http://svn.apache.org/repos/asf/tomcat/tc7.0.x/trunk/

* Source packages can be downloaded from:

http://tomcat.apache.org/download-70.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.

* NOTE: Users wishing to build Tomcat with JSR-356 (Java WebSocket 1.0) support must also set the java.7.home build property to the location of the Java 7 JDK installation.

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 7.0sources using your SVN client.

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

cd ${tomcat.source} ant

(5) Special builds

There are several targets in Tomcat build files that are useful to becalled separately. They build components that you may want to buildquickly, or ones that are included in the full release and are not builtduring the default "deploy" build.

(5.1) Building documentation

The documentation web application is built during the default "deploy"build.

It can be built quickly by using the following commands:

cd ${tomcat.source} ant build-docs

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

output/build/webapps/docs

The API documentation (Javadoc) is built during a "release" build. It iseasy to build it separately by using the following commands:

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

These components are documented on the "Additional Components"(extras.html) page of documentation. They are built during a "release"build.

You can build them by using the following commands:

cd ${tomcat.source} ant extras

(5.3) Building the embedded packages

These are built during a "release" build.

You can build them by using the following commands:

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) Tests

(7.1) Running Tomcat tests

Tomcat includes a number of junit tests. The tests are not run when arelease is built. There is separate command to run them.

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

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

output/build/logs

By default the testsuite is run three times to test 3 differentimplementations of Tomcat connectors: BIO, NIO and APR. (If you are notfamiliar with Tomcat connectors, see config/http.html in documentation fordetails).

The 3 runs are enabled and disabled individually by the followingproperties, 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 arefound by the testsuite. The "test.apr.loc" property specifies the directorywhere 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 thetcnative-1.dll file into ${tomcat.source}/bin/native/ and it will be copiedinto the above directory when the build runs.

(7.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 ofthe test class.

For example:

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

(7.3) Other configuration 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

4. Optional support is provided for the Cobertura code coverage tool. It can be enabled using the following property:

test.cobertura=true

* NOTE: Cobertura is licensed under GPL v2 with parts of it being under Apache License v1.1. See http://cobertura.sf.net for details. Using it during Tomcat build is optional and is off by default.

(8) Source code checks

(8.1) Checkstyle

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

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

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

execute.validate=true

Once Checkstyle is enabled, the check will be performed automaticallyduring the build. The check is run before compilation of the source code.

To speed-up repeated runs of this check, a cache is configured. The cacheis located in the following directory:

output/res/checkstyle

It is possible to run the check separately by invoking the "validate"target. The command is:

cd ${tomcat.source} ant -Dexecute.validate=true validate

(8.2) End-of-line conventions check

You usually would not need to run this check. You can skip this section.

Apache Tomcat project has convention that all of its textual source files,stored in Subversion repository, are marked with Subversion property"svn:eol-style" with value of "native". This convention makes the editingof source code on different platforms easier.

This test is used by developers to check that the source code adheres tothis convention. It verifies that the ends of lines in textual files areappropriate for the operating system where it is run. The idea is to runthis check regularly on two different platforms and notify developers whenan inconsistency is detected.

The command to run this test is:

cd ${tomcat.source} ant validate-eoln