This page last changed on Sep 28, 2006 by tcarlson.

As of Mule 1.3-rc5, the official project build is performed by Maven 2.x For instructions on building with Maven 1.x, see Working with the build (Maven 1.x)

Maven 2.x

Maven 2.x has some pretty interesting and innovative concepts. Read all about it

Documentation has not historically been one of Maven's strong points, but with the creation of Mergere this has been improving.

If you are already familiar with Maven 1.x take a look at Information for Maven 1.0 Users

Useful quick reference:

Modules

The Mule project is neatly organized into a hierarchy of sub-projects or "modules". Each module generally produces one artifact (usually a jar file). Modules are built by executing goals/targets such as "compile", "test", "install", etc.

Executing a Maven goal for a module will also (by default) execute the goal for any modules below it in the hierarchy. This makes it easy to work with portions of the project at a time (providers, extras, tests, etc.) without having to rebuild the entire project. In fact, a single module (or group of modules) can be checked-out from source control, modified, and built on its own without even needing the rest of the project!

Goals

Common goals to execute for a module are:

mvn clean - purges any built artifacts or intermediate files (.class, etc.) from the target directory ("target" by default)
mvn test - runs any unit tests for this module
mvn install - installs the artifact to your local repository (~/.m2/repository by default)
mvn deploy - installs the artifact to a remote repository (used for uploading snapshots or releases)
Implicit goals

You will find that some goals such as mvn compile and mvn package aren't used very often because they are run implicitly by mvn test and mvn install respectively.

See Introduction to the Build Lifecycle for more info.

Tests

Unit Tests

All unit tests for each module are run by default for each build. This can take a long time, depending on the module. If you wish to skip the unit tests, you can set the -Dmaven.test.skip=true parameter:

mvn -Dmaven.test.skip=true install

Integration Tests

In addition to the unit tests for each module, the Mule project has a separate module containing integration tests. These tests verify "macroscopic" functionality which could not be tested by any single module alone.

Vendor Tests

In addition to the unit and integation tests, there is a separate module containing "vendor" tests. These tests can only be run if a certain 3rd-party resource (database, application server, EIS, etc.) is present.

Vendor tests are generally disabled by default. They may be run by either building the module from its own directory (i.e., not from Mule's top-level directory) or by enabling the corresponding profile (e.g., oracle, sap, tibco) as explained in the section Profiles, below.

Distributions

All distributions and distribution-related resources are located in the distributions module.

For performance's sake, the distributions are not built from the project's top-level directory by default. You may either build a distribution from its own directory or by enabling the distributions profile as explained in the section Profiles, below.

A brief description of each distribution follows:

Full stand-alone server (distributions/server/full)

Packages Mule as a stand-alone server application. Includes all providers and extras and all dependencies. Includes the Java Service Wrapper for starting/stopping/restarting Mule from the native OS. heavy-weight

Custom stand-alone server (distributions/server/custom)

Same as the Full stand-alone server but does not include any dependencies. If the user's project is based on Maven 2, it can easily provide the exact libraries it depends on thanks to m2's intelligent resolution of transitive dependencies. light-weight

JCA Resource adapter (distributions/jca)

Packages Mule as a JCA-compatible Resource Adapter for deployment into a J2EE application server. Includes all providers and extras and all dependencies. heavy-weight

Embedded / Composite jar file (distributions/embedded)

Builds a single jar file containing all Mule classes (including all providers and extras). This is useful for embedding Mule into another application or for using Mule with a non-Maven based build. Note that the user is responsible for providing any needed Mule dependencies. light-weight

Extras (distributions/extras)

Includes all the non-essentials: User's Guide (exported from Confluence), Samples, API (Javadocs), Tools, IDE. New users are recommended to download this in addition to the full distribution, whereas advanced users may not need/want it. light-weight

Settings

One of the principal objectives of Maven is to centralize all information necessary for building a module in a single project file. However there are a few settings (such as authentication, firewalls, active profiles, etc.) which may be host-specific or user-specific. These settings are stored in a separate file.

Project settings

Default settings for the project (or module) are stored in a settings.xml file alongside the project's (or module)'s pom.xml.

User settings

User-specific settings are stored in a settings.xml file in the user's local m2 directory. User-specific settings will override the project defaults.

The top level directory of the Mule project contains a template for creating your user-specific settings. Copy and rename the file local_settings.xml to your local m2 directory (~/.m2/settings.xml by default).

Profiles

Profiles are used to enable/disable certain parts of the build, depending on whether the profile is set. (It is sort of like setting a conditional compiler directive in C++)

Your active profiles are determined by (in order of priority):

  1. the command line
  2. your user-specific settings
  3. the project default settings

Command line

In order to enable ("activate") the profile distributions from the command line:

mvn -Ddistributions=true install

In order to disable ("deactivate") the profile tests from the command line:

mvn -Dtests=false install
Workaround

The standard Maven way of activating profiles from the command line is mvn -Pfoo,bar
However, there's AFAIK no standard Maven way of deactivating profiles from the command line, so we use the workaround mvn -Dfoo=true -Dbar=false for now.

Settings file

In order to permanently enable ("activate") the profile distributions in your project or user-specific settings.xml file, add the following:

<activeProfiles>
  <activeProfile>distributions</activeProfile>
</activeProfiles>

Repositories

A Maven repository ("repo") is a directory containing artifacts. The artifacts are usually Java libraries (jars) and meta-data (poms), but they could also be Maven plug-ins, source code bundles, javadocs, zips, pretty much anything. There is a very strict format to follow when adding an artifact to the repository, so don't try it by hand unless you know what you're doing. See Introduction to Repositories for more info.

Local repository

Each user has a local repository, created the first time Maven is run (~/.m2/repository by default) This is where artifacts produced by mvn install will be placed.

Snapshots repository

Snapshots of artifacts are published to http://snapshots.repository.codehaus.org. This is where artifacts produced by mvn deploy will be placed.

Release repository

Releases of artifacts are published to http://repository.codehaus.org. This is where artifacts produced by mvn -DperformRelease=true deploy will be placed.

Dependencies repository

An ad-hoc repository at http://dist.codehaus.org/mule/dependencies contains libraries which, for one reason or another, are not available for download from one of the major Maven repositories.

The procedure for uploading a new library to this repository is as follows:
TO DO
(I think this can be done with mvn deploy-file via WebDAV_)_
Disclaimer

Please read the disclaimer regarding the use of these libraries.

Troubleshooting and other Tips

OutOfMemoryError

If you are getting OutOfMemoryError exceptions when attempting a full build of Mule you may try increasing the max heap and the PermGen space sizes. Either export a MAVEN_OPTS variable in your shell or add it to the original mvn script. The following settings were confirmed working fine with Mule:

MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=256m
Offline option

If you know your downloads are up-to-date, you can use the offline option which may speed up your build considerably depending on network latency:

mvn -o
Debug option

Transitive dependencies in m2 are both a blessing and a curse. The debug option is especially helpful when you find yourself in "classloader hell" (conflicting library versions or unwanted libraries are in your classpath). Among other things, it prints out the effective classpath in a tree format which makes it easy to see where each libraries is coming from.

mvn -X
Non-recursive option

Executing a Maven goal for a module will by default execute the goal for any modules below it in the hierarchy. If you specifically wish to run the goal for this module only (and not its children) you can use the non-recursive option.

mvn -N

Glossary


module, sub-project - A unit of organization within the source code. Each module will generally produce one artifact. For more information read the Modules section above.


artifact - Something produced by a module, for example : a jar, pom, rar, war, zip, tar.gz


pom.xml, POM, project file - This file is present in each module and defines all information necessary for building the module (equivalent to project.xml for Maven 1.x or build.xml for Ant)


goal, target - A task to be executed by Maven, for example, "mvn clean", "mvn install", "mvn deploy" For more information read the Goals section above.


settings.xml - This file defines settings and parameters for the build. For more information read the Settings section above.


local m2 directory - A directory where user-specific settings are kept (~/.m2 by default). Also the default location for the user's local repository.


profile - Used to enable/disable certain parts of the build. For more information read the Profiles section above.


repository, repo - A directory containing Java libraries (jars), metadata (poms), and other artifacts. For more information read the Repositories section above.


snapshot - A development (i.e., "bleeding-edge") version of an artifact. Snapshots will usually indicate their nature (e.g., 1.3-rc2-SNAPSHOT) but have no source control tag associated with them and therefore are not reproducible like a released version is.


release - An official, reproducible version of an artifact (e.g., 1.3-rc2). The version coincides with a source control tag of the same name so that one can easily determine which changes were/were not in that version.

Document generated by Confluence on Oct 03, 2006 09:23