 ------
 Usage
 ------
 Bernd Mau, mau@hhla.de
 ------
 28 October 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

Maven Eclipse Plugin: Usage

 This mini guide explains howto use Maven in Eclipse IDE.

 * {{{Maven_repository}Maven repository}}

 * {{{Maven_as_an_external_tool}Maven as an external tool}}

 * {{{Simple_Project}Simple Project}}

 * {{{Project_with_Dependencies}Project with Dependencies}}

 * {{{Multiple_Module_Projects}Multiple Module Projects}}

 * {{{Eclipse_PDE_Projects}Eclipse PDE Projects}}

* Maven repository

 Eclipse needs to know the path to the local maven repository. Therefore the
 classpath variable <M2_REPO> has to be set. Execute the following command:

+----+
mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo
+----+

 You can also define a new classpath variable inside Eclipse: From the menu
 bar, select Window > Preferences. Select the Java > Build Path > Classpath
 Variables page.

* Maven as an external tool

 You might want to execute some maven goals from inside Eclipse. This is
 possible by configuring an external launcher.

 It is best practice to prepare Eclipse by adding a variable, which points to
 your local maven excutable (mvn.bat/mvn).

 From the menu bar, select Window > Preferences. Select the Run/Debug > String
 Substitution. Add a new variable e.g. <maven_exec>.

 When you set up a new external launcher (from the menu bar, select Run >
 External Tools. Select Program) you can refer to <maven_exec> in the location
 field.

 Furthermore refer to <project_loc> as the working directory and specify the
 maven goals of your choice as arguments, e.g. <eclipse:eclipse>.

 For further information please refer to the Eclipse help.


* Simple Project

 If you have a simple java project which is made up of only one module, using
 Eclipse is very simple. To generate the Eclipse project files from your POM
 you execute the following command:

+----+
mvn eclipse:eclipse
+----+

 If you have created or checked out the project with Eclipse, you only have to
 refresh the project in your workspace. Otherwise you have to import the
 project into your Eclipse workspace (From the menu bar, select File > Import >
 Existing Projects into Workspace). In the latter case the project (directory)
 should not be located in your workspace, because Eclipse might come into
 trouble, especially if you want to use Eclipse as the scm client.

* Project with Dependencies

 If your maven project has dependencies, the eclipse classpath will be
 synchronised with the current list of maven dependencies, as well as
 any transitive maven dependencies.

 After making changes to your maven dependencies inside the pom file,
 rerun <eclipse:eclipse> and refresh your eclipse workspace for the
 new dependencies to take effect.

* Multiple Module Projects

 If your maven project consists of a number of aggregated projects with
 a common root pom, and if some of these aggregated projects depend on
 each other, the <eclipse:eclipse> goal will configure each dependent
 project in eclipse as an eclipse project dependency, rather than an
 eclipse jar dependency.

 By doing this, changes to code within project A will be available immediately
 to project B, assuming that project B defines a dependency on project A.

 For further details, see {{{./reactor.html}Multiple Module Projects}}.

* Eclipse PDE Projects

 This plugin is capable of creating and / or synchronising an Eclipse
 Plugin Development Environment project.

 For further details, see the configuration instructions
 {{{./pde.html}here}}.

