BUILDING.txt 18.6 KB
Newer Older
Miguel Landaeta's avatar
Miguel Landaeta committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
================================================================================
  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 @VERSION_MAJOR_MINOR@ Servlet/JSP Container
            ====================================================

This subproject contains the source code for Tomcat @VERSION_MAJOR_MINOR@, a container that
23
implements the Servlet 4.0, 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 27 28 29 30 31

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:
Miguel Landaeta's avatar
Miguel Landaeta committed
32 33


34
(1) Download and Install a Java Development Kit
Miguel Landaeta's avatar
Miguel Landaeta committed
35

36
 1. If the JDK is already installed, skip to (2).
Miguel Landaeta's avatar
Miguel Landaeta committed
37

38
 2. Download a version 8 of Java Development Kit (JDK) release (use the
39
    latest update available for your chosen version) from one of:
Miguel Landaeta's avatar
Miguel Landaeta committed
40

41
        http://www.oracle.com/technetwork/java/javase/downloads/index.html
42 43
        http://openjdk.java.net/install/index.html
        or another JDK vendor.
44 45 46 47

    Note regarding later versions of Java:

      As documented elsewhere, one of components in Apache Tomcat includes
48
      a private copy of the Apache Commons DBCP 2 library.
49

50 51
      The JDBC interfaces implemented by DBCP frequently change in non-backwards
      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 54
      listed above and that compilation will fail if a later version of Java is
      used.
55

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

59
        https://commons.apache.org/dbcp/
60

61
 3. Install the JDK according to the instructions included with the release.
Miguel Landaeta's avatar
Miguel Landaeta committed
62

63 64
 4. Set an environment variable JAVA_HOME to the pathname of the directory
    into which you installed the JDK release.
Miguel Landaeta's avatar
Miguel Landaeta committed
65 66


67
(2) Install Apache Ant version 1.9.8 or later on your computer.
Miguel Landaeta's avatar
Miguel Landaeta committed
68

69
 1. If Apache Ant version 1.9.8 or later is already installed on your
70
    computer, skip to (3).
Miguel Landaeta's avatar
Miguel Landaeta committed
71

72
 2. Download a binary distribution of Ant from:
Miguel Landaeta's avatar
Miguel Landaeta committed
73

74
        https://ant.apache.org/bindownload.cgi
Miguel Landaeta's avatar
Miguel Landaeta committed
75

76 77 78
 3. Unpack the binary distribution into a convenient location so that the
    Ant release resides in its own directory (conventionally named
    "apache-ant-[version]").
Miguel Landaeta's avatar
Miguel Landaeta committed
79

80 81 82
    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.
Miguel Landaeta's avatar
Miguel Landaeta committed
83

84 85
 4. Create an ANT_HOME environment variable to point the directory
    ${ant.home}.
Miguel Landaeta's avatar
Miguel Landaeta committed
86

87 88 89
 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.
Miguel Landaeta's avatar
Miguel Landaeta committed
90 91


92
(3) Building Tomcat @VERSION_MAJOR_MINOR@
Miguel Landaeta's avatar
Miguel Landaeta committed
93

94
(3.1) Checkout or obtain the source code for Tomcat @VERSION_MAJOR_MINOR@
Miguel Landaeta's avatar
Miguel Landaeta committed
95

96 97
Clone the source using git, then checkout a specific major branch or
master for the latest code development, or download and unpack a source
98
package.
Miguel Landaeta's avatar
Miguel Landaeta committed
99

100
 *  Tomcat GitHub repository URL:
Miguel Landaeta's avatar
Miguel Landaeta committed
101

102
        https://github.com/apache/tomcat
Miguel Landaeta's avatar
Miguel Landaeta committed
103

104
 *  Source packages can be downloaded from:
Miguel Landaeta's avatar
Miguel Landaeta committed
105

106
        https://tomcat.apache.org/download-@VERSION_MAJOR@0.cgi
107 108 109 110

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

111 112 113 114 115 116 117 118 119 120 121 122
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.

