Author: kkolinko Date: Tue Jan 17 16:00:07 2012 New Revision: 1232451 URL: http://svn.apache.org/viewvc?rev=1232451&view=rev Log: Merged revision 1232447 from tomcat/trunk: 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/tc7.0.x/trunk/ (props changed) tomcat/tc7.0.x/trunk/BUILDING.txt tomcat/tc7.0.x/trunk/webapps/docs/building.xml tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml Propchange: tomcat/tc7.0.x/trunk/ ------------------------------------------------------------------------------ --- svn:mergeinfo (original) +++ svn:mergeinfo Tue Jan 17 16:00:07 2012 @@ -1 +1 @@ -/tomcat/trunk:1156115,1156171,1156276,1156304,1156519,1156530,1156602,1157015,1157018,1157151,1157198,1157204,1157810,1157832,1157834,1157847,1157908,1157939,1158155,1158160,1158176,1158195,1158198-1158199,1158227,1158331,1158334-1158335,1158426,1160347,1160592,1160611,1160619,1160626,1160639,1160652,1160720-1160721,1160772,1160774,1160776,1161303,1161310,1161322,1161339,1161486,1161540,1161549,1161584,1162082,1162149,1162169,1162721,1162769,1162836,1162932,1163630,1164419,1164438,1164469,1164480,1164567,1165234,1165247-1165248,1165253,1165273,1165282,1165309,1165331,1165338,1165347,1165360-1165361,1165367-1165368,1165602,1165608,1165677,1165693,1165721,1165723,1165728,1165730,1165738,1165746,1165765,1165777,1165918,1165921,1166077,1166150-1166151,1166290,1166366,1166620,1166686,1166693,1166752,1166757,1167368,1167394,1169447,1170647,1171692,1172233-1172234,1172236,1172269,1172278,1172282,1172556,1172610,1172664,1172689,1172711,1173020-1173021,1173082,1173088,1173090,1173096 ,1173241,1173256,1173288,1173333,1173342,1173461,1173614,1173630,1173659,1173722,1174061,1174239,1174322,1174325,1174329-1174330,1174337-1174339,1174343,1174353,1174799,1174882,1174884,1174975,1174983,1175155,1175158,1175167,1175182,1175190,1175201,1175272,1175275,1175283,1175582,1175589-1175590,1175594,1175602,1175613,1175633,1175690,1175713,1175798,1175889,1175896,1175907,1176584,1176590,1176799,1177050,1177060,1177125,1177152,1177160,1177245,1177850,1177862,1177978,1178209,1178228,1178233,1178449,1178542,1178681,1178684,1178721,1179268,1179274,1180261,1180865,1180891,1180894,1180907,1181028,1181123,1181125,1181136,1181291,1181743,1182796,1183078,1183105,1183142,1183328,1183339-1183340,1183492-1183494,1183605,1184917,1184919,1185018,1185020,1185200,1185588,1185626,1185756,1185758,1186011,1186042-1186045,1186104,1186123,1186137,1186153,1186254,1186257,1186377-1186379,1186479-1186480,1186712,1186743,1186750,1186763,1186890-1186892,1186894,1186949,1187018,1187027-1187028,1187 381,1187753,1187755,1187775,1187801,1187806,1187809,1187827,1188301,1188303-1188305,1188399,1188822,1188930-1188931,1189116,1189129,1189183,1189240,1189256,1189386,1189413-1189414,1189477,1189685,1189805,1189857,1189864,1189882,1190034,1190185,1190279,1190339,1190371,1190388-1190389,1190474,1190481,1194915,1195222-1195223,1195531,1195899,1195905,1195943,1195949,1195953,1195955,1195965,1195968,1196175,1196212,1196223,1196304-1196305,1196735,1196825,1196827,1197158,1197261,1197263,1197299-1197300,1197305,1197339-1197340,1197343,1197382,1197386-1197387,1197480,1197578,1198497,1198528,1198552,1198602,1198604,1198607,1198622,1198640,1198696,1198707,1199418,1199432,1199436,1199513,1199529,1199980,1199996,1200056,1200089,1200106-1200107,1200263,1200316,1200320,1200398-1200399,1200445-1200446,1200555,1200627,1200696,1200725,1200937,1200941,1201069,1201087,1201180,1201235-1201237,1201508,1201521,1201542,1201545-1201546,1201548,1201555-1201556,1201568,1201576,1201608,1201921-1201922,1 201931,1202035,1202039,1202271,1202565,1202578,1202705,1202828,1202860,1203047-1203052,1203078,1203091,1203253,1203278,1204182,1204856,1204867,1204936,1204938,1204982,1205033,1205065,1205082,1205097,1205112,1206200,1207692,1208046,1208073,1208096,1208114,1208145,1208772,1209194,1209277-1209278,1209686-1209731,1210894,1212091,1212095,1212099,1212118,1213469,1213906,1214853,1214855,1214864,1215115,1215118-1215119,1215121,1220293,1220295,1221038,1221842,1222189,1222201,1222276,1222300,1222690,1222850,1222852,1222855,1224607,1224617,1224648-1224652,1224657,1224662-1224663,1224682,1224801,1224910,1225000,1225219,1225343,1225465,1225627,1225629,1225634,1226069,1226158-1226159,1226177,1226196,1226214-1226215,1226385,1226394,1226500,1226537-1226538,1226546,1226551,1226975,1228196,1228360,1228376,1228724,1228908,1228918,1228920,1228922,1228929,1228969,1229307,1229536,1229549,1229724,1229726-1229731,1229997,1230539,1230711,1230729,1230762-1230763,1230765,1230955,1230957,1231285,123129 0,1231308,1231310,1231337,1231460-1231461,1231542-1231543,1231546-1231547,1231620-1231621,1231624-1231625,1231630,1231654-1231655,1231738,1231740,1231762-1231763,1231856,1231886,1231923,1231947,1232345,1232368,1232380 +/tomcat/trunk:1156115,1156171,1156276,1156304,1156519,1156530,1156602,1157015,1157018,1157151,1157198,1157204,1157810,1157832,1157834,1157847,1157908,1157939,1158155,1158160,1158176,1158195,1158198-1158199,1158227,1158331,1158334-1158335,1158426,1160347,1160592,1160611,1160619,1160626,1160639,1160652,1160720-1160721,1160772,1160774,1160776,1161303,1161310,1161322,1161339,1161486,1161540,1161549,1161584,1162082,1162149,1162169,1162721,1162769,1162836,1162932,1163630,1164419,1164438,1164469,1164480,1164567,1165234,1165247-1165248,1165253,1165273,1165282,1165309,1165331,1165338,1165347,1165360-1165361,1165367-1165368,1165602,1165608,1165677,1165693,1165721,1165723,1165728,1165730,1165738,1165746,1165765,1165777,1165918,1165921,1166077,1166150-1166151,1166290,1166366,1166620,1166686,1166693,1166752,1166757,1167368,1167394,1169447,1170647,1171692,1172233-1172234,1172236,1172269,1172278,1172282,1172556,1172610,1172664,1172689,1172711,1173020-1173021,1173082,1173088,1173090,1173096 ,1173241,1173256,1173288,1173333,1173342,1173461,1173614,1173630,1173659,1173722,1174061,1174239,1174322,1174325,1174329-1174330,1174337-1174339,1174343,1174353,1174799,1174882,1174884,1174975,1174983,1175155,1175158,1175167,1175182,1175190,1175201,1175272,1175275,1175283,1175582,1175589-1175590,1175594,1175602,1175613,1175633,1175690,1175713,1175798,1175889,1175896,1175907,1176584,1176590,1176799,1177050,1177060,1177125,1177152,1177160,1177245,1177850,1177862,1177978,1178209,1178228,1178233,1178449,1178542,1178681,1178684,1178721,1179268,1179274,1180261,1180865,1180891,1180894,1180907,1181028,1181123,1181125,1181136,1181291,1181743,1182796,1183078,1183105,1183142,1183328,1183339-1183340,1183492-1183494,1183605,1184917,1184919,1185018,1185020,1185200,1185588,1185626,1185756,1185758,1186011,1186042-1186045,1186104,1186123,1186137,1186153,1186254,1186257,1186377-1186379,1186479-1186480,1186712,1186743,1186750,1186763,1186890-1186892,1186894,1186949,1187018,1187027-1187028,1187 381,1187753,1187755,1187775,1187801,1187806,1187809,1187827,1188301,1188303-1188305,1188399,1188822,1188930-1188931,1189116,1189129,1189183,1189240,1189256,1189386,1189413-1189414,1189477,1189685,1189805,1189857,1189864,1189882,1190034,1190185,1190279,1190339,1190371,1190388-1190389,1190474,1190481,1194915,1195222-1195223,1195531,1195899,1195905,1195943,1195949,1195953,1195955,1195965,1195968,1196175,1196212,1196223,1196304-1196305,1196735,1196825,1196827,1197158,1197261,1197263,1197299-1197300,1197305,1197339-1197340,1197343,1197382,1197386-1197387,1197480,1197578,1198497,1198528,1198552,1198602,1198604,1198607,1198622,1198640,1198696,1198707,1199418,1199432,1199436,1199513,1199529,1199980,1199996,1200056,1200089,1200106-1200107,1200263,1200316,1200320,1200398-1200399,1200445-1200446,1200555,1200627,1200696,1200725,1200937,1200941,1201069,1201087,1201180,1201235-1201237,1201508,1201521,1201542,1201545-1201546,1201548,1201555-1201556,1201568,1201576,1201608,1201921-1201922,1 201931,1202035,1202039,1202271,1202565,1202578,1202705,1202828,1202860,1203047-1203052,1203078,1203091,1203253,1203278,1204182,1204856,1204867,1204936,1204938,1204982,1205033,1205065,1205082,1205097,1205112,1206200,1207692,1208046,1208073,1208096,1208114,1208145,1208772,1209194,1209277-1209278,1209686-1209731,1210894,1212091,1212095,1212099,1212118,1213469,1213906,1214853,1214855,1214864,1215115,1215118-1215119,1215121,1220293,1220295,1221038,1221842,1222189,1222201,1222276,1222300,1222690,1222850,1222852,1222855,1224607,1224617,1224648-1224652,1224657,1224662-1224663,1224682,1224801,1224910,1225000,1225219,1225343,1225465,1225627,1225629,1225634,1226069,1226158-1226159,1226177,1226196,1226214-1226215,1226385,1226394,1226500,1226537-1226538,1226546,1226551,1226975,1228196,1228360,1228376,1228724,1228908,1228918,1228920,1228922,1228929,1228969,1229307,1229536,1229549,1229724,1229726-1229731,1229997,1230539,1230711,1230729,1230762-1230763,1230765,1230955,1230957,1231285,123129 0,1231308,1231310,1231337,1231460-1231461,1231542-1231543,1231546-1231547,1231620-1231621,1231624-1231625,1231630,1231654-1231655,1231738,1231740,1231762-1231763,1231856,1231886,1231923,1231947,1232345,1232368,1232380,1232447 Modified: tomcat/tc7.0.x/trunk/BUILDING.txt URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/BUILDING.txt?rev=1232451&r1=1232450&r2=1232451&view=diff ============================================================================== --- tomcat/tc7.0.x/trunk/BUILDING.txt (original) +++ tomcat/tc7.0.x/trunk/BUILDING.txt Tue Jan 17 16:00:07 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 @VERSION_MAJOR_MINOR@ 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-70.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 7 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/tc7.0.x/trunk/webapps/docs/building.xml URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/building.xml?rev=1232451&r1=1232450&r2=1232451&view=diff ============================================================================== --- tomcat/tc7.0.x/trunk/webapps/docs/building.xml (original) +++ tomcat/tc7.0.x/trunk/webapps/docs/building.xml Tue Jan 17 16:00:07 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. Modified: tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml?rev=1232451&r1=1232450&r2=1232451&view=diff ============================================================================== --- tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml (original) +++ tomcat/tc7.0.x/trunk/webapps/docs/changelog.xml Tue Jan 17 16:00:07 2012 @@ -53,6 +53,17 @@ They eventually become mixed with the numbered issues. (I.e., numbered issues to not "pop up" wrt. others). --> +<section name="Tomcat 7.0.26 (markt)"> + <subsection name="Web applications"> + <changelog> + <update> + Improve <code>BUILDING.txt</code>. Update instructions for + building. Add instructions for using Checkstyle and running the + tests. (kkolinko) + </update> + </changelog> + </subsection> +</section> <section name="Tomcat 7.0.25 (markt)"> <subsection name="Web applications"> <changelog> --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org