See also: ModeShape Development Tools ModeShape Development Workflow ModeShape Development Guidelines

The ModeShape project uses Maven for its build system. This document describes how to set up Maven 3 in your local environment, and how to use it to build the ModeShape source code.

Prerequisites

ModeShape requires JDK 1.6, so be sure that's installed correctly. (See ModeShape Development Tools for more details.)

Setup

Download the Maven 3.0.1 (or later) archive and extract to the desired location (e.g., "/usr/local/"). Then add the "bin" directory to your path. If you need to keep Maven 2, I'd suggest using a symbolic link at "/usr/local/maven" that points to the actual Maven installation (e.g., "/usr/local/apache-maven-3.0.2"); a script or shell alias can change the symbolic link to your Maven 2 installation. So far this is a typical Maven installation.

ModeShape has a lot of tests, and our build needs a bit more memory to run (especially the full build that runs everything). Set the MAVEN_OPTS to the following:

-Xmx1024m -XX:MaxPermSize=512m

Check your Maven installation by verifying the following command produces similar output (based upon your platform):

$ mvn --version
Apache Maven 3.0.2 (r1056850; 2011-01-08 18:58:10-0600)
Java version: 1.6.0_22, vendor: Apple Inc.
Java home: /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x", version: "10.6.6", arch: "x86_64", family: "mac"

Building

The following Maven command runs a complete build:

$ mvn -s settings.xml -Passembly clean install

This cleans up any prior output, downloads missing but required libraries and plugins, compiles all code, runs all unit and integration tests, produces all JARs and WARs, installs all JARs into your local Maven repository, and generates all documentation and ZIP assemblies (most of which are placed in the 'modeshape-distribution/target' directory). This command may take a while to run, especially if Maven has to download a lot of libraries and plugins. Maven will cache them, so that subsequent builds will go significantly faster.

Sometimes, you don't even need to produce the ZIP assemblies, and only need to compile ModeShape and install the JARs into your local Maven repository. For example, you may be trying to add features or fix bugs in ModeShape, or you may be developing a Maven-based application that uses ModeShape and you want to use the latest codebase. In these cases, you really just need to compile the code, run the tests, and install the JARs into your local Maven repository. The following command will do just this by using the "integration" profile instead of the "assembly" profile:

$ mvn -s settings.xml -Pintegration clean install

This is a bit faster than building with the assembly profile used in the previous commands, but it still runs all the unit and integration tests and creates the AS7 kit. If you just want to compile ModeShape and install the JARs into your local Maven repository but want to completely skip the integration and unit tests (and not build the AS7 kit), simply exclude any profiles:

$ mvn -s settings.xml clean install

Cleaning up

Occasionally, you may want to just clean up all generated output (e.g, the "target" directory in each module), and to do this you can use the following command:

$ mvn -s settings.xml -Passembly clean

Changing your Maven settings

You'll note that each of the commands listed above uses the "-s settings.xml" argument. This tells Maven to use the "settings.xml" file in the ModeShape codebase instead of your ~/.m2/settings.xml file. This is because all of the ModeShape and JBoss artifacts are housed in the JBoss.org Maven repository, and Maven needs to know this.

If you don't like using "-s settings.xml" in your Maven commands, you can always edit your ~/.m2/settings.xml file to add the information that is in our "settings.xml" file, and then you can leave off the "-s settings.xml" from all of your Maven commands.

If you're a contributor, you probably want to do this. If you will be making and publishing ModeShape releases into the JBoss.org repository, you definitely need to do this, and need to modify your ~/.m2/settings.xml file to contain your JBoss.org repository credentials.

See the documentation for developers for details on how to edit your ~/.m2/settings.xml file.

Publishing releases to Maven

ModeShape releases are published in the JBoss Maven repository and to Maven Central. This must be done either by the project lead or only after communicating with the project lead.

First, in order to publish the releases, you'll need to have the following in your ${HOME}/.m2/settings.xml file as described earlier, but be sure to include your JBoss.org repository credentials:

  ...
  
    ...
    
      jboss-snapshots-repository
      your JBoss.org username
      your JBoss.org password
    
    
      jboss-releases-repository
      your JBoss.org username
      your JBoss.org password
    
    ...
  
  ...

Publishing snapshots

The following command will build the current codebase, install into your local Maven repository, and also publish the snapshot build into the JBoss Maven repository:

$ mvn clean deploy -DskipTests

Publishing releases

The first step is to get the latest from the correct branch of the ModeShape Git repository and do a full build to ensure the code is indeed buildable:

$ mvn -Passembly clean install

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.

See the ModeShape Release Process more information about the ModeShape release process.

Troubleshooting

When a Maven 3 build fails, the last line will tell you how you can resume the build starting at the failed module. Maven refers to this as "resuming from" and is specified by adding "-rf :<module>" to your previous command. For example, if one of the integration tests in the "modeshape-jcr" module failed during a complete build (e.g., using "mvn -Passembly install"), you can resume the build with the following command:

$ mvn -Passembly clean install -rf :modeshape-jcr

Also, several of ModeShape's tests also verify that clustering works properly using a simple, default clustering configuration that isn't always appropriate for all networks. This will usually result first in a failure in one of the tests with "clustering" in the name. It usually can be handled by instructing JGroups (which ModeShape uses for clustering) to prefer either IPv6 or IPv4 addresses.

To do this, simply add either "-DpreferIpv6" or "-DpreferIpv4" to the command line, optionally resuming the build from where where it previously failed or starting over with the full build command below:

$ mvn clean install -s settings.xml -Djava.net.preferIPv4Stack=true

If you have other issues with the build, please contact us on IRC or post a question in our forum.