123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
(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.
Miguel Landaeta's avatar
Miguel Landaeta committed
144

145 146 147
* 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.
148

149 150
* NOTE: Users accessing the Internet through a proxy must use the properties
  file to indicate to Ant the proxy configuration.
Miguel Landaeta's avatar
Miguel Landaeta committed
151

152 153
  The following properties should be added to the ${tomcat.source}/build.properties
  file.
Miguel Landaeta's avatar
Miguel Landaeta committed
154

155
        proxy.use=true
156 157 158 159
        proxy.host=proxy.domain
        proxy.port=8080
        proxy.user=username
        proxy.password=password
Miguel Landaeta's avatar
Miguel Landaeta committed
160

161
  See Apache Ant documentation for the <setproxy> task for details.
Miguel Landaeta's avatar
Miguel Landaeta committed
162

163
 3. Go to the sources directory and run Ant:
Miguel Landaeta's avatar
Miguel Landaeta committed
164

165 166
        cd ${tomcat.source}
        ant
Miguel Landaeta's avatar
Miguel Landaeta committed
167

168
    This will execute the "deploy" target in build.xml.
Miguel Landaeta's avatar
Miguel Landaeta committed
169

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
    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@
187
sources using your git client.
Miguel Landaeta's avatar
Miguel Landaeta committed
188 189 190 191 192 193 194

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

    cd ${tomcat.source}
    ant


195 196
(5) Special builds

197 198 199 200
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.
201

202
(5.1) Building documentation
203

204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
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:
Miguel Landaeta's avatar
Miguel Landaeta committed
219 220 221 222

    cd ${tomcat.source}
    ant javadoc

223 224 225 226 227 228 229
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

230

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

233 234 235 236 237 238
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:

Miguel Landaeta's avatar
Miguel Landaeta committed
239 240 241
    cd ${tomcat.source}
    ant extras

242 243
(5.3) Building the embedded packages

244 245 246 247
These are built during a "release" build.

You can build them by using the following commands:

Miguel Landaeta's avatar
Miguel Landaeta committed
248 249 250
    cd ${tomcat.source}
    ant embed

251 252 253

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

254 255
    A full release includes the Windows installer which requires a Windows
    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 258 259
    the case, the skip.installer property may be set to skip the creation of the
    Windows installer.

260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
 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.

277 278 279 280 281 282 283
 2. If building the Windows installer

    If running the build in a UAC enabled environment, building the Windows
    installer requires elevated privileges. The simplest way to do this is to
    open the command prompt used for the build with the "Run as administrator"
    option.

284 285 286 287 288 289 290 291 292 293 294 295 296
 3. Configure the code signing service

    ASF committers performing official releases will need to configure the code
    signing service so that the Windows installer is signed during the build
    process. The following properties need to be added to the build.properties
    file:

        # Location of GPG executable (used only for releases)
        # Code signing of Windows installer
        do.codesigning=true
        codesigning.user=request-via-pmc
        codesigning.pwd=request-via-pmc
        codesigning.partnercode=request-via-pmc
297
        codesigning.service=Microsoft Windows Signing
298 299 300 301

    Release managers will be provided with the necessary credentials by the PMC.

 4. Build the release:
Miguel Landaeta's avatar
Miguel Landaeta committed
302 303 304

    cd ${tomcat.source}
    ant release
305 306


307
(7) Tests
308

309
(7.1) Running Tomcat tests
310

311 312
Tomcat includes a number of junit tests. The tests are not run when a
release is built. There is separate command to run them.
313 314 315 316 317 318 319 320 321 322 323 324 325 326

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

327 328
By default the testsuite is run three times to test 3 different
implementations of Tomcat connectors: NIO, NIO2 and APR. (If you are not
329 330 331
familiar with Tomcat connectors, see config/http.html in documentation for
details).

332
The 3 runs are enabled and disabled individually by the following
333 334 335
properties, which all are "true" by default:

    execute.test.nio=true
336
    execute.test.nio2=true
337 338 339 340 341 342 343 344 345 346 347 348 349 350
    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.

351 352 353 354 355 356
The unit tests include tests of the clustering functionality which require
multicast to be enabled. There is a simple application provided in the Tomcat
test source (org.apache.catalina.tribes.TesterMulticast) that can be used to
check if a machine supports multicast. Notes on enabling multicast for different
operating systems are provided in the Javadoc for that class.

357

358
(7.2) Running a single test
359 360 361 362 363 364 365 366 367

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

368 369
It is possible to further limit such run to a number of selected test
methods by adding "test.entry.methods" property. The property specifies a
370
comma-separated list of test case methods.
371 372 373 374 375 376

For example:

    test.entry=org.apache.el.lang.TestELArithmetic
    test.entry.methods=testMultiply01,testMultiply02

377

378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393
(7.3) Running a set of tests

It is possible to run a set of JUnit test classes by adding the "test.name"
property to the build.properties file. The property specifies an Ant
includes pattern for the fileset of test class files to run.

The default value is "**/Test*.java", so all test classes are being
executed (with few exceptions - see build.xml for several exclude patterns).

You can include multiple patterns by concatenating them with a comma (",")
as the separator.

For example:

    test.name=**/TestSsl.java,**/TestWebSocketFrameClientSSL.java

394 395 396 397 398 399
You can exclude specific JUnit test classes by adding the "test.exclude"
property to the build.properties file. The property specifies an Ant
excludes pattern for the fileset of test class files to exclude form the run.
The default value is empty, so no classes are excluded. The syntax is the same
as for the property "test.name".

400 401

(7.4) Other configuration options
402

403 404 405 406 407 408 409
 1. It is possible to configure the directory where JUnit reports are
 written to. It is configured by "test.reports" property. The default
 value is

        output/build/logs

 2. It is possible to enable generation of access log file when the tests
410 411 412 413 414 415 416 417 418 419
 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

420
 3. The testsuite respects logging configuration as configured by
421 422 423 424 425 426 427
 ${tomcat.source}/conf/logging.properties

 The log files will be written to the temporary directory used by the
 tests,

        output/test-tmp/logs

428 429 430 431 432
 4. It is possible to configure formatter used by JUnit reports.
 Configuration properties are "junit.formatter.type",
 "junit.formatter.extension" and "junit.formatter.usefile".

 For example the following property disables generation of separate report
433 434 435
 files:

        junit.formatter.usefile=false
436

437 438 439 440 441 442 443 444 445
 5. It is possible to speed up testing by letting JUnit to run several
 tests in parallel.

 This is configured by setting "test.threads" property. The recommended
 value is one thread per core.

 6. Optional support is provided for the Cobertura code coverage tool.

NOTE: Cobertura is licensed under GPL v2 with parts of it being under
446 447
      Apache License v1.1. See https://cobertura.github.io/cobertura/ for details.
      Using it during Tomcat build is optional and is off by default.
448 449

 Cobertura can be enabled using the following properties:
450 451

        test.cobertura=true
452 453 454 455 456
        test.threads=1

 Using Cobertura currently requires setting test.threads configuration
 property to the value of 1. Setting that property to a different value
 will disable code coverage.
457

458 459 460 461
 The report files by default are written to

        output/coverage

462
 7. The performance tests are written to run reasonably powerful machines (such
463
    as a developer may use day to day) assuming no other resource hungry
464 465 466 467 468
    processes are running.

    These assumptions are not always true (e.g. on CI systems running in a
    virtual machine) so the performance tests may be disabled by using the
    following property:
469 470 471

        test.excludePerformance=true

472
 8. Some tests include checks that the access log valve entries are as expected.
473 474 475 476 477
    These checks include timings. On slower / loaded systems these checks will
    often fail. The checks may be relaxed by using the following property:

        test.relaxTiming=true

478
 9. It is known that some platforms (e.g. OSX El Capitan) require IPv4 to
479 480 481 482 483
    be the default for the multicast tests to work. This is configured by
    the following property:

        java.net.preferIPv4Stack=true

484 485 486 487 488
 10. It is possible to control whether the output of the tests is displayed
     on the console or not. By default it is displayed and can be disabled
     by the following property:

        test.verbose=true
489 490 491 492 493

(8) Source code checks

(8.1) Checkstyle

494 495 496 497
NOTE: Checkstyle is licensed under LGPL. Using Checkstyle during Tomcat
      build is optional and is off by default.

      See http://checkstyle.sourceforge.net/ for more information.
498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513

Tomcat comes with a Checkstyle configuration that tests its source code
for 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 automatically
during 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 cache
is located in the following directory:

    output/res/checkstyle

514
It is possible to run the check separately by calling the "validate"
515 516 517 518 519
target. The command is:

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

520

521 522 523 524 525
(8.2) FindBugs

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

526
      See https://spotbugs.github.io/ for more information.
527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543

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

    execute.findbugs=true

To compile Tomcat classes and generate a FindBugs report, call the
"findbugs" target. For example:

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

The report file by default is written to

    output/findbugs


(8.3) End-of-line conventions check
544 545 546 547

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,
548
stored in the Git repository, use Unix style LF line endings.
549 550 551

This test is used by developers to check that the source code adheres to
this convention. It verifies that the ends of lines in textual files are
552 553
appropriate. The idea is to run this check regularly and notify developers
when an inconsistency is detected.
554 555 556 557 558

The command to run this test is:

    cd ${tomcat.source}
    ant validate-eoln