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 SourceForge. Accessing the JBoss CVS Repositories at SourceForgeThe JBoss source is hosted at SourceForge, a great open-source community service provided by VA Linux Systems. With more than 88,000 open-source projects and nearly 950,000 registered users, SourceForge is the largest open-source hosting service available. Many of the top open-source projects have moved their development to the SourceForge.net site. The services offered by SourceForge include hosting of project CVS repositories and a web interface for project management that includes bug tracking, release management, mailing lists, and more. Best of all, these services are free to all open-source developers. For additional details and to browse the plethora of projects, see the SourceForge home page (http://sourceforge.net). Understanding CVSCVS 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 that is 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. Anonymous CVS AccessThe JBoss project's SourceForge CVS repository can be accessed through anonymous (pserver) CVS. The module you want to check out must be specified as modulename. When prompted for a password for anonymous, you simply press the Enter key. The following is the general syntax of the command-line version of CVS for anonymous access to the JBoss repositories: cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss login cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss co modulename The first command logs you in to the JBoss CVS repository as an anonymous user. This command needs to be performed only once for each machine on which you use CVS because the login information will be saved in your HOME/.cvspass file or the 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@cvs.jboss.sourceforge.net:/cvsroot/jboss and then use the following abbreviated versions of the previous commands: cvs login 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 check out 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. The following are some checkout examples: cvs co -r Branch_4_0 jboss-4.0 # Checkout the current 3.0 branch code cvs co -r JBoss_4_0_1 jboss-4.0 # Checkout the 4.0.1 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 current HEAD branch code Obtaining a CVS ClientThe command-line version of the CVS program is freely available for nearly every platform, and it is included by default on most Linux and Unix distributions. A good port for CVS as well as numerous other Unix programs for Windows 32-bit platforms is Cygwin, at http://sources.redhat.com/cygwin/. In the next few sections, let's examine the syntax of the command-line version of CVS, which is common across all platforms. Note For complete documentation on CVS, check out the CVS home page, at www.cvshome.org. Building the JBoss Distribution Using the Source CodeEvery 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, at http://sourceforge.net/projects/jboss/. The source directory structure matches that of the CVS source tree described in the following section, 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. Building the JBoss Distribution Using the CVS Source CodeThis section guides you through the task of building a JBoss distribution from the CVS source code. To start, you create a directory into which you want to download the CVS source tree, and then you 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 checks out code into a /tmp/jboss directory on a Linux system. Next, you 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 the CVS modules required to build the server. To perform the build, you cd to the jboss-all/build directory and execute the build.sh or build.bat file, as appropriate for your OS. You 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 a "Failed to launch JJTree" error, you do not have in your PATH variable the JAVA_HOME/bin directory that is 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 preceding example uses the build.sh script to kick off the build process. This is just a wrapper that launches the ant binary included in the distribution. You can use Ant directly to build if your environment is configured to run it from the command line. An Overview of the JBoss CVS Source TreeThe top-level directory structure under the jboss-4.0 source tree is illustrated in Figure 1.3, which shows the CVS source tree top-level directories. Table 1.2 describes the primary purpose of each of the top-level directories. Figure 1.3. The testsuite CVS module directory structure.
Using the JBossTest Unit TestsuiteYou can do more advanced testing of the JBoss installation and builds by using the JBoss Testsuite. The JBoss Testsuite is a collection of client-oriented unit tests of the JBoss server application. It is an Ant-based package that uses the JUnit (www.junit.org) unit test framework. The JBoss Testsuite 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 1.3. The two main source branches of the testsuite CVS module 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 such as deployment descriptors, JAR manifest, web content, and so on. 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 because this is the only directory that is searched for unit tests by the Ant build scripts. If the tests involve EJBs, then the convention is to include interfaces and ejb subpackages 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, you use the build scripts located in the testsuite directory. The key targets in the build.xml file include the following:
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 1.4 shows an example of the HTML report for a run of the testsuite against the JBoss 4.0.1 release. Figure 1.4. An example of a testsuite-run report in status HTML view, as generated by the testsuite.You can find the results of the testsuite in the JBoss distribution under the JBOSS_DIST/docs/tests directory. |