Appendix C. Building the Server from Source Code - JBoss Application Server 4.0.4 release5 Guide 英文版指南文档
Source code is available for every JBoss module, and you can build any version of JBoss from source by downloading the appropriate version of the code from JBoss CVS.
The source code for any released version of JBoss can be downloaded from the JBoss AS download page, http://www.jboss.com/products/jbossas/downloads. Follow the download links and select the source distribution for the version you want. For JBoss 4.0.4, you would download jboss-4.0.4-src.tar.gz. Extract the contents of the archive to prepare a buildable JBoss source tree.
The JBoss project's CVS repository can be accessed through anonymous CVS at anoncvs.forge.jboss.com. If you've never accessed JBoss CVS before, the first step is to log in. This command only needs to be performed once for each machine on which you use CVS because the login information will be saved in your $HOME/.cvspass file or equivalent for your system. When prompted for a password for anonymous, simply press return.
cvs -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss login
A JBoss source tree can be checked out using a simple co command. The main JBoss tree is jboss-head and can be checked out as shown in the following command:
cvs -z3 -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss co modulename
jboss-head is the JBoss 5 development repository. To check out the current JBoss 4 tree, you should check out the jboss-4.0.x module from the Branch_4_0 branch:
cvs -z3 -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss co -r Branch_4_0 jboss-4.0.x
Branch_4_0 is the development branch of the JBoss 4.0 tree. Specific older releases can be accessed by adding the minor version. Branch_4_0_4 would retrieve the JBoss AS 4.0.4 branch, for example.
After downloading or checking out JBoss, go to the build directory and execute the build.sh or build.bat file, as appropriate for you OS. You will need to set the JAVA_HOME environment variable to the location of the JDK you wish to use for compilation, and the JDK bin directory should be on your path.
[jboss-4.0.x]$ cd build
[build]$ ./build.sh
...
BUILD SUCCESSFUL
Total time: 2 minutes 41 seconds
Note that if you see an "Failed to launch JJTree" error do not have the JAVA_HOME/bin directory in your PATH required for the JavaCC JJTree Ant task.
The build process is driven by an Ant based configuration. The main Ant build script is the build.xml file located in the jboss-4.0.x/build directory. The purpose of the main build.xml file is to compile the various JBoss modules and then to integrate their output to produce the binary release. The binary release structure is found under the build/output directory. The example above used the build.sh script to kickoff the build process. This is just a wrapper the launches the ant binary included in the distribution. You can use Ant directly to build if your environment is configured run it from the command line.
More advanced testing of the JBoss installation and builds can be done using the JBoss testsuite. The JBossTest suite is a collection of client oriented unit tests of the JBoss server application. It is an Ant based package that uses the JUnit (http://www.junit.org) unit test framework. The JBossTest suite is used as a QA benchmark by the development team to help test new functionality and prevent introduction of bugs. It is run on a nightly basis and the results are posted to the development mailing list for all to see.
The unit tests are run using Ant and the source for the tests are contained in the testsuite directory of the source tree. The structure of the testsuite CVS module is illustrated in Figure C.1, “The testsuite CVS module directory structure”.
The two main source branches are src/main and src/resources. The src/main tree contains the Java source code for the unit tests. The src/resources tree contains resource files like deployment descriptors, JAR manifest, web content, etc. The root package of every unit test is org.jboss.test. The typical structure below each specific unit test subpackage (for example, security) consists of a test package that contains the unit test classes. The test subpackage is a required naming convention as this is the only directory searched for unit tests by the Ant build scripts. If the tests involves EJBs then the convention is to include an interfaces and ejb subpackage for these components. The unit tests themselves need to follow a naming convention for the class file. The unit test class must be named XXXUnitTest.java, where XXX is either the class being tested or the name of the functionality being tested.
To run the unit tests use the build scripts located in the testsuite directory. The key targets in the build.xml file include:
tests: this target builds and runs all unit tests and generates HTML and text reports of the tests into the testsuite/output/reports/html and testsuite/output/reports/text directories respectively.
tests-standard-unit: builds all unit tests and runs a subset of the key unit tests. This is useful for quick check of the server to test for gross problems.
test: this target allows one to run all tests within a particular package. To run this target you need to specify a test property that specifies a package name using -Dtest=package command line. The package value is the name of the package below org.jboss.test you want to run unit tests for. So, for example, to run all unit tests in the org.jboss.test.naming package, you would use: build.sh -Dtest=naming test
one-test: this target allows you to run a single unit test. To run this target you need to specify a test property that specifies the classname of the unit test using -Dtest=classname on the command line. So, for example, to run the org.jboss.test.naming.test.ENCUnitTestCase, you would use: build.sh -Dtest=org.jboss.test.naming.test.ENCUnitTestCase one-test
tests-report: this target generates html and text reports of the tests into the testsuite/output/reports/html and testsuite/output/reports/text directories respectively using the current JUnit XML results in the testsuite/output/reports directory. This is useful for generating the nice html reports when you have run a subset of the tests by hand and want to generate a summary.
On completion of a test the testsuite/output/reports directory will contain one or more XML files that represent the individual JUnit test runs. The tests-report target collates these into an HTML report located in the html subdirectory along with a text report located in the text subdirectory. Figure C.2, “An example testsuite run report status HTML view as generated by the testsuite” shows an example of the HTML report for a run of the test suite against the JBoss 4.0.1 release.
You can find the results of the testsuite in the JBoss distribution in under the JBOSS_DIST/docs/tests directory.