Appendix C. Building the Server from Source Code - JBoss Application Server 4.0.3 release4 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.
CVS (Concurrent Versions System) is an Open Source version control system that is used pervasively throughout the Open Source community. CVS is a source control or revision control tool designed to keep track of source changes made by groups of developers who are working on the same files. CVS enables developers to stay in sync with each other as each individual chooses.
The JBoss project's CVS repository can be accessed through anonymous (pserver) CVS with the following instruction set. The module you want to check out must be specified as the modulename. When prompted for a password for anonymous, simply press the Enter key. The general syntax of the command line version of CVS for anonymous access to the JBoss repositories is:
cvs -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss login cvs -z3 -d:pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss co modulename
The first command logs into JBoss CVS repository as an anonymous user. 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. The second command checks out a copy of the modulename source code into the directory from which you run the cvs command. To avoid having to type the long cvs command line each time, you can set up a CVSROOT environment variable with the value :pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jboss and then use the following abbreviated versions of the previous commands:
cvs login cvs -z3 co modulename
The name of the JBoss module alias you use depends on the version of JBoss you want. For the 4.0 branch the module name is jboss-4.0, for the 3.2 branch it is jboss-3.2, and in general, for branch x.y the module name is jboss-x.y. To checkout the HEAD revision of jboss to obtain the latest code on the main branch you would use jboss-head as the module name. Releases of JBoss are tagged with the pattern JBoss_X_Y_Z where X is the major version, Y is the minor version and Z is the patch version. Release branches of JBoss are tagged with the pattern Branch_X_Y. Some checkout examples are:
cvs co -r Branch_4_0 jboss-4.0 # Checkout the current 4.0 branch code cvs co -r JBoss_4_0_3 jboss-4.0 # Checkout the 4.0.3 release version code cvs co -r JBoss_3_2_6 jboss-3.2 # Checkout the 3.2.6 release version code cvs co jboss-head # Checkout the curent HEAD branch code
The command line version of the CVS program is freely available for nearly every platform, and is included by default on most Linux and UNIX distributions. A good port of CVS as well as numerous other UNIX programs for Win32 platforms is available from Cygwin at http://sources.redhat.com/cygwin/. The syntax of the command line version of CVS will be examined because this is common across all platforms.
For complete documentation on CVS, check out the CVS home page at http://www.cvshome.org/.
Every JBoss release includes a source archive that contains everything needed to build the release and is available from the files section of the JBoss project site here: http://sourceforge.net/projects/jboss/. The source directory structure matches that of the CVS source tree described below so once you have the source distribution you can build the release by following the instructions given in the next section, beginning with the instructions after the step to obtain the jboss-4.0 source tree.
This section will guide you through the task of building a JBoss distribution from the CVS source code. To start, create a directory into which you want to download the CVS source tree, and move into the newly created directory. This directory is referred to as the CVS_WD directory for CVS working directory. The example build in this book will check out code into a /tmp/jboss directory on a Linux system. Next, obtain the 4.0.1 version of the source code as shown here:
[tmp]$ mkdir jboss
[tmp]$ cd jboss
[jboss]$ export CVSROOT=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss
[jboss]$ cvs co -r JBoss_4_0_1 jboss-4.0
cvs checkout: Updating aop
U aop/.classpath
U aop/.cvsignore
U aop/.project
U aop/RELEASE_NOTES.txt
...The resulting jboss-4.0 directory structure contains all of the CVS modules required to build the server. To perform the build, cd to the jboss-all/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]$ cd jboss-4.0/build/
[build]$ ./build.sh
Searching for build.xml ...
Buildfile: /tmp/jboss/jboss-4.0/build/build.xml
...
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/build directory. This script uses a number of custom Ant tasks masked as buildmagic constructs. The purpose of the main build.xml file is to compile the various module directories under jboss-4.0 and then to integrate their output to produce the binary release. The binary release structure is found under the jboss-4.0/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.
The top-level directory structure under the jboss-4.0 source tree is illustrated in Figure C.1, “The testsuite CVS module directory structure”, the CVS source tree top-level directories. Table C.1, “Descriptions of the top-level directories of the JBoss CVS source tree.” gives the primary purpose of each of the top-level directories.
Table C.1. Descriptions of the top-level directories of the JBoss CVS source tree.
| Directory | Description |
|---|---|
| aop | The JBoss AOP module |
| aspects | The JBossAOP aspect library |
| build | The main build directory from which the release builds are initiated |
| cache | The JBoss TreeCache module |
| cluster | The clustering support services source module |
| common | A source module of common utility type code used by many of the other source modules |
| connector | The JCA support and application server integration source module |
| console | Admin apps for viewing the JMX MBeans |
| deployment | The JSR 88 J2EE application deployment module |
| ejb3 | The EJB3 implementation |
| ejb3x | The EJB3 annotations |
| hibernate-int | The Hibernate deployer service |
| iiop | The RMI/IIOP transport service source module |
| j2ee | The core J2EE interfaces and classes |
| jaxrpc | The J2EE web services module |
| jboss.net | A web services support source module that provides support for using SOAP to invoke operations on EJBs and MBeans |
| jmx | The JBoss JMX implementation source module |
| jmx-remoting | The JMX remoting module |
| management | The JBoss JSR-77 source module |
| media | The enterprise media beans module |
| messaging | The JBoss JMS implementation source module |
| naming | The JBoss JNDI implementation source module |
| remoting | The JBoss remoting modules |
| security | The JBoss standard J2EE declarative security implementation based on JAAS |
| server | The EJB container |
| system | The JMX micro kernel based bootstrap services and standard deployment services source module |
| test | The unit test support classes |
| testsuite | The JUnit unit test source module |
| thirdparty | A module containing the third-party binary JARs used by the JBoss modules |
| tomcat | The Tomcat-5.0.x embedded service source module |
| tools | The JARs used by the JBoss build process |
| transaction | The JTA transaction manager |
| varia | Various utility services that have not or will not been integrated into one of the higher-level modules |
| webservice | The J2EE web service implementation in JBoss |
| xdoclet-int | The XDoclet support library |
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 jboss-4.0/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.