JBoss.orgCommunity Documentation
The JBoss DNA project uses Maven as its primary build tool, Subversion for its source code repository, JIRA for the issue management and bug tracking system, and Hudson for the continuous integration system. We do not stipulate a specific integrated development environment (IDE), although most of us use Eclipse and rely upon the code formatting and compile preferences to ensure no warnings or errors.
The rest of this chapter talks in more detail about these different tools and how to set them up.
Currently, JBoss DNA is developed and built using JDK 5. So if you're trying to get JBoss DNA to compile locally, you should make sure you have the JDK 5 installed and are using it. If you're a contributor, you should make sure that you're using JDK 5 before committing any changes.
You should be able to use the latest JDK, which is currently JDK 6. We periodically try to build JBoss DNA using JDK 6, but it's not our official JDK (yet).
Why do we build using JDK 5 and not 6? The main reason is that if we were to use JDK 6, then JBoss DNA couldn't really be used in any applications or projects that still used JDK 5. Plus, anybody using JDK 6 can still use JBoss DNA. However, considering that the end-of-life for Java 5 is October 2009, we may be switching to Java 6 in the coming months.
When installing a JDK, simply follow the procedure for your particular platform. On most platforms, this should set the
JAVA_HOME environment variable. But if you run into any problems, first check that this environment
variable was set to the correct location, and then check that you're running the version you expect by running
the following command:
$ java -version
If you don't see the correct version, double-check your JDK installation.
JBoss DNA uses Subversion as its source code management system, and specifically the instance at JBoss.org. Although you can view the trunk of the Subversion repository directly (or using FishEye) through your browser, it order to get more than just a few files of the latest version of the source code, you probably want to have an SVN client installed. Several IDE's have SVN support included (or available as plugins), but having the command-line SVN client is recommended. See http://subversion.tigris.org/ for downloads and instructions for your particular platform.
Here are some useful URLs for the JBoss DNA Subversion:
Table 2.1. SVN URLs for JBoss DNA
| Repository | URL |
|---|---|
| Anonymous Access URL | http://anonsvn.jboss.org/repos/dna/trunk/ |
| Secure Developer Access URL | http://fisheye.jboss.org/browse/DNA/trunk/ |
| FishEye Code Browser | https://svn.jboss.org/repos/dna/trunk/ |
JBoss DNA uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus everything that library needs. This means that it's very easy to build the examples - or even create a maven project that depends on the JBoss DNA JARs.
To use Maven with JBoss DNA, you'll need to have JDK 5 or 6 and Maven 2.0.9 (or higher).
Maven can be downloaded from http://maven.apache.org/, and is installed by unzipping the
maven-2.0.9-bin.zip file to a convenient location on your local disk. Simply add $MAVEN_HOME/bin
to your path and add the following profile to your ~/.m2/settings.xml file:
<settings>
<profiles>
<profile>
<id>jboss.repository</id>
<activation>
<property>
<name>!jboss.repository.off</name>
</property>
</activation>
<repositories>
<repository>
<id>snapshots.jboss.org</id>
<url>http://snapshots.jboss.org/maven2</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<repository>
<id>repository.jboss.org</id>
<url>http://repository.jboss.org/maven2</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>repository.jboss.org</id>
<url>http://repository.jboss.org/maven2</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>snapshots.jboss.org</id>
<url>http://snapshots.jboss.org/maven2</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
</settings>
This profile informs Maven of the two JBoss repositories (snapshots and releases) that contain all of the JARs for JBoss DNA and all dependent libraries.
It is a policy of the project that the source code and JARs for all dependencies must be loaded into the JBoss repository. This is so that the project can always be built and that all source code is always available.
For more information about the JBoss Maven repository, see the JBoss.org Wiki.
There are just a few commands that are useful for building JBoss DNA (and it's subprojects).
Usually, these are issued while at the top level of the code (usually just below trunk/), although issuing
them inside a subproject just applies to that subproject.
Table 2.2. Useful Maven commands
| Command | Description |
|---|---|
mvn clean | Clean up all built artifacts (e.g., the target/ directory in each project) |
mvn clean install | Clean up all built artifacts, then compile, run the unit tests, and install the resulting JAR artifact(s)
into your local Maven repository (e.g, usually ~/.m2/repository).
|
JBoss DNA's continuous integration is done with several Hudson jobs on JBoss.org. These jobs run periodically and basically run the Maven build process. Any build failures or test failures are reported, as are basic statistics and history for each job.
Table 2.3. Continuous integration jobs
| Job | Description |
|---|---|
| Continuous on JDK 5 | Continuous build that runs after changes are committed to SVN. SVN is polled every 15 minutes. |
| Nightly on JDK 5 | Build that runs every night (usually around 2 a.m. EDT), regardless of whether changes have been committed to SVN since the previous night. |
Many of the JBoss DNA committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making it pretty easy to get an Eclipse workspace running with all of the JBoss DNA projects. Many of the JBoss DNA committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making it pretty easy to get an Eclipse workspace running with all of the JBoss DNA projects.
We're using the latest released version of Eclipse (3.4, called "Ganymede"), available from Eclipse.org. Simply follow the instructions for your platform.
After Eclipse is installed, create a new workspace. Before importing the JBoss DNA projects, import (via "File->Import->Preferences")
the subset of the Eclipse preferences by importing the eclipse-preferences.epf file (located under trunk).
Then, open the Eclipse preferences and open the "Java->Code Style-> Formatter" preference page, and press the "Import" button and
choose the eclipse-code-formatter-profile.xml file (located under trunk). This will load the code
formatting preferences for the JBoss DNA project.
Then install Eclipse plugins for SVN and Maven. (Remember, you will have to restart Eclipse after installing them.) We use the following plugins:
Table 2.4. Continuous integration jobs
| Eclipse Plugins | Update Site URLs |
|---|---|
| Subversive SVN Client | http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/ http://www.polarion.org/projects/subversive/download/integrations/update-site/ |
| Maven Integration for Eclipse | http://m2eclipse.sonatype.org/update/ |
After you check out the JBoss DNA codebase, you can import the JBoss DNA Maven projects into Eclipse as Eclipse projects.
To do this, go to "File->Import->Existing Projects", navigate to the trunk/ folder in the import wizard,
and then check each of the subprojects that you want to have in your workspace.
Don't forget about the projects under extensions/ or docs/.
This section outlines the basic process of releasing JBoss DNA. This must be done either by the project lead or only after communicating with the project lead.
Before continuing, your local workspace should contain no changes and should be a perfect reflection of Subversion. You can verify this by getting the latest from Subversion
$ svn update
and ensuring that you have no additional changes with
$ svn status
You may also want to note the revision number for use later on in the process. The release number is returned by
the svn update command, but may also be found using
$ svn info
At this point, you're ready to verify that everything builds normally.
By default, the project's Maven build process is does not build the documentation, JavaDocs, or assemblies. These take extra time, and most of our builds don't require them. So the first step of releasing JBoss DNA is to use Maven to build all of regular artifacts (e.g., JARs) and these extra documents and assemblies.
Before running Maven commands to build the releases, increase the memory available to Maven with this command:
$ export MAVEN_OPTS=-Xmx256m
To perform this complete build, issue the following command while in the target/ directory:
$ mvn -P assembly clean javadoc:javadoc install
This command runs the "clean", "javadoc:javadoc", and "install" goals using the "assembly" profile, which adds the production of JavaDocs, the Getting Started document, the Reference Guide document, the Getting Started examples, and several ZIP archives. The order of the goals is important, since the "install" goal attempts to include the JavaDoc in the archives.
After this build has completed, verify that the assemblies under target/ have actually been created and that
they contain the correct information.
At this point, we know that the actual Maven build process is building
everything we want and will complete without errors. We can now proceed with preparing for the release.
The version being released should match the JIRA road map. Make sure that all issues related to the release are closed. The project lead should be notified and approve that the release is taking place.
The next step is to ensure that all information in the POM is correct and contains all the information required for the release process. This is called a dry run, and is done with the Maven "release" plugin:
$ mvn -Passembly release:prepare -DdryRun=true
This may download a lot of Maven plugins if they already haven't been downloaded, but it will eventually prompt you for
the release version of each of the Maven projects, the tag name for the release, and the next development versions
(again for each of the Maven projects). The default values are probably acceptable; if not, then check that the
"<version>" tags in each of the POM files is correct and end with "-SNAPSHOT".
After the dry run completes you should clean up the files that the release plugin created in the dry run:
$ mvn -Passembly release:clean
Run the prepare step (without the dryRun option):
$ mvn -Passembly release:prepare
You will again be prompted for the release versions and tag name. These should be the same as what was used during the dry run. This will run the same steps as the dry run, with the additional step of tagging the release in SVN.
If there are any problems during this step, you should go back and try the dry run option.
Next run the perform step which will checkout the files from the tag, do a build, and deploy the generated artifacts.
$ mvn -Passembly release:perform
The deployment is done to the local file system (a local checkout of the JBoss Maven2 repository), so you will need to commit the new files after they are deployed. For more information, see the JBoss wiki.
Note that the release process updates your project's pom.xml files to change the "<version>" values
to the next version. These will then need to be committed onto the trunk of SVN.
At this point, the software has been released and tagged, so now the only thing left is to publish the release onto the project's downloads and documentation pages.