"Fossies" - the Fresh Open Source Software Archive

Member "apache-tomcat-8.5.58/webapps/docs/BUILDING.txt" (10 Sep 2020, 19882 Bytes) of package /windows/www/apache-tomcat-8.5.58-windows-x86.zip:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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
    8 
    9       http://www.apache.org/licenses/LICENSE-2.0
   10 
   11   Unless required by applicable law or agreed to in writing, software
   12   distributed under the License is distributed on an "AS IS" BASIS,
   13   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14   See the License for the specific language governing permissions and
   15   limitations under the License.
   16 ================================================================================
   17 
   18             ====================================================
   19             Building The Apache Tomcat 8.5 Servlet/JSP Container
   20             ====================================================
   21 
   22 This subproject contains the source code for Tomcat 8.5, a container that
   23 implements the Servlet 3.1, JSP 2.3, EL 3.0, WebSocket 1.1 and JASPIC 1.1
   24 specifications from the Java Community Process <https://www.jcp.org/>.
   25 
   26 Note: If you just need to run Apache Tomcat, it is not necessary to build
   27 it. You may simply download a binary distribution. It is cross-platform.
   28 Read RUNNING.txt for the instruction on how to run it.
   29 
   30 In order to build a binary distribution version of Apache Tomcat from a
   31 source distribution, do the following:
   32 
   33 
   34 (1) Download and Install a Java Development Kit
   35 
   36  1. If the JDK is already installed, skip to (2).
   37 
   38  2. Download a version 7 of Java Development Kit (JDK) release (use the
   39     latest update available for your chosen version) from one of:
   40 
   41         http://www.oracle.com/technetwork/java/javase/downloads/index.html
   42         http://openjdk.java.net/install/index.html
   43         or another JDK vendor.
   44 
   45     Note regarding later versions of Java:
   46 
   47       As documented elsewhere, one of components in Apache Tomcat includes
   48       a private copy of the Apache Commons DBCP 2 library.
   49 
   50       The JDBC interfaces implemented by DBCP frequently change in non-backwards
   51       compatible ways between versions of the Java SE specification. Therefore,
   52       it is likely that DBCP 2 will only compile with the specific version of Java
   53       listed above and that compilation will fail if a later version of Java is
   54       used.
   55 
   56       See Apache Commons DBCP 2 project web site for more details on
   57       available versions of the library and its requirements,
   58 
   59         https://commons.apache.org/dbcp/
   60 
   61  3. Install the JDK according to the instructions included with the release.
   62 
   63  4. Set an environment variable JAVA_HOME to the pathname of the directory
   64     into which you installed the JDK release.
   65 
   66 
   67 (2) Install Apache Ant version 1.9.8 or later on your computer.
   68 
   69  1. If Apache Ant version 1.9.8 or later is already installed on your
   70     computer, skip to (3).
   71 
   72  2. Download a binary distribution of Ant from:
   73 
   74         https://ant.apache.org/bindownload.cgi
   75 
   76  3. Unpack the binary distribution into a convenient location so that the
   77     Ant release resides in its own directory (conventionally named
   78     "apache-ant-[version]").
   79 
   80     For the purposes of the remainder of this document, the symbolic name
   81     "${ant.home}" is used to refer to the full pathname of the release
   82     directory.
   83 
   84  4. Create an ANT_HOME environment variable to point the directory
   85     ${ant.home}.
   86 
   87  5. Modify the PATH environment variable to include the directory
   88     ${ant.home}/bin in its list.  This makes the "ant" command line script
   89     available, which will be used to actually perform the build.
   90 
   91 
   92 (3) Building Tomcat 8.5
   93 
   94 (3.1) Checkout or obtain the source code for Tomcat 8.5
   95 
   96 Clone the source using git, then checkout a specific major branch or
   97 master for the latest code development, or download and unpack a source
   98 package.
   99 
  100  *  Tomcat GitHub repository URL:
  101 
  102         https://github.com/apache/tomcat
  103 
  104  *  Source packages can be downloaded from:
  105 
  106         https://tomcat.apache.org/download-80.cgi
  107 
  108 The location where the source has been placed will be further referred as
  109 ${tomcat.source}.
  110 
  111 The Tomcat local build process does not modify line-endings. The svn repository
  112 is configured so that all files will be checked out with the line-ending
  113 appropriate for the current platform. When using a source package you should
  114 ensure that you use the source package that has the appropriate line-ending
  115 for your platform:
  116 
  117   zip    -> CRLF
  118   tar.gz -> LF
  119 
  120 Note that the release build process does modify line-endings to ensure that
  121 each release package has the appropriate line-endings.
  122 
  123 (3.2) Building
  124 
  125  1. The build is controlled by creating a ${tomcat.source}/build.properties
  126     file.
  127 
  128     It is recommended to always create the file, because of unfortunate
  129     default value of base.path property. You may start with the following
  130     content for the file:
  131 
  132         # ----- Default Base Path for Dependent Packages -----
  133         # Replace this path with the directory path where dependencies binaries
  134         # should be downloaded
  135         base.path=/home/me/some-place-to-download-to
  136 
  137  2. Configure base.path property by adding it to the
  138     ${tomcat.source}/build.properties file.
  139 
  140     The base.path property specifies the place where Tomcat dependencies
  141     required by the build are downloaded. It is recommended to place this
  142     directory outside of the source tree, so that you do not waste your
  143     time re-downloading the libraries.
  144 
  145 * NOTE: The default value of the base.path property configures the build script
  146   to download the libraries required to build Tomcat to the
  147   ${user.home}/tomcat-build-libs directory.
  148 
  149 * NOTE: Users accessing the Internet through a proxy must use the properties
  150   file to indicate to Ant the proxy configuration.
  151 
  152   The following properties should be added to the ${tomcat.source}/build.properties
  153   file.
  154 
  155         proxy.use=true
  156         proxy.host=proxy.domain
  157         proxy.port=8080
  158         proxy.user=username
  159         proxy.password=password
  160 
  161   See Apache Ant documentation for the <setproxy> task for details.
  162 
  163  3. Go to the sources directory and run Ant:
  164 
  165         cd ${tomcat.source}
  166         ant
  167 
  168     This will execute the "deploy" target in build.xml.
  169 
  170     Once the build has completed successfully, a usable Tomcat installation
  171     will have been produced in the ${tomcat.source}/output/build directory,
  172     and can be started and stopped with the usual scripts.
  173 
  174     Note that the build includes Tomcat documentation, which can be found
  175     in the output/build/webapps/docs directory.
  176 
  177     The path of the output directory can be controlled by specifying the
  178     "tomcat.output" property in the build.properties file.
  179 
  180 * NOTE: Do not run the build as the root user. Building and running Tomcat
  181   does not require root privileges.
  182 
  183 
  184 (4) Updating sources and rebuilding
  185 
  186 It is recommended that you regularly update the downloaded Tomcat 8.5
  187 sources using your SVN client.
  188 
  189 For a quick rebuild of only modified code you can use:
  190 
  191     cd ${tomcat.source}
  192     ant
  193 
  194 
  195 (5) Special builds
  196 
  197 There are several targets in Tomcat build files that are useful to be
  198 called separately. They build components that you may want to build
  199 quickly, or ones that are included in the full release and are not built
  200 during the default "deploy" build.
  201 
  202 (5.1) Building documentation
  203 
  204 The documentation web application is built during the default "deploy"
  205 build.
  206 
  207 It can be built quickly by using the following commands:
  208 
  209     cd ${tomcat.source}
  210     ant build-docs
  211 
  212 The output of this command will be found in the following directory:
  213 
  214     output/build/webapps/docs
  215 
  216 
  217 The API documentation (Javadoc) is built during a "release" build. It is
  218 easy to build it separately by using the following commands:
  219 
  220     cd ${tomcat.source}
  221     ant javadoc
  222 
  223 The output of this command will be found in the following directories:
  224 
  225     output/dist/webapps/docs/api
  226     output/dist/webapps/docs/elapi
  227     output/dist/webapps/docs/jspapi
  228     output/dist/webapps/docs/servletapi
  229 
  230 
  231 (5.2) Building the extras (commons-logging, webservices etc.)
  232 
  233 These components are documented on the "Additional Components"
  234 (extras.html) page of documentation. They are built during a "release"
  235 build.
  236 
  237 You can build them by using the following commands:
  238 
  239     cd ${tomcat.source}
  240     ant extras
  241 
  242 (5.3) Building the embedded packages
  243 
  244 These are built during a "release" build.
  245 
  246 You can build them by using the following commands:
  247 
  248     cd ${tomcat.source}
  249     ant embed
  250 
  251 
  252 (6) Building a full release (as provided via the ASF download pages)
  253 
  254     A full release includes the Windows installer which requires a Windows
  255     environment to be available to create it. If not building in a Windows
  256     environment, the build scripts assume that Wine is available. If this is not
  257     the case, the skip.installer property may be set to skip the creation of the
  258     Windows installer.
  259 
  260  1. Configure GPG, if needed
  261 
  262     If the released artifacts have to be cryptographically signed with a
  263     PGP signature, like the official ASF releases are, the following
  264     property can be added to the build.properties file:
  265 
  266         # Location of GPG executable (used only for releases)
  267         gpg.exec=/path/to/gpg
  268 
  269     You do not need it if you do not plan to sign the release.
  270 
  271     If "gpg.exec" property does not point to an existing file, it will be
  272     ignored and this feature will be disabled.
  273 
  274     You will be prompted for the GPG passphrase when the release build
  275     starts, unless "gpg.passphrase" property is set.
  276 
  277  2. If building the Windows installer
  278 
  279     If running the build in a UAC enabled environment, building the Windows
  280     installer requires elevated privileges. The simplest way to do this is to
  281     open the command prompt used for the build with the "Run as administrator"
  282     option.
  283 
  284  3. Configure the code signing service
  285 
  286     ASF committers performing official releases will need to configure the code
  287     signing service so that the Windows installer is signed during the build
  288     process. The following properties need to be added to the build.properties
  289     file:
  290 
  291         # Location of GPG executable (used only for releases)
  292         # Code signing of Windows installer
  293         do.codesigning=true
  294         codesigning.user=request-via-pmc
  295         codesigning.pwd=request-via-pmc
  296         codesigning.partnercode=request-via-pmc
  297         codesigning.service=Microsoft Windows Signing
  298 
  299     Release managers will be provided with the necessary credentials by the PMC.
  300     It will also be necessary to enable TLS 1.1 and TLS 1.2 by default (they are
  301     disabled by default on Java 7) for the build process to communicate with the
  302     code signing service. The simplest way is by setting the ANT_OPTS
  303     environment variable. E.g. (for Windows):
  304 
  305     set ANT_OPTS=-Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2
  306 
  307  4. Build the release:
  308 
  309     cd ${tomcat.source}
  310     ant release
  311 
  312 
  313 (7) Tests
  314 
  315 (7.1) Running Tomcat tests
  316 
  317 Tomcat includes a number of junit tests. The tests are not run when a
  318 release is built. There is separate command to run them.
  319 
  320 To run the testsuite use the following command:
  321 
  322     cd ${tomcat.source}
  323     ant test
  324 
  325 It is advisable to redirect output of the above command to a file for later
  326 inspection.
  327 
  328 The JUnit reports generated by the tests will be written to the following
  329 directory:
  330 
  331     output/build/logs
  332 
  333 By default the testsuite is run three times to test 3 different
  334 implementations of Tomcat connectors: NIO, NIO2 and APR. (If you are not
  335 familiar with Tomcat connectors, see config/http.html in documentation for
  336 details).
  337 
  338 The 3 runs are enabled and disabled individually by the following
  339 properties, which all are "true" by default:
  340 
  341     execute.test.nio=true
  342     execute.test.nio2=true
  343     execute.test.apr=true
  344 
  345 The APR connector can be tested only if Tomcat-Native library binaries are
  346 found by the testsuite. The "test.apr.loc" property specifies the directory
  347 where the library binaries are located.
  348 
  349 By default the "test.apr.loc" property specifies the following location:
  350 
  351     output/build/bin/native/
  352 
  353 If you are on Windows and want to test the APR connector you can put the
  354 tcnative-1.dll file into ${tomcat.source}/bin/native/ and it will be copied
  355 into the above directory when the build runs.
  356 
  357 The unit tests include tests of the clustering functionality which require
  358 multicast to be enabled. There is a simple application provided in the Tomcat
  359 test source (org.apache.catalina.tribes.TesterMulticast) that can be used to
  360 check if a machine supports multicast. Notes on enabling multicast for different
  361 operating systems are provided in the Javadoc for that class.
  362 
  363 
  364 (7.2) Running a single test
  365 
  366 It is possible to run a single JUnit test class by adding the "test.entry"
  367 property to the build.properties file. The property specifies the name of
  368 the test class.
  369 
  370 For example:
  371 
  372     test.entry=org.apache.catalina.util.TestServerInfo
  373 
  374 It is possible to further limit such run to a number of selected test
  375 methods by adding "test.entry.methods" property. The property specifies a
  376 comma-separated list of test case methods.
  377 
  378 For example:
  379 
  380     test.entry=org.apache.el.lang.TestELArithmetic
  381     test.entry.methods=testMultiply01,testMultiply02
  382 
  383 
  384 (7.3) Running a set of tests
  385 
  386 It is possible to run a set of JUnit test classes by adding the "test.name"
  387 property to the build.properties file. The property specifies an Ant
  388 includes pattern for the fileset of test class files to run.
  389 
  390 The default value is "**/Test*.java", so all test classes are being
  391 executed (with few exceptions - see build.xml for several exclude patterns).
  392 
  393 You can include multiple patterns by concatenating them with a comma (",")
  394 as the separator.
  395 
  396 For example:
  397 
  398     test.name=**/TestSsl.java,**/TestWebSocketFrameClientSSL.java
  399 
  400 You can exclude specific JUnit test classes by adding the "test.exclude"
  401 property to the build.properties file. The property specifies an Ant
  402 excludes pattern for the fileset of test class files to exclude form the run.
  403 The default value is empty, so no classes are excluded. The syntax is the same
  404 as for the property "test.name".
  405 
  406 
  407 (7.4) Other configuration options
  408 
  409  1. It is possible to configure the directory where JUnit reports are
  410  written to. It is configured by "test.reports" property. The default
  411  value is
  412 
  413         output/build/logs
  414 
  415  2. It is possible to enable generation of access log file when the tests
  416  are run. This is off by default and can be enabled by the following
  417  property:
  418 
  419         test.accesslog=true
  420 
  421  The "access_log.<date>" file will be written to the same directory as
  422  JUnit reports,
  423 
  424         output/build/logs
  425 
  426  3. The testsuite respects logging configuration as configured by
  427  ${tomcat.source}/conf/logging.properties
  428 
  429  The log files will be written to the temporary directory used by the
  430  tests,
  431 
  432         output/test-tmp/logs
  433 
  434  4. It is possible to configure formatter used by JUnit reports.
  435  Configuration properties are "junit.formatter.type",
  436  "junit.formatter.extension" and "junit.formatter.usefile".
  437 
  438  For example the following property disables generation of separate report
  439  files:
  440 
  441         junit.formatter.usefile=false
  442 
  443  5. It is possible to speed up testing by letting JUnit to run several
  444  tests in parallel.
  445 
  446  This is configured by setting "test.threads" property. The recommended
  447  value is one thread per core.
  448 
  449  6. Optional support is provided for the Cobertura code coverage tool.
  450 
  451 NOTE: Cobertura is licensed under GPL v2 with parts of it being under
  452       Apache License v1.1. See https://cobertura.github.io/cobertura/ for details.
  453       Using it during Tomcat build is optional and is off by default.
  454 
  455  Cobertura can be enabled using the following properties:
  456 
  457         test.cobertura=true
  458         test.threads=1
  459 
  460  Using Cobertura currently requires setting test.threads configuration
  461  property to the value of 1. Setting that property to a different value
  462  will disable code coverage.
  463 
  464  The report files by default are written to
  465 
  466         output/coverage
  467 
  468  7. The performance tests are written to run reasonably powerful machines (such
  469     as a developer may use day to day) assuming no other resource hungry
  470     processes are running.
  471 
  472     These assumptions are not always true (e.g. on CI systems running in a
  473     virtual machine) so the performance tests may be disabled by using the
  474     following property:
  475 
  476         test.excludePerformance=true
  477 
  478  8. Some tests include checks that the access log valve entries are as expected.
  479     These checks include timings. On slower / loaded systems these checks will
  480     often fail. The checks may be relaxed by using the following property:
  481 
  482         test.relaxTiming=true
  483 
  484  9. It is known that some platforms (e.g. OSX El Capitan) require IPv4 to
  485     be the default for the multicast tests to work. This is configured by
  486     the following property:
  487 
  488         java.net.preferIPv4Stack=true
  489 
  490  10. It is possible to control whether the output of the tests is displayed
  491      on the console or not. By default it is displayed and can be disabled
  492      by the following property:
  493 
  494         test.verbose=true
  495 
  496 (8) Source code checks
  497 
  498 (8.1) Checkstyle
  499 
  500 NOTE: Checkstyle is licensed under LGPL. Using Checkstyle during Tomcat
  501       build is optional and is off by default.
  502 
  503       See http://checkstyle.sourceforge.net/ for more information.
  504 
  505 Tomcat comes with a Checkstyle configuration that tests its source code
  506 for certain conventions, like presence of the license header.
  507 
  508 To enable Checkstyle, add the following property to build.properties file:
  509 
  510     execute.validate=true
  511 
  512 Once Checkstyle is enabled, the check will be performed automatically
  513 during the build. The check is run before compilation of the source code.
  514 
  515 To speed-up repeated runs of this check, a cache is configured. The cache
  516 is located in the following directory:
  517 
  518     output/res/checkstyle
  519 
  520 It is possible to run the check separately by calling the "validate"
  521 target. The command is:
  522 
  523     cd ${tomcat.source}
  524     ant -Dexecute.validate=true validate
  525 
  526 
  527 (8.2) FindBugs
  528 
  529 NOTE: FindBugs is licensed under LGPL. Using Findbugs during Tomcat build is
  530       optional and is off by default.
  531 
  532       See https://spotbugs.github.io/ for more information.
  533 
  534 To enable FindBugs, add the following property to build.properties file:
  535 
  536     execute.findbugs=true
  537 
  538 To compile Tomcat classes and generate a FindBugs report, call the
  539 "findbugs" target. For example:
  540 
  541     cd ${tomcat.source}
  542     ant -Dexecute.findbugs=true findbugs
  543 
  544 The report file by default is written to
  545 
  546     output/findbugs
  547 
  548 
  549 (8.3) End-of-line conventions check
  550 
  551 You usually would not need to run this check. You can skip this section.
  552 
  553 Apache Tomcat project has convention that all of its textual source files,
  554 stored in the Git repository, use Unix style LF line endings.
  555 
  556 This test is used by developers to check that the source code adheres to
  557 this convention. It verifies that the ends of lines in textual files are
  558 appropriate. The idea is to run this check regularly and notify developers
  559 when an inconsistency is detected.
  560 
  561 The command to run this test is:
  562 
  563     cd ${tomcat.source}
  564     ant validate-eoln