----------
 Usage
 ----------
 Brett Porter
 ----------
 1 November 2005
 ----------

~~ 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

Usage

* Maven 1 to Maven 2 conversion

  If you are moving a project from Maven 1 to Maven 2, you can get some help
  from the Maven One plugin. It can convert your project's <<<project.xml>>>
  and <<<project.properties>>> into a <<<pom.xml>>>. To do this, change to the
  directory where your <<<project.xml>>> file is located and issue this command
  on the command line:

-------
mvn one:convert
-------

  This goal uses
  {{{http://maven.apache.org/ref/current/maven-model-converter/}maven-model-converter}}
  which not only converts your project model, it also has <relocators> for many
  plugins and <converters> for their configurations. So if you had some
  configuration properties for the Maven 1 jar-plugin, a converter will try
  to create a suitable configuration section for the Maven 2 jar-plugin inside
  your new <<<pom.xml>>>. You need to review the versions for the plugins in
  <<<pom.xml>>> after it has been created, as the versions might not be the
  same as for the Maven 1 plugins.

* Maven 1.x Plugin Packaging

  To package a Maven 1.x plugin using Maven 2.x, you need to include the Maven
  One plugin in the build section and use a <<<packaging>>> of
  <<<maven-one-plugin>>>. Like this:

-------
<project>
  ...
  <packaging>maven-one-plugin</packaging>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-one-plugin</artifactId>
        <version>${project.version}</version>
        <extensions>true</extensions>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>
-------

* Maven 1.x Local Repository Installation

  To have your artifact installed into a local Maven 1.x repository, you add a
  lifecycle binding to your POM using <<<\<executions\>>>>:

-------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-one-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <goals>
              <goal>install-maven-one-repository</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>
-------

  <<Note:>> The plugin section can be shared with the one above in the case of
  building a Maven 1.x plugin.

  This will read the local repository location from <<<~/build.properties>>>,
  defaulting to <<<~/.maven/repository>>>.

* Maven 1.x Remote Repository Deployment

  To have your artifact deployed into an additional remote Maven 1.x repository,
  you need to add a lifecycle binding to your POM. This configuration will
  deploy your artifact to the Maven 1.x repository at Apache:

-------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-one-plugin</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <configuration>
              <remoteRepositoryUrl>scp://people.apache.org/repository</remoteRepositoryUrl>
            </configuration>
            <goals>
              <goal>deploy-maven-one-repository</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>
-------

  This will not read any settings from the Maven 1.x properties, so the URL is
  required.

  If you configure server settings in your <<<settings.xml>>> file, use the ID
  of <<<mavenOneRemoteRepository>>>. This can be overridden using the
  <<<remoteRepositoryId>>> configuration element.

  For more information, see the {{{./plugin-info.html} Goal Reference}}.