src/site/apt/guides/mini/guide-m1-m2.apt

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

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

 This document is intended to be continously 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.

 []