Guide to Moving from Maven 1.x to Maven 2.x

This document is intended to be continuously updated from the mail list archives. For an only slightly out-of-date reference with concrete examples, check out Vincent Massol's JavaZone2005 presentation.

Parallel Builds

It is possible to establish parallel Maven builds, one using the old M1 settings, and a second using M2. The Maven 2 configuration file names and uses have been modified, so the two builds should not conflict.

A Maven 1.x build is configured with the following files:

  • [project.xml] Project Object Model (POM) definition
  • [maven.xml] Custom build scripts
  • [project.properties] general build settings
  • [build.properties] local build settings

    A Maven 2 build is configured with a different file set:

  • [pom.xml] POM definition
  • [settings.xml] local configuration

Migrating the POM

The Project Object Model (POM) has moved from the project.xml file to pom.xml. The XML schema has also changed, from Version 3 to Version 4.

The new POM is nominally a superset of the old, so the first step in creating a pom.xml is to copy over project.xml. Then start tweaking. There are several new elements that can be added to a POM, but all are optional so should not cause a problem with an initial build.

If you want some help converting your project.xml into a pom.xml you can use the maven-one-plugin. If you run the following command, it will convert your project.xml into a pom.xml:

mvn one:convert

project.xml:

<project>
  <pomVersion>3</pomVersion>
  <id>util</id>
  <name>Generic utility code</name>
  <groupId>project</groupId>
  <currentVersion>1.1</currentVersion>
  <package>org.apache.project.util</package>
  <dependencies>
    ...
  </dependencies>
  <build>
    ...
  </build>
  ...
</project>

pom.xml:

<project>
  <modelVersion>4.0.0</modelVersion>
  <artifactId>util</artifactId>
  <name>Generic Utility Code</name>
  <groupId>org.apache.project.util</groupId>
  <version>1.1</version>
  <packaging>jar</packaging>
  <dependencies>
  ...
  </dependencies>
  <build>
  ...
  </build>
  ...
</project>

For more details, check out the POM Guide.

build.properties and project.properties

These files have been replaced with settings.xml. Like with the POM, you can establish a parallel build environment, so the m1 build never breaks while the m2 build is being debugged.

Additional local build customization options can also be created using profiles.

What to do with maven.xml?

See How do I write custom scripts without a maven.xml file? for an explanation of why maven.xml was discarded, and Introduction to Maven 2.0 Plugin Development for a guide to writing your own plug-ins.

Directory Structure

The POM allows customization of the directory structure in both Maven 1 and Maven 2 using the <build> tag. For simplicity, it would be ideal to move source to the Maven 2 default structure, but it is not required. You can begin by customizing the directories in Maven 2, then when satisfied that both build paths are working, move to the Maven 2 structure and customize the settings in Maven 1.

Migrating Plug-ins

The main conceptual change in plugins and their use has to do with the concept of a build cycle in Maven 2. Instead of using preGoal and postGoal tags in maven.xml to tie plugin goals into the build process, the goals of a plugin are associated with the pre-defined stages of the build cycle. See the Introduction to the Build Lifecycle for more on how plugins relate.

Re-use Ant Tasks

See the Ant Script FAQ.

Replace scripts with Mojos

The new plugin architecture does not specify a specific language implementation, so Jelly scripts and other such artifacts should be re-usable with wrappers. It is recommended that you look into moving to Mojos.

Utilize built-in Maven 2 capabilities

Resource filtering to inject POM variables into application

You can turn on resource filtering in your POM. Tokens of the form ${pom.variable} in resource files will be replaced with the corresponding POM property.

<project>
  ...
  <build>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
      </resource>
    </resources>
  </build>
</project>
Multiproject Builds

The old reactor+multiproject plugin combination was established more as an afterthought of the core development. In Maven 2, multiproject support is included in the core, so any scripts required in the past to work around problems with the multiproject plugin should be unnecessary.

Migrating repositories

Every four hours the Maven 1.x repository is converted over to a Maven 2.x repository and we plan to release a plug-in based on our conversion tool but currently.

Related links