Author: kkolinko
Date: Tue Jan 17 15:46:44 2012
New Revision: 1232447
URL: http://svn.apache.org/viewvc?rev=1232447&view=rev
Log:
Improve BUILDING.txt.
Especially:
1. Reformat the document.
2. Document creation of "build.properties" as an explicit step before building.
3. Document enabling GPG when doing a release.
4. Document enabling Checkstyle.
5. Document running the tests.
Modified:
tomcat/trunk/BUILDING.txt
tomcat/trunk/webapps/docs/building.xml
Modified: tomcat/trunk/BUILDING.txt
URL:
http://svn.apache.org/viewvc/tomcat/trunk/BUILDING.txt?rev=1232447&r1=1232446&r2=1232447&view=diff
==============================================================================
--- tomcat/trunk/BUILDING.txt (original)
+++ tomcat/trunk/BUILDING.txt Tue Jan 17 15:46:44 2012
@@ -33,119 +33,290 @@ In order to build a binary distribution
source distribution, do the following:
-(0) Download and Install a Java Development Kit
+(1) Download and Install a Java Development Kit
-* If the JDK is already installed, skip to (1).
+ 1. If the JDK is already installed, skip to (2).
-* Download a Java Development Kit (JDK) release (version 1.6.x or later) from:
+ 2. Download a Java Development Kit (JDK) release (version 1.6.x or later)
+ from:
- http://www.oracle.com/technetwork/java/javase/downloads/index.html
+ http://www.oracle.com/technetwork/java/javase/downloads/index.html
-* Install the JDK according to the instructions included with the release.
+ 3. Install the JDK according to the instructions included with the release.
-* Set an environment variable JAVA_HOME to the pathname of the directory
- into which you installed the JDK release.
+ 4. Set an environment variable JAVA_HOME to the pathname of the directory
+ into which you installed the JDK release.
-(1) Install Apache Ant 1.8.x on your computer
+(2) Install Apache Ant 1.8.x on your computer
-* If Apache Ant 1.8.x is already installed on your computer, skip to (2).
+ 1. If Apache Ant 1.8.x is already installed on your computer, skip to (3).
-* Download a binary distribution of Ant 1.8.x from:
+ 2. Download a binary distribution of Ant 1.8.x from:
- http://ant.apache.org/bindownload.cgi
+ http://ant.apache.org/bindownload.cgi
-* 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.
+ 3. Unpack the binary distribution into a convenient location so that the
+ Ant release resides in its own directory (conventionally named
+ "apache-ant-[version]").
-* Create an ANT_HOME environment variable to point the directory
- ${ant.home}.
+ 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.
-* 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.
+ 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.
-(2) Building Tomcat @VERSION_MAJOR_MINOR@
-(2.1) Checkout or obtain the source code for Tomcat @VERSION_MAJOR_MINOR@
+(3) Building Tomcat @VERSION_MAJOR_MINOR@
-* Tomcat SVN repository URL:
- http://svn.apache.org/repos/asf/tomcat/tc@VERSION_MAJOR_MINOR@.x/trunk/
+(3.1) Checkout or obtain the source code for Tomcat @VERSION_MAJOR_MINOR@
-* Download a source package from:
- http://tomcat.apache.org/download-@version_ma...@0.cgi
+Checkout the source using SVN, selecting a tag for released version or
+trunk for the current development code, or download and unpack a source
+package.
-* Checkout the source using SVN, selecting a tag for released version or
- trunk for the current development code, or unpack a source package. The
- location where the source has been placed will be referred as
- ${tomcat.source}.
+ * Tomcat SVN repository URL:
-(2.2) Building
+ http://svn.apache.org/repos/asf/tomcat/tc@VERSION_MAJOR_MINOR@.x/trunk/
-* Go to that directory, and do:
+ * Source packages can be downloaded from:
- cd ${tomcat.source}
- ant
+ http://tomcat.apache.org/download-@version_ma...@0.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: Running this command will 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,
- and, even if you do, it may not be appropriate for you to write there.
+* 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. Read below to learn how to customize
- the directory used to download the binaries.
+ directory, unless Cygwin is used.
-* NOTE: Users accessing the Internet through a proxy must use a properties
- file to indicate to Ant the proxy configuration. Read below.
+* NOTE: Users accessing the Internet through a proxy must use the properties
+ file to indicate to Ant the proxy configuration.
-* The build can be controlled by creating a ${tomcat.source}/build.properties
- file, and adding the following content to it:
+ The following properties should be added to the
${tomcat.source}/build.properties
+ file.
- # ----- Proxy setup -----
- # Uncomment if using a proxy server
- #proxy.host=proxy.domain
- #proxy.port=8080
- #proxy.use=on
+ proxy.use=on
+ proxy.host=proxy.domain
+ proxy.port=8080
+ proxy.user=username
+ proxy.password=password
- # ----- 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
+ See Apache Ant documentation for the <setproxy> task for details.
+ 3. Go to the sources directory and run Ant:
-(3) Updating sources
+ cd ${tomcat.source}
+ ant
-It is recommended that you regularly update the downloaded Tomcat
@VERSION_MAJOR_MINOR@ sources
-using your SVN client.
+ This will execute the "deploy" target in build.xml.
-(4) Rebuilds
+ 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@
+sources using your SVN client.
For a quick rebuild of only modified code you can use:
cd ${tomcat.source}
ant
-(5) Building the servlet and jsp API documentation
-The documentation can be easly built:
+(5) Special builds
+
+Some Tomcat components, that are included in the full release, but are not
+built during the default "deploy" build, can also be built separately.
+
+(5.1) Building API documentation (Javadoc)
+
+The API documentation can be easily built:
cd ${tomcat.source}
ant javadoc
-(6) Building the extras (commons-logging, webservices etc.).
+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.)
+
cd ${tomcat.source}
ant extras
-(7) Building the embedded packages.
+(5.3) Building the embedded packages
+
cd ${tomcat.source}
ant embed
-(8) Building a full release (as provided via the ASF download pages):
+
+(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) Enabling Checkstyle
+
+Tomcat comes with a Checkstyle configuration that tests its source code
+for certain conventions, like presence of the license header.
+
+To enable Checkstyle checks during Tomcat build, add the following property
+to build.properties file:
+
+ execute.validate=true
+
+* NOTE: Checkstyle is licensed under LGPL. Using Checkstyle during Tomcat
+ build is optional and is off by default.
+
+
+(8) Running the tests
+
+The tests are not run when a release is built. There is separate command
+for running the tests.
+
+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
+
+
+(8.1) Testing with APR connector
+
+By default the testsuite is run three times to test 3 different
+implementations of Tomcat connectors: BIO, NIO and APR. (If you are not
+familiar with Tomcat connectors, see config/http.html in documentation for
+details).
+
+The 3 runs are enabled and disabled individually by the following
+properties, 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 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.
+
+
+(8.2) Running a single test class
+
+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
+
+
+(8.3) Other 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
Modified: tomcat/trunk/webapps/docs/building.xml
URL:
http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/building.xml?rev=1232447&r1=1232446&r2=1232447&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/building.xml (original)
+++ tomcat/trunk/webapps/docs/building.xml Tue Jan 17 15:46:44 2012
@@ -118,7 +118,7 @@ Use the following commands to build Tomc
to build Tomcat to the <code>/usr/share/java</code> directory by default.
On a typical Linux or MacOX system, an ordinary user
will not have access to write to this directory, and, even if you do,
- it may not be appropriate for you to write there. On Windows
+ it is likely not appropriate for you to write there. On Windows
this usually corresponds to the <code>C:\usr\share\java</code> directory,
unless Cygwin is used. Read below to learn how to customize the directory
used to download the binaries.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
