You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

559 lines
19 KiB

  1. ================================================================================
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. ================================================================================
  15. ====================================================
  16. Building The Apache Tomcat @VERSION_MAJOR_MINOR@ Servlet/JSP Container
  17. ====================================================
  18. This subproject contains the source code for Tomcat @VERSION_MAJOR_MINOR@, a container that
  19. implements the Servlet 4.0, JSP 2.3, EL 3.0, WebSocket 1.1 and JASPIC 1.1
  20. specifications from the Java Community Process <>.
  21. Note: If you just need to run Apache Tomcat, it is not necessary to build
  22. it. You may simply download a binary distribution. It is cross-platform.
  23. Read RUNNING.txt for the instruction on how to run it.
  24. In order to build a binary distribution version of Apache Tomcat from a
  25. source distribution, do the following:
  26. (1) Download and Install a Java Development Kit
  27. 1. If the JDK is already installed, skip to (2).
  28. 2. Download a version 8 of Java Development Kit (JDK) release (use the
  29. latest update available for your chosen version) from one of:
  32. or another JDK vendor.
  33. Note regarding later versions of Java:
  34. As documented elsewhere, one of components in Apache Tomcat includes
  35. a private copy of the Apache Commons DBCP 2 library.
  36. The JDBC interfaces implemented by DBCP frequently change in non-backwards
  37. compatible ways between versions of the Java SE specification. Therefore,
  38. it is likely that DBCP 2 will only compile with the specific version of Java
  39. listed above and that compilation will fail if a later version of Java is
  40. used.
  41. See Apache Commons DBCP 2 project web site for more details on
  42. available versions of the library and its requirements,
  44. 3. Install the JDK according to the instructions included with the release.
  45. 4. Set an environment variable JAVA_HOME to the pathname of the directory
  46. into which you installed the JDK release.
  47. (2) Install Apache Ant version 1.9.10 or later on your computer.
  48. 1. If Apache Ant version 1.9.10 or later is already installed on your
  49. computer, skip to (3).
  50. 2. Download a binary distribution of Ant from:
  52. 3. Unpack the binary distribution into a convenient location so that the
  53. Ant release resides in its own directory (conventionally named
  54. "apache-ant-[version]").
  55. For the purposes of the remainder of this document, the symbolic name
  56. "${ant.home}" is used to refer to the full pathname of the release
  57. directory.
  58. 4. Create an ANT_HOME environment variable to point the directory
  59. ${ant.home}.
  60. 5. Modify the PATH environment variable to include the directory
  61. ${ant.home}/bin in its list. This makes the "ant" command line script
  62. available, which will be used to actually perform the build.
  63. (3) Building Tomcat @VERSION_MAJOR_MINOR@
  64. (3.1) Checkout or obtain the source code for Tomcat @VERSION_MAJOR_MINOR@
  65. Clone the source using git, then checkout a specific major branch or
  66. master for the latest code development, or download and unpack a source
  67. package.
  68. * Tomcat GitHub repository URL:
  70. * Source packages can be downloaded from:
  72. The location where the source has been placed will be further referred as
  73. ${tomcat.source}.
  74. The Tomcat local build process does not modify line-endings. The svn repository
  75. is configured so that all files will be checked out with the line-ending
  76. appropriate for the current platform. When using a source package you should
  77. ensure that you use the source package that has the appropriate line-ending
  78. for your platform:
  79. zip -> CRLF
  80. tar.gz -> LF
  81. Note that the release build process does modify line-endings to ensure that
  82. each release package has the appropriate line-endings.
  83. (3.2) Building
  84. 1. The build is controlled by creating a ${tomcat.source}/
  85. file.
  86. It is recommended to always create the file, because of unfortunate
  87. default value of base.path property. You may start with the following
  88. content for the file:
  89. # ----- Default Base Path for Dependent Packages -----
  90. # Replace this path with the directory path where dependencies binaries
  91. # should be downloaded
  92. base.path=/home/me/some-place-to-download-to
  93. 2. Configure base.path property by adding it to the
  94. ${tomcat.source}/ file.
  95. The base.path property specifies the place where Tomcat dependencies
  96. required by the build are downloaded. It is recommended to place this
  97. directory outside of the source tree, so that you do not waste your
  98. time re-downloading the libraries.
  99. * NOTE: The default value of the base.path property configures the build script
  100. to download the libraries required to build Tomcat to the
  101. ${user.home}/tomcat-build-libs directory.
  102. * NOTE: Users accessing the Internet through a proxy must use the properties
  103. file to indicate to Ant the proxy configuration.
  104. The following properties should be added to the ${tomcat.source}/
  105. file.
  106. proxy.use=true
  108. proxy.port=8080
  109. proxy.user=username
  110. proxy.password=password
  111. See Apache Ant documentation for the <setproxy> task for details.
  112. 3. Go to the sources directory and run Ant:
  113. cd ${tomcat.source}
  114. ant
  115. This will execute the "deploy" target in build.xml.
  116. Once the build has completed successfully, a usable Tomcat installation
  117. will have been produced in the ${tomcat.source}/output/build directory,
  118. and can be started and stopped with the usual scripts.
  119. Note that the build includes Tomcat documentation, which can be found
  120. in the output/build/webapps/docs directory.
  121. The path of the output directory can be controlled by specifying the
  122. "tomcat.output" property in the file.
  123. * NOTE: Do not run the build as the root user. Building and running Tomcat
  124. does not require root privileges.
  125. (4) Updating sources and rebuilding
  126. It is recommended that you regularly update the downloaded Tomcat @VERSION_MAJOR_MINOR@
  127. sources using your git client.
  128. For a quick rebuild of only modified code you can use:
  129. cd ${tomcat.source}
  130. ant
  131. (5) Special builds
  132. There are several targets in Tomcat build files that are useful to be
  133. called separately. They build components that you may want to build
  134. quickly, or ones that are included in the full release and are not built
  135. during the default "deploy" build.
  136. (5.1) Building documentation
  137. The documentation web application is built during the default "deploy"
  138. build.
  139. It can be built quickly by using the following commands:
  140. cd ${tomcat.source}
  141. ant build-docs
  142. The output of this command will be found in the following directory:
  143. output/build/webapps/docs
  144. The API documentation (Javadoc) is built during a "release" build. It is
  145. easy to build it separately by using the following commands:
  146. cd ${tomcat.source}
  147. ant javadoc
  148. The output of this command will be found in the following directories:
  149. output/dist/webapps/docs/api
  150. output/dist/webapps/docs/elapi
  151. output/dist/webapps/docs/jspapi
  152. output/dist/webapps/docs/servletapi
  153. (5.2) Building the extras (commons-logging, webservices etc.)
  154. These components are documented on the "Additional Components"
  155. (extras.html) page of documentation. They are built during a "release"
  156. build.
  157. You can build them by using the following commands:
  158. cd ${tomcat.source}
  159. ant extras
  160. (5.3) Building the embedded packages
  161. These are built during a "release" build.
  162. You can build them by using the following commands:
  163. cd ${tomcat.source}
  164. ant embed
  165. (6) Building a full release (as provided via the ASF download pages)
  166. A full release includes the Windows installer which requires a Windows
  167. environment to be available to create it. If not building in a Windows
  168. environment, the build scripts assume that Wine is available. If this is not
  169. the case, the skip.installer property may be set to skip the creation of the
  170. Windows installer.
  171. Provided that Wine is available on non-Windows platforms, a full release
  172. build may be made on Windows, Linux or MacOS.
  173. 1. Configure GPG, if needed
  174. If the released artifacts have to be cryptographically signed with a
  175. PGP signature, like the official ASF releases are, the following
  176. property can be added to the file:
  177. # Location of GPG executable (used only for releases)
  178. gpg.exec=/path/to/gpg
  179. You do not need it if you do not plan to sign the release.
  180. If "gpg.exec" property does not point to an existing file, it will be
  181. ignored and this feature will be disabled.
  182. You will be prompted for the GPG passphrase when the release build
  183. starts, unless "gpg.passphrase" property is set.
  184. 2. If building the Windows installer
  185. If running the build in a UAC enabled environment, building the Windows
  186. installer requires elevated privileges. The simplest way to do this is to
  187. open the command prompt used for the build with the "Run as administrator"
  188. option.
  189. 3. Configure the code signing service
  190. ASF committers performing official releases will need to configure the code
  191. signing service so that the Windows installer is signed during the build
  192. process. The following properties need to be added to the
  193. file:
  194. # Location of GPG executable (used only for releases)
  195. gpg.exec=/path/to/gpg
  196. # Code signing of Windows installer
  197. do.codesigning=true
  198. codesigning.storepass=request-via-pmc
  199. Release managers will be provided with the necessary credentials by the PMC.
  200. 4. Build the release:
  201. cd ${tomcat.source}
  202. ant release
  203. (7) Tests
  204. (7.1) Running Tomcat tests
  205. Tomcat includes a number of junit tests. The tests are not run when a
  206. release is built. There is separate command to run them.
  207. To run the testsuite use the following command:
  208. cd ${tomcat.source}
  209. ant test
  210. It is advisable to redirect output of the above command to a file for later
  211. inspection.
  212. The JUnit reports generated by the tests will be written to the following
  213. directory:
  214. output/build/logs
  215. By default the testsuite is run three times to test 3 different
  216. implementations of Tomcat connectors: NIO, NIO2 and APR. (If you are not
  217. familiar with Tomcat connectors, see config/http.html in documentation for
  218. details).
  219. The 3 runs are enabled and disabled individually by the following
  220. properties, which all are "true" by default:
  221. execute.test.nio=true
  222. execute.test.nio2=true
  223. execute.test.apr=true
  224. The APR connector can be tested only if Tomcat-Native library binaries are
  225. found by the testsuite. The "test.apr.loc" property specifies the directory
  226. where the library binaries are located.
  227. By default the "test.apr.loc" property specifies the following location:
  228. output/build/bin/native/
  229. If you are on Windows and want to test the APR connector you can put the
  230. tcnative-1.dll file into ${tomcat.source}/bin/native/ and it will be copied
  231. into the above directory when the build runs.
  232. The unit tests include tests of the clustering functionality which require
  233. multicast to be enabled. There is a simple application provided in the Tomcat
  234. test source (org.apache.catalina.tribes.TesterMulticast) that can be used to
  235. check if a machine supports multicast. Notes on enabling multicast for different
  236. operating systems are provided in the Javadoc for that class.
  237. (7.2) Running a single test
  238. It is possible to run a single JUnit test class by adding the "test.entry"
  239. property to the file. The property specifies the name of
  240. the test class.
  241. For example:
  242. test.entry=org.apache.catalina.util.TestServerInfo
  243. It is possible to further limit such run to a number of selected test
  244. methods by adding "test.entry.methods" property. The property specifies a
  245. comma-separated list of test case methods.
  246. For example:
  247. test.entry=org.apache.el.lang.TestELArithmetic
  248. test.entry.methods=testMultiply01,testMultiply02
  249. (7.3) Running a set of tests
  250. It is possible to run a set of JUnit test classes by adding the ""
  251. property to the file. The property specifies an Ant
  252. includes pattern for the fileset of test class files to run.
  253. The default value is "**/Test*.java", so all test classes are being
  254. executed (with few exceptions - see build.xml for several exclude patterns).
  255. You can include multiple patterns by concatenating them with a comma (",")
  256. as the separator.
  257. For example:
  259. You can exclude specific JUnit test classes by adding the "test.exclude"
  260. property to the file. The property specifies an Ant
  261. excludes pattern for the fileset of test class files to exclude form the run.
  262. The default value is empty, so no classes are excluded. The syntax is the same
  263. as for the property "".
  264. (7.4) Other configuration options
  265. 1. It is possible to configure the directory where JUnit reports are
  266. written to. It is configured by "test.reports" property. The default
  267. value is
  268. output/build/logs
  269. 2. It is possible to enable generation of access log file when the tests
  270. are run. This is off by default and can be enabled by the following
  271. property:
  272. test.accesslog=true
  273. The "access_log.<date>" file will be written to the same directory as
  274. JUnit reports,
  275. output/build/logs
  276. 3. The testsuite respects logging configuration as configured by
  277. ${tomcat.source}/conf/
  278. The log files will be written to the temporary directory used by the
  279. tests,
  280. output/test-tmp/logs
  281. 4. It is possible to configure formatter used by JUnit reports.
  282. Configuration properties are "junit.formatter.type",
  283. "junit.formatter.extension" and "junit.formatter.usefile".
  284. For example the following property disables generation of separate report
  285. files:
  286. junit.formatter.usefile=false
  287. 5. It is possible to speed up testing by letting JUnit to run several
  288. tests in parallel.
  289. This is configured by setting "test.threads" property. The recommended
  290. value is one thread per core.
  291. 6. Optional support is provided for the Cobertura code coverage tool.
  292. NOTE: Cobertura is licensed under GPL v2 with parts of it being under
  293. Apache License v1.1. See for details.
  294. Using it during Tomcat build is optional and is off by default.
  295. Cobertura can be enabled using the following properties:
  296. test.cobertura=true
  297. test.threads=1
  298. Using Cobertura currently requires setting test.threads configuration
  299. property to the value of 1. Setting that property to a different value
  300. will disable code coverage.
  301. The report files by default are written to
  302. output/coverage
  303. 7. The performance tests are written to run reasonably powerful machines (such
  304. as a developer may use day to day) assuming no other resource hungry
  305. processes are running.
  306. These assumptions are not always true (e.g. on CI systems running in a
  307. virtual machine) so the performance tests may be disabled by using the
  308. following property:
  309. test.excludePerformance=true
  310. 8. Some tests include checks that the access log valve entries are as expected.
  311. These checks include timings. On slower / loaded systems these checks will
  312. often fail. The checks may be relaxed by using the following property:
  313. test.relaxTiming=true
  314. 9. It is known that some platforms (e.g. OSX El Capitan) require IPv4 to
  315. be the default for the multicast tests to work. This is configured by
  316. the following property:
  318. 10. By default the output of unit tests is sent to the console and can be
  319. quite verbose. The output can be disabled by setting the property:
  320. test.verbose=false
  321. (8) Source code checks
  322. (8.1) Checkstyle
  323. NOTE: Checkstyle is licensed under LGPL. Using Checkstyle during Tomcat
  324. build is optional and is off by default.
  325. See for more information.
  326. Tomcat comes with a Checkstyle configuration that tests its source code
  327. for certain conventions, like presence of the license header.
  328. To enable Checkstyle, add the following property to file:
  329. execute.validate=true
  330. Once Checkstyle is enabled, the check will be performed automatically
  331. during the build. The check is run before compilation of the source code.
  332. To speed-up repeated runs of this check, a cache is configured. The cache
  333. is located in the following directory:
  334. output/res/checkstyle
  335. It is possible to run the check separately by calling the "validate"
  336. target. The command is:
  337. cd ${tomcat.source}
  338. ant -Dexecute.validate=true validate
  339. (8.2) FindBugs
  340. NOTE: FindBugs is licensed under LGPL. Using Findbugs during Tomcat build is
  341. optional and is off by default.
  342. See for more information.
  343. To enable FindBugs, add the following property to file:
  344. execute.findbugs=true
  345. To compile Tomcat classes and generate a FindBugs report, call the
  346. "findbugs" target. For example:
  347. cd ${tomcat.source}
  348. ant -Dexecute.findbugs=true findbugs
  349. The report file by default is written to
  350. output/findbugs
  351. (8.3) End-of-line conventions check
  352. You usually would not need to run this check. You can skip this section.
  353. Apache Tomcat project has convention that all of its textual source files,
  354. stored in the Git repository, use Unix style LF line endings.
  355. This test is used by developers to check that the source code adheres to
  356. this convention. It verifies that the ends of lines in textual files are
  357. appropriate. The idea is to run this check regularly and notify developers
  358. when an inconsistency is detected.
  359. The command to run this test is:
  360. cd ${tomcat.source}
  361. ant validate-eoln