crapapi-tomcat

================================================================================ 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 8.5 Servlet/JSP Container ==================================================== This subproject contains the source code for Tomcat 8.5, a container that implements the Servlet 3.1, JSP 2.3, EL 3.0, WebSocket 1.1 and JASPIC 1.1 specifications from the Java Community Process <https://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 version 7 of Java Development Kit (JDK) release (use the latest update available for your chosen version) from one of: http://www.oracle.com/technetwork/java/javase/downloads/index.html http://openjdk.java.net/install/index.html or another JDK vendor. Note regarding later versions of Java: As documented elsewhere, one of components in Apache Tomcat includes a private copy of the Apache Commons DBCP 2 library. The JDBC interfaces implemented by DBCP frequently change in non-backwards compatible ways between versions of the Java SE specification. Therefore, it is likely that DBCP 2 will only compile with the specific version of Java listed above and that compilation will fail if a later version of Java is used. See Apache Commons DBCP 2 project web site for more details on available versions of the library and its requirements, https://commons.apache.org/dbcp/ 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 version 1.9.8 or later on your computer. 1. If Apache Ant version 1.9.8 or later is already installed on your computer, skip to (3). 2. Download a binary distribution of Ant from: https://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 8.5 (3.1) Checkout or obtain the source code for Tomcat 8.5 Clone the source using git, then checkout a specific major branch or master for the latest code development, or download and unpack a source package. * Tomcat GitHub repository URL: https://github.com/apache/tomcat * Source packages can be downloaded from: https://tomcat.apache.org/download-80.cgi The location where the source has been placed will be further referred as ${tomcat.source}. The Tomcat local build process does not modify line-endings. The svn repository is configured so that all files will be checked out with the line-ending appropriate for the current platform. When using a source package you should ensure that you use the source package that has the appropriate line-ending for your platform: zip -> CRLF tar.gz -> LF Note that the release build process does modify line-endings to ensure that each release package has the appropriate line-endings. (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. * NOTE: The default value of the base.path property configures the build script to 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 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=true 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 8.5 sources 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 be called separately. They build components that you may want to build quickly, or ones that are included in the full release and are not built during 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 is easy to build it separately by using the following commands: cd ${tomcat.so