-----
 Guide to Moving From Maven 1.x to Maven 2.x
 ---
 Jay H. Hartley
 -----
 2008-01-01
 -----

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

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
 {{{http://blogs.codehaus.org/people/vmassol/archives/001170_javazone_2005.html}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 {{{http://maven.apache.org/xsd/maven-v3_0_0.xsd}Version 3}} to
 {{{http://maven.apache.org/xsd/maven-4.0.0.xsd}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 {{{http://maven.apache.org/plugins/maven-one-plugin/}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
 {{{../introduction/introduction-to-the-pom.html}POM Guide}}.

* build.properties and project.properties

 These files have been replaced with
 {{{../../settings.html}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
 {{{../introduction/introduction-to-profiles.html}profiles}}.

* What to do with maven.xml?

 See {{{../../maven1.html#m1-maven-xml}How do I write custom scripts without a maven.xml file?}} for an explanation of
 why maven.xml was discarded, and
 {{{../introduction/introduction-to-plugins.html}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
 {{{../introduction/introduction-to-the-standard-directory-layout.html}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/introduction-to-the-lifecycle.html}Introduction to the Build Lifecycle}}
 for more on how plugins relate.

** Re-use Ant Tasks

 See the {{{../../general.html#using-ant-tasks}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
  {{{../plugin/guide-java-plugin-development.html}Mojos}}.

** Utilize built-in Maven 2 capabilities

*** Resource filtering to inject POM variables into application

 You can turn on {{{../getting-started/index.html#How_do_I_filter_resource_files}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

 * {{{http://maven.apache.org/plugins/maven-one-plugin/}Maven 2 One Plugin}}

 * {{{https://svn.apache.org/repos/asf/maven/sandbox/trunk/other/m1-m2/maven1+project+to+maven2+pom.xsl}XSLT}} from {{{http://jira.codehaus.org/browse/MNG-2337}MNG-2337}}

 * {{{http://www.nabble.com/using-preGoal-and-postGoal-in-m2--td1151533s177.html}using preGoal and postGoal in m2?}} Thread.

 []