Multi Module
************

Links
=====

- `How do I build more than one project at once?`_
- `Maven 2 Notes, Part 6: Multiproject Builds`_
- `Explain multi-module support in M2`_
- `Eclipse and Maven Multiple Module Projects`_

Sample
======

sample-multi-module_

Imagine a sample project with this folder structure:

::

  ./pom.xml
  ./module-a/pom.xml
  ./module-b/pom.xml

Parent
------

The parent ``pom.xml`` file will look like this:

::

  <project>
      <modelVersion>4.0.0</modelVersion>
      <groupId>com.sample</groupId>
      <version>1.0-SNAPSHOT</version>
      <artifactId>parent-app</artifactId>
      <packaging>pom</packaging>
      <name>Parent App</name>
      <modules>
          <module>module-a</module>
          <module>module-b</module>
      </modules>
  </project>

Module
------

The module ``pom.xml`` files, ``module-a`` and ``module-b`` are virtually the
same.  They will only differ with the ``artifactId``, ``packaging`` and
``name``

::

  <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <parent>
      <groupId>com.mycompany</groupId>
      <artifactId>parent-app</artifactId>
      <version>1.0-SNAPSHOT</version>
    </parent>

    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mycompany</groupId>
    <artifactId>module-a</artifactId>
    ...

**Note:**

- It is important to identify the ``parent`` from each of the modules.
- If you use ``mvn eclipse:eclipse`` it looks like you need to import each
  module into Eclipse separately.
- If you don't specify the ``version`` in the module, it appears to inherit the
  version of the parent (which is probably what you want).

  **Note**: If your module does specify a version, the project files generated by
  the Eclipse plugin might refer to ``jar`` files in the Maven repository rather
  than the project.

- If you use ``archetype:create`` it will set-up the ``pom.xml`` files
  correctly.
- For the release plugin, :doc:`mvn-plugin-release`, the ``scm``,
  ``connection`` only needs to be specified in the parent pom.

Dependencies
------------

The parent ``pom.xml`` file can use the ``dependencyManagement`` tag to
specify versions of dependencies which can be used in the modules:

::

    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>commons-dbcp</groupId>
          <artifactId>commons-dbcp</artifactId>
          <version>1.2.1</version>
        </dependency>
        <dependency>
          <groupId>commons-dbutils</groupId>
          <artifactId>commons-dbutils</artifactId>
          <version>1.0</version>
        </dependency>
      </dependencies>
    </dependencyManagement>

The ``dependencies`` tag in the module ``pom.xml`` file will inherit the
version of the artifact from the parent:

::

    <dependencies>
      <dependency>
        <groupId>commons-dbcp</groupId>
        <artifactId>commons-dbcp</artifactId>
        <scope>test</scope>
      </dependency>
      <dependency>
        <groupId>commons-dbutils</groupId>
        <artifactId>commons-dbutils</artifactId>
      </dependency>
    </dependencies>

Note: The ``scope`` can be changed in the module.

To add a dependency to one of the other modules in the project:

::

    <dependencies>
      <dependency>
        <groupId>com.sample</groupId>
        <artifactId>module-b</artifactId>
        <version>${project.version}</version>
      </dependency>

- This is the configuration to use if you want to release all modules with the
  same version number.  Releasing all modules with the same version number will
  make it much simple to identify the version number of deployed jar files.  In
  any case, the release plugin increments the version number for every module
  in the project even if no changes have been committed.
- If you do want a different version number for a module the release plugin,
  :doc:`mvn-plugin-release`, will automatically update the version number in
  the module and the ``dependencyManagement`` section of the parent pom e.g.

  ::

    <version>5.3-SNAPSHOT</version>

- Also see
  `Maven best practices: Use dependency management for multi module projects`_.

Effective pom
=============

To view the effective pom.xml file for a project:

::

  mvn help:effective-pom

POM Dependency
==============

...declare a pom as a dependency, so that its dependencies would be inherited...

`POM Inheritance`_

::

  JDBC POM:

  <project>
    ...
    <artifactId>my-jdbc-project</artifactId>
    <packaging>pom</packaging>
    <dependencies>
      ... add jdbc dependencies here, like mysql jdbc, or sqlserver jdbc ...
    </dependencies>
  </project>

  Then, in your project that needs to use the jdbc drivers:

    <dependencies>
      <dependency>
        <groupId>...</groupId>
        <artifactId>my-jdbc-project</artifactId>
        <version>...</version>
        <type>pom</type>
      </dependency>
      ....

Site
====

- :doc:`mvn-plugin-site-multi-module`


.. _`How do I build more than one project at once?`: http://maven.apache.org/guides/getting-started/index.html#How%20do%20I%20build%20more%20than%20one%20project%20at%20once?
.. _`Maven 2 Notes, Part 6: Multiproject Builds`: http://communitygrids.blogspot.com/2006/02/maven-2-notes-part-6-multiproject_06.html
.. _`Explain multi-module support in M2`: http://www.mail-archive.com/users@maven.apache.org/msg41444.html
.. _`Eclipse and Maven Multiple Module Projects`: http://maven.apache.org/plugins/maven-eclipse-plugin/reactor.html
.. _sample-multi-module: http://toybox/hg/sample/file/tip/java/maven/sample-multi-module
.. _`Maven best practices: Use dependency management for multi module projects`: http://www.bhaskarvk.info/content/maven/dependency_management.html
.. _`POM Inheritance`: http://www.nabble.com/POM-Inheritance-tf3304518s177.html#a9234650