Multi-Module Maven Projects

External

• Guide to Working with Multiple Modules https://maven.apache.org/guides/mini/guide-multiple-modules.html
• A multi-module project http://books.sonatype.com/mvnex-book/reference/multimodule.html

Internal

• Maven Concepts

Overview

For guidelines on when it is appropriate to use modules, and when separate projects, see "When We Should Use Modules ?" section.

When We Should Use Modules?

Two major benefits of a multi-module project are that all the parts can be built with a single command, and Maven handles the correct build order.

Modules and Versions

Different modules of the same project can have different versions.

In case all modules evolve keeping maintaining their versions in lockstep, that version is specified in the parent POM.

if the version of the modules evolve independently, this can be made clear by specifying the parent POM version to be 0.

POM Structure

The Parent POM

A multi-module project is defined by a parent POM referencing one or more submodules. The essential elements are the packaging, which is of type "pom", and the list of modules.

<project>
    ...
    <groupId>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>

    <packaging>pom</packaging>

    ...
    <modules>
        <module>module1</module>
        <module>module2</module>
    </modules>
    ...
</project>

The "pom" packaging indicates that the single purpose of this (top-level) project is to provide a container Project Object Model.

The group ID will be shared with the modules.

The artifact ID does not really matter. We conventionally use the "maven-root" value.

For considerations on the version, see "Modules and Versions" section.

Each <module> element corresponds to a subdirectory of the top level project directory. Maven will look into these subdirectories for pom.xml files, and it will add the modules to the list of Maven projects included in a build. Each module will have its own independent source hierarchy.

The rest of the parent POM includes settings to be inherited by all modules. This is where common plug-ins and dependencies should be declared.

Organizatorium

• The modules do not need to specify their <groupId>, as it is inherited from their parent, and thus redundant.