You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by bu...@apache.org on 2012/03/02 00:09:05 UTC
svn commit: r806981 [26/46] - in /websites/staging/maventest/trunk/content:
./ ant/ background/ css/ developers/ developers/conventions/
developers/release/ developers/website/ docs/ docs/2.0.1/ docs/2.0.10/
docs/2.0.11/ docs/2.0.2/ docs/2.0.3/ docs/2....
Added: websites/staging/maventest/trunk/content/guides/mini/guide-configuring-plugins.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/mini/guide-configuring-plugins.html (added)
+++ websites/staging/maventest/trunk/content/guides/mini/guide-configuring-plugins.html Thu Mar 1 23:08:58 2012
@@ -0,0 +1,585 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Guide to Configuring Plug-ins</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl
+Vincent Siveton" />
+ <meta name="Date-Creation-yyyymmdd" content="20090826" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Guide to Configuring Plug-ins
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- 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/referen
ces/apt-format.html --><div class="section"><h2>Guide to Configuring Plug-ins<a name="Guide_to_Configuring_Plug-ins"></a></h2><ol style="list-style-type: decimal"><li><a href="#Generic_Configuration">Generic Configuration</a><ol style="list-style-type: decimal"><li><a href="#Help_Goal">Help Goal</a></li><li><a href="#Configuring_Parameters">Configuring Parameters</a><ol style="list-style-type: decimal"><li><a href="#Mapping_Simple_Objects">Mapping Simple Objects</a></li><li><a href="#Mapping_Complex_Objects">Mapping Complex Objects</a></li><li><a href="#Mapping_Collections">Mapping Collections</a><ol style="list-style-type: decimal"><li><a href="#Mapping_Lists">Mapping Lists</a></li><li><a href="#Mapping_Maps">Mapping Maps</a></li><li><a href="#Mapping_Properties">Mapping Properties</a></li></ol></li></ol></li></ol></li><li><a href="#Configuring_Build_Plugins">Configuring Build Plugins</a><ol style="list-style-type: decimal"><li><a href="#Using_the_executions_Tag">Using the
<tt><executions></tt> Tag</a></li><li><a href="#Using_the_dependencies_Tag">Using the <tt><dependencies></tt> Tag</a></li><li><a href="#Using_the_inherited_Tag_In_Build_Plugins">Using the <tt><inherited></tt> Tag In Build Plugins</a></li></ol></li><li><a href="#Configuring_Reporting_Plugins">Configuring Reporting Plugins</a><ol style="list-style-type: decimal"><li><a href="#Using_the_reporting_Tag_VS_build_Tag">Using the <tt><reporting></tt> Tag VS <tt><build></tt> Tag</a></li><li><a href="#Using_the_reportSets_Tag">Using the <tt><reportSets></tt> Tag</a></li><li><a href="#Using_the_inherited_Tag_In_Reporting_Plugins">Using the <tt><inherited></tt> Tag In Reporting Plugins</a></li></ol></li></ol><div class="section"><h3>Introduction<a name="Introduction"></a></h3><p>In Maven, there are the build and the reporting plugins:</p><ul><li><b>Build plugins</b> will be executed during the build and then, they should be configured in the <tt>
<build/></tt> element.</li><li><b>Reporting plugins</b> will be executed during the site generation and they should be configured in the <tt><reporting/></tt> element.</li></ul><p>All plugins should have minimal required <a class="externalLink" href="http://maven.apache.org/ref/current/maven-model/maven.html#class_plugin">informations</a>: <tt>groupId</tt>, <tt>artifactId</tt> and <tt>version</tt>.</p><p><b>Important Note</b>: It is recommended to always defined each version of the plugins used by the build to guarantee the build reproducibility. A good practice is to specify them in the <tt><build><pluginManagement/></build></tt> elements for <b>each</b> build plugins (generally, you will define a <pluginManagement/> element in a parent POM). For reporting plugins, you should specify each version in the <tt><reporting><plugins/></reporting></tt> elements (and surely in the <tt><build><pluginManagement/></b
uild></tt> elements too).</p></div><div class="section"><h3><a name="Generic_Configuration">Generic Configuration</a></h3><p>Maven plugins (build and reporting) are configured by specifying a <tt><configuration/></tt> element where the child elements of the <tt><configuration/></tt> element are mapped to fields, or setters, inside your Mojo (remember that a plug-in consists of one or more Mojos where a Mojo maps to a goal). Say, for example, we had a Mojo that performed a query against a particular URL, with a specified timeout and list of options. The Mojo might look like the following:</p><div class="source"><pre>/**
+ * @goal query
+ */
+public class MyQueryMojo
+ extends AbstractMojo
+{
+ /**
+ * @parameter expression="${query.url}"
+ */
+ private String url;
+
+ /**
+ * @parameter default-value="60"
+ */
+ private int timeout;
+
+ /**
+ * @parameter
+ */
+ private String[] options;
+
+ public void execute()
+ throws MojoExecutionException
+ {
+ ...
+ }
+}</pre></div><p>To configure the Mojo from your POM with the desired URL, timeout and options you might have something like the following:</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-myquery-plugin</artifactId>
+ <version>1.0</version>
+ <configuration>
+ <url>http://www.foobar.com/query</url>
+ <timeout>10</timeout>
+ <options>
+ <option>one</option>
+ <option>two</option>
+ <option>three</option>
+ </options>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div><p>As you can see the elements in the configuration match the names of the fields in the Mojo. The configuration mechanism Maven employs is very similar to the way <a class="externalLink" href="http://xstream.codehaus.org">XStream</a> works where elements in XML are mapped to objects. So from the example above you can see that the mapping is pretty straight forward the <tt>url</tt> element maps to the <tt>url</tt> field, the <tt>timeout</tt> element maps to the <tt>timeout</tt> field and the <tt>options</tt> element maps to the <tt>options</tt> field. The mapping mechanism can deal with arrays by inspecting the type of the field and determining if a suitable mapping is possible.</p><p>For mojos that are intended to be executed directly from the CLI, their parameters usually provide a means to be configured via system properties instead of a <tt><configuration/></tt> section in the POM. The plugin documentation for those parameters will list
an <i>expression</i> that denotes the system properties for the configuration. In the mojo above, the parameter <tt>url</tt> is associated with the expression <tt>${query.url}</tt>, meaning its value can be specified by the system property <tt>query.url</tt> as shown below:</p><div class="source"><pre>mvn myquery:query -Dquery.url=http://maven.apache.org</pre></div><p>Note that the name of the system property does not necessarily match the name of the mojo parameter. While this is a rather common practice, you will often notice plugins that employ some prefix for the system properties to avoid name clashes with other system properties. Though rarely, there are also plugin parameters that (e.g. for historical reasons) employ system properties which are completely unrelated to the parameter name. So be sure to have a close look at the plugin documentation.</p><div class="section"><h4><a name="Help_Goal">Help Goal</a></h4><p>Recent Maven plugins have generally an <tt>help</tt>
goal to have in the command line the description of the plugin, with their parameters and types. For instance, to understand the javadoc goal, you need to call:</p><div class="source"><pre>mvn javadoc:help -Ddetail -Dgoal=javadoc</pre></div><p>And you will see all parameters for the javadoc:javadoc goal, similar to this <a class="externalLink" href="http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html">page</a>.</p></div><div class="section"><h4><a name="Configuring_Parameters">Configuring Parameters</a></h4><div class="section"><h5><a name="Mapping_Simple_Objects">Mapping Simple Objects</a></h5><p>Mapping simple types, like Boolean or Integer, is very simple. The <tt><configuration/></tt> element might look like the following:</p><div class="source"><pre>...
+<configuration>
+ <myString>a string</myString>
+ <myBoolean>true</myBoolean>
+ <myInteger>10</myInteger>
+ <myDouble>1.0</myDouble>
+ <myFile>c:\temp</myFile>
+ <myURL>http://maven.apache.org</myURL>
+</configuration>
+...</pre></div></div><div class="section"><h5><a name="Mapping_Complex_Objects">Mapping Complex Objects</a></h5><p>Mapping complex types is also fairly straight forward in Maven so let's look at a simple example where we are trying to map a configuration for Person object. The <tt><configuration/></tt> element might look like the following:</p><div class="source"><pre>...
+<configuration>
+ <person>
+ <firstName>Jason</firstName>
+ <lastName>van Zyl</lastName>
+ </person>
+</configuration>
+...</pre></div><p>The rules for mapping complex objects are as follows:</p><ul><li>There must be a private field that corresponds to name of the element being mapped. So in our case the <tt>person</tt> element must map to a <tt>person</tt> field in the mojo.</li><li>The object instantiated must be in the same package as the Mojo itself. So if your mojo is in <tt>com.mycompany.mojo.query</tt> then the mapping mechanism will look in that package for an object named <tt>Person</tt>. As you can see the mechanism will capitalize the first letter of the element name and use that to search for the object to instantiate.</li><li>If you wish to have the object to be instantiated live in a different package or have a more complicated name then you must specify this using an <tt>implementation</tt> attribute like the following:</li></ul><div class="source"><pre>...
+<configuration>
+ <person implementation="com.mycompany.mojo.query.SuperPerson">
+ <firstName>Jason</firstName>
+ <lastName>van Zyl</lastName>
+ </person>
+</configuration>
+...</pre></div></div><div class="section"><h5><a name="Mapping_Collections">Mapping Collections</a></h5><p>The configuration mapping mechanism can easily deal with most collections so let's go through a few examples to show you how it's done:</p><div class="section"><h6><a name="Mapping_Lists">Mapping Lists</a></h6><p>Mapping lists works in much the same way as mapping to arrays where you a list of elements will be mapped to the List. So if you have a mojo like the following:</p><div class="source"><pre>public class MyAnimalMojo
+ extends AbstractMojo
+{
+ /**
+ * @parameter
+ */
+ private List animals;
+
+ public void execute()
+ throws MojoExecutionException
+ {
+ ...
+ }
+}</pre></div><p>Where you have a field named <tt>animals</tt> then your configuration for the plug-in would look like the following:</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-myanimal-plugin</artifactId>
+ <version>1.0</version>
+ <configuration>
+ <animals>
+ <animal>cat</animal>
+ <animal>dog</animal>
+ <animal>aardvark</animal>
+ </animals>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div><p>Where each of the animals listed would be entries in the <tt>animals</tt> field. Unlike arrays, collections have no specific component type. In order to derive the type of a list item, the following strategy is used:</p><ol style="list-style-type: decimal"><li>If the XML element contains an <tt>implementation</tt> hint attribute, that is used</li><li>If the XML tag contains a <tt>.</tt>, try that as a fully qualified class name</li><li>Try the XML tag (with capitalized first letter) as a class in the same package as the mojo/object being configured</li><li>If the element has no children, assume its type is <tt>String</tt>. Otherwise, the configuration will fail.</li></ol></div><div class="section"><h6><a name="Mapping_Maps">Mapping Maps</a></h6><p>In the same way, you could define maps like the following:</p><div class="source"><pre>...
+ /**
+ * My Map.
+ *
+ * @parameter
+ */
+ private Map myMap;
+...</pre></div><div class="source"><pre>...
+ <configuration>
+ <myMap>
+ <key1>value1</key1>
+ <key2>value2</key2>
+ </myMap>
+ </configuration>
+...</pre></div></div><div class="section"><h6><a name="Mapping_Properties">Mapping Properties</a></h6><p>Properties should be defined like the following:</p><div class="source"><pre>...
+ /**
+ * My Properties.
+ *
+ * @parameter
+ */
+ private Properties myProperties;
+...</pre></div><div class="source"><pre>...
+ <configuration>
+ <myProperties>
+ <property>
+ <name>propertyName1</name>
+ <value>propertyValue1</value>
+ <property>
+ <property>
+ <name>propertyName2</name>
+ <value>propertyValue2</value>
+ <property>
+ </myProperties>
+ </configuration>
+...</pre></div></div></div></div></div><div class="section"><h3><a name="Configuring_Build_Plugins">Configuring Build Plugins</a></h3><p>The following is only to configure Build plugins in the <tt><build/></tt> element.</p><div class="section"><h4><a name="Using_the_executions_Tag">Using the <tt><executions/></tt> Tag</a></h4><p>You can also configure a mojo using the <tt><executions></tt> tag. This is most commonly used for mojos that are intended to participate in some phases of the <a href="../introduction/introduction-to-the-lifecycle.html">build lifecycle</a>. Using <tt>MyQueryMojo</tt> as an example, you may have something that will look like:</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-myquery-plugin</artifactId>
+ <version>1.0</version>
+ <executions>
+ <execution>
+ <id>execution1</id>
+ <phase>test</phase>
+ <configuration>
+ <url>http://www.foo.com/query</url>
+ <timeout>10</timeout>
+ <options>
+ <option>one</option>
+ <option>two</option>
+ <option>three</option>
+ </options>
+ </configuration>
+ <goals>
+ <goal>query</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>execution2</id>
+ <configuration>
+ <url>http://www.bar.com/query</url>
+ <timeout>15</timeout>
+ <options>
+ <option>four</option>
+ <option>five</option>
+ <option>six</option>
+ </options>
+ </configuration>
+ <goals>
+ <goal>query</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div><p>The first execution with id "execution1" binds this configuration to the test phase. The second execution does not have a <tt><phase></tt> tag, how do you think will this execution behave? Well, goals can have a default phase binding as discussed further below. If the goal has a default phase binding then it will execute in that phase. But if the goal is not bound to any lifecycle phase then it simply won't be executed during the build lifecycle.</p><p>Note that while execution id's have to be unique among all executions of a single plugin within a POM, they don't have to be unique across an inheritance hierarchy of POMs. Executions of the same id from different POMs are merged. The same applies to executions that are defined by profiles.</p><p>How about if we have a multiple executions with different phases bound to it? How do you think will it behave? Let us use the example POM above again, but this time we shall bind <tt>exec
ution2</tt> to a phase.</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ ...
+ <executions>
+ <execution>
+ <id>execution1</id>
+ <phase>test</phase>
+ ...
+ </execution>
+ <execution>
+ <id>execution2</id>
+ <phase>install</phase>
+ <configuration>
+ <url>http://www.bar.com/query</url>
+ <timeout>15</timeout>
+ <options>
+ <option>four</option>
+ <option>five</option>
+ <option>six</option>
+ </options>
+ </configuration>
+ <goals>
+ <goal>query</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div><p>If there are multiple executions bound to different phases, then the mojo is executed once for each phase indicated. Meaning, <tt>execution1</tt> will be executed applying the configuration setup when the phase of the build is test, and <tt>execution2</tt> will be executed applying the configuration setup when the build phase is already in install.</p><p>Now, let us have another mojo example which shows a default lifecycle phase binding.</p><div class="source"><pre>/**
+ * @goal query
+ * @phase package
+ */
+public class MyBindedQueryMojo
+ extends AbstractMojo
+{
+ /**
+ * @parameter expression="${query.url}"
+ */
+ private String url;
+
+ /**
+ * @parameter default-value="60"
+ */
+ private int timeout;
+
+ /**
+ * @parameter
+ */
+ private String[] options;
+
+ public void execute()
+ throws MojoExecutionException
+ {
+ ...
+ }
+}</pre></div><p>From the above mojo example, <tt>MyBindedQueryMojo</tt> is by default bound to the package phase (see the <tt>@phase</tt> notation). But if we want to execute this mojo during the install phase and not with package we can rebind this mojo into a new lifecycle phase using the <tt><phase></tt> tag under <tt><execution></tt>.</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <artifactId>maven-myquery-plugin</artifactId>
+ <version>1.0</version>
+ <executions>
+ <execution>
+ <id>execution1</id>
+ <phase>install</phase>
+ <configuration>
+ <url>http://www.bar.com/query</url>
+ <timeout>15</timeout>
+ <options>
+ <option>four</option>
+ <option>five</option>
+ <option>six</option>
+ </options>
+ </configuration>
+ <goals>
+ <goal>query</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div><p>Now, <tt>MyBindedQueryMojo</tt> default phase which is package has been overrided by install phase.</p><p><b>Note:</b> Configurations inside the <tt><executions></tt> tag differ from those that are outside <tt><executions></tt> in that they cannot be used from a direct command line invocation. Instead they are only applied when the lifecycle phase they are bound to are invoked. Alternatively, if you move a configuration section outside of the executions section, it will apply globally to all invocations of the plugin.</p></div><div class="section"><h4><a name="Using_the_dependencies_Tag">Using the <tt><dependencies/></tt> Tag</a></h4><p>You could configure the dependencies of the Build plugins, commonly to use a more recent dependency version.</p><p>For instance, the Maven Antrun Plugin version 1.2 uses Ant version 1.6.5, if you want to use the latest Ant version when running this plugin, you need to add <tt><dependencies/&
gt;</tt> element like the following:</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <version>1.2</version>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant</artifactId>
+ <version>1.7.1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-launcher</artifactId>
+ <version>1.7.1</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div></div><div class="section"><h4><a name="Using_the_inherited_Tag_In_Build_Plugins">Using the <tt><inherited/></tt> Tag In Build Plugins</a></h4><p>By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could uses the <tt><inherited/></tt> tag:</p><div class="source"><pre><project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <version>1.2</version>
+ <inherited>false</inherited>
+ ...
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project></pre></div></div></div><div class="section"><h3><a name="Configuring_Reporting_Plugins">Configuring Reporting Plugins</a></h3><p>The following is only to configure Reporting plugins in the <tt><reporting/></tt> element.</p><div class="section"><h4><a name="Using_the_reporting_Tag_VS_build_Tag">Using the <tt><reporting/></tt> Tag VS <tt><build/></tt> Tag</a></h4><p>Configuring a reporting plugin in the <reporting/> or <build/> elements in the pom have <b>NOT</b> the same behavior!</p><dl><dt><tt>mvn site</tt></dt><dd>It uses <b>only</b> the parameters defined in the <configuration/> element of each reporting Plugin specified in the <reporting/> element, i.e. <tt>site</tt> always <b>ignores</b> the parameters defined in the <configuration/> element of each plugin specified in <build/>.</dd><dt><tt>mvn aplugin:areportgoal</tt></dt><dd>It uses <b>firstly</b> the parameters defined in the <configuration/>
; element of each reporting Plugin specified in the <reporting/> element; if a parameter is not found, it will look up to a parameter defined in the <configuration/> element of each plugin specified in <build/>.</dd></dl></div><div class="section"><h4><a name="Using_the_reportSets_Tag">Using the <tt><reportSets/></tt> Tag</a></h4><p>You can configure a reporting plugin using the <tt><reportSets></tt> tag. This is most commonly used to generate reports selectively when running <tt>mvn site</tt>. The following will generate only the project team report.</p><div class="source"><pre><project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.1.2</version>
+ <reportSets>
+ <reportSet>
+ <reports>
+ <report>project-team</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+</project></pre></div><p><b>Notes</b>:</p><ol style="list-style-type: decimal"><li>To exclude all reports, you need to use:<div class="source"><pre> <reportSets>
+ <reportSet>
+ <reports/>
+ </reportSet>
+ </reportSets></pre></div></li><li>Refer to each Plugin Documentation (i.e. plugin-info.html) to know the available report goals.</li></ol></div><div class="section"><h4><a name="Using_the_inherited_Tag_In_Reporting_Plugins">Using the <tt><inherited/></tt> Tag In Reporting Plugins</a></h4><p>Similar to the build plugins, to break the inheritance, you could uses the <tt><inherited/></tt> tag:</p><div class="source"><pre><project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.1.2</version>
+ <inherited>false</inherited>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+</project></pre></div></div></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maventest/trunk/content/guides/mini/guide-coping-with-sun-jars.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/mini/guide-coping-with-sun-jars.html (added)
+++ websites/staging/maventest/trunk/content/guides/mini/guide-coping-with-sun-jars.html Thu Mar 1 23:08:58 2012
@@ -0,0 +1,250 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Guide to Coping with Sun JARs</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Guide to Coping with Sun JARs
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section"><h2>Coping with Sun JARs<a name="Coping_with_Sun_JARs"></a></h2><p>Often users are confronted with the need to build against JARs provide by Sun like the <a class="externalLink" href="http://java.sun.com/products/javamail/">JavaMail</a> JAR, or the <a class="externalLink" href="http://java.sun.com/products/javabeans/jaf/downloads/index.html">Activation</a> JAR and users have found these JARs not present in central repository resulting in a broken build. Unfortunately most of these artifacts fall under Sun's Binary License which disallows us from distributing them from Ibiblio.</p><p>Another problem is that Sun's appears not to have any sort of convention for naming their own JARs so we have taken steps in suggesting some common names for Sun's artifacts. You can find a list of our suggestions here:</p><table border="1" class="bodyTable"><tr class="a"><td align="left">Product artifact</td><td align="left">Group ID</td><td align="left">Artifact ID<
/td></tr><tr class="b"><td align="left">Java Activation Framework</td><td align="left">javax.activation</td><td align="left">activation</td></tr><tr class="a"><td align="left">J2EE</td><td align="left">javax.j2ee</td><td align="left">j2ee</td></tr><tr class="b"><td align="left">Java Data Object (JDO)</td><td align="left">javax.jdo</td><td align="left">jdo</td></tr><tr class="a"><td align="left">Java Message Service (JMS)</td><td align="left">javax.jms</td><td align="left">jms</td></tr><tr class="b"><td align="left">JavaMail</td><td align="left">javax.mail</td><td align="left">mail</td></tr><tr class="a"><td align="left">Java Persistence API (JPA) / EJB 3</td><td align="left">javax.persistence</td><td align="left">persistence-api</td></tr><tr class="b"><td align="left">J2EE Connector Architecture</td><td align="left">javax.resource</td><td align="left">connector</td></tr><tr class="a"><td align="left">J2EE Connector Architecture API</td><td align="left">javax.resource</td><td
align="left">connector-api</td></tr><tr class="b"><td align="left">Java Authentication and Authorization Service (JAAS)</td><td align="left">javax.security</td><td align="left">jaas</td></tr><tr class="a"><td align="left">Java Authorization Contract for Containers</td><td align="left">javax.security</td><td align="left">jacc</td></tr><tr class="b"><td align="left">Servlet API</td><td align="left">javax.servlet</td><td align="left">servlet-api</td></tr><tr class="a"><td align="left">Servlet JavaServer Pages (JSP)</td><td align="left">javax.servlet</td><td align="left">jsp-api</td></tr><tr class="b"><td align="left">Servlet JavaServer Pages Standard Tag Library (JSTL)</td><td align="left">javax.servlet</td><td align="left">jstl</td></tr><tr class="a"><td align="left">JDBC 2.0 Optional Package</td><td align="left">javax.sql</td><td align="left">jdbc-stdext</td></tr><tr class="b"><td align="left">Java Transaction API (JTA)</td><td align="left">javax.transaction</td><td align="l
eft">jta</td></tr><tr class="a"><td align="left">Java XML RPC</td><td align="left">javax.xml</td><td align="left">jaxrpc</td></tr><tr class="b"><td align="left">Portlet</td><td align="left">javax.portlet</td><td align="left">portlet-api</td></tr><tr class="a"><td align="left">Java Naming and Directory Interface (JNDI)</td><td align="left">javax.naming</td><td align="left">jndi</td></tr></table><p>If you use our suggestions as noted above when adding a Sun dependency to your POM, Maven 2.x can help you locate the JARs by providing the site where they can be retrieved. It is important that you follow the suggested naming conventions as we cannot store the JARs at the central repository. We can only store metadata about those JARs and it is the metadata that contains location and retrieval information.</p><p>Once you have downloaded a particular Sun JAR to your system you can install the JAR in your local repository. Please refer to our <a href="./guide-3rd-party-jars-local.htm
l">Guide to installing 3rd party JARs</a> for instructions on how to accomplish this.</p><p><b>Note</b>: Java.net provides a <a class="externalLink" href="http://download.java.net/maven/2/">Maven 2 repository</a>. You could specify it directly in your POM or in your settings.xml between the tags <repositories>:</p><div><pre>...
+ <repositories>
+ <repository>
+ <id>maven2-repository.dev.java.net</id>
+ <name>Java.net Repository for Maven</name>
+ <url>http://download.java.net/maven/2/</url>
+ <layout>default</layout>
+ </repository>
+ </repositories>
+...</pre></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: websites/staging/maventest/trunk/content/guides/mini/guide-creating-archetypes.html
==============================================================================
--- websites/staging/maventest/trunk/content/guides/mini/guide-creating-archetypes.html (added)
+++ websites/staging/maventest/trunk/content/guides/mini/guide-creating-archetypes.html Thu Mar 1 23:08:58 2012
@@ -0,0 +1,315 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!-- Generated by Apache Maven Doxia at Mar 1, 2012 -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <title>Guide to Creating Archetypes</title>
+ <style type="text/css" media="all">
+ @import url("../../css/maven-base.css");
+ @import url("../../css/maven-theme.css");
+ @import url("../../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Jason van Zyl, Alexander Hars, Franz Allan Valencia See" />
+ <meta name="Date-Creation-yyyymmdd" content="20100410" />
+ <meta name="Date-Revision-yyyymmdd" content="20120301" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
+
+<script type="text/javascript">_uacct = "UA-140879-1";
+ urchinTracker();</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../.././" id="bannerLeft">
+ <img src="../../images/apache-maven-project-2.png" alt="" />
+ </a>
+ <span id="bannerRight">
+ <img src="../../images/maven-logo-2.gif" alt="" />
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+ <div class="xleft">
+ <a href="http://www.apache.org/" class="externalLink">Apache</a>
+ >
+ <a href="../../index.html">Maven</a>
+ >
+ Guide to Creating Archetypes
+ </div>
+ <div class="xright">
+ Last Published: 2012-03-01
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+ <h5>Main</h5>
+ <ul>
+ <li class="none">
+ <a href="../../index.html">Welcome</a>
+ </li>
+ </ul>
+ <h5>Get Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../download.html">Download</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/3.0.4/release-notes.html">Release Notes (3.0.4)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.2.1/release-notes.html">Release Notes (2.2.1)</a>
+ </li>
+ <li class="none">
+ <a href="../../docs/2.0.11/release-notes.html">Release Notes (2.0.11)</a>
+ </li>
+ <li class="none">
+ <a href="../../license.html">License</a>
+ </li>
+ </ul>
+ <h5>IDE Integration</h5>
+ <ul>
+ <li class="none">
+ <a href="../../eclipse-plugin.html">Eclipse</a>
+ </li>
+ <li class="none">
+ <a href="../../netbeans-module.html">NetBeans</a>
+ </li>
+ </ul>
+ <h5>About Maven</h5>
+ <ul>
+ <li class="none">
+ <a href="../../what-is-maven.html">What is Maven?</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-features.html">Features</a>
+ </li>
+ <li class="none">
+ <a href="../../general.html">FAQ (official)</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1" class="externalLink">FAQ (unofficial)</a>
+ </li>
+ <li class="none">
+ <a href="../../powered-by-m2.html">Powered By</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="../../plugins/index.html">Maven Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/index.html">Index (category)</a>
+ </li>
+ <li class="none">
+ <a href="../../run-maven/index.html">Running Maven</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../users/index.html">User Centre</a>
+ </li>
+ <li class="collapsed">
+ <a href="../../plugin-developers/index.html">Plugin Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../repository/index.html">Maven Repository Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../developers/index.html">Maven Developer Centre</a>
+ </li>
+ <li class="none">
+ <a href="../../articles.html">Books and Resources</a>
+ </li>
+ <li class="none">
+ <a href="http://docs.codehaus.org/display/MAVENUSER/Home" class="externalLink">Wiki</a>
+ </li>
+ </ul>
+ <h5>Community</h5>
+ <ul>
+ <li class="none">
+ <a href="../../community.html">Community Overview</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/development/guide-helping.html">How to Contribute</a>
+ </li>
+ <li class="none">
+ <a href="../../guides/mini/guide-maven-evangelism.html">Maven Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../users/getting-help.html">Getting Help</a>
+ </li>
+ <li class="none">
+ <a href="../../issue-tracking.html">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="../../source-repository.html">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="../../team-list.html">The Maven Team</a>
+ </li>
+ </ul>
+ <h5>Project Documentation</h5>
+ <ul>
+ <li class="collapsed">
+ <a href="../../project-info.html">Project Information</a>
+ </li>
+ </ul>
+ <h5>Maven Projects</h5>
+ <ul>
+ <li class="none">
+ <a href="../../ant-tasks/index.html">Ant Tasks</a>
+ </li>
+ <li class="none">
+ <a href="../../archetype/index.html">Archetype</a>
+ </li>
+ <li class="none">
+ <a href="../../doxia/index.html">Doxia</a>
+ </li>
+ <li class="none">
+ <a href="../../jxr/index.html">JXR</a>
+ </li>
+ <li class="none">
+ <a href="../../maven-1.x/index.html">Maven 1.x</a>
+ </li>
+ <li class="none">
+ <a href="../../index.html">Maven 2 & 3</a>
+ </li>
+ <li class="none">
+ <a href="../../plugins/index.html">Plugins</a>
+ </li>
+ <li class="none">
+ <a href="../../scm/index.html">SCM</a>
+ </li>
+ <li class="none">
+ <a href="../../shared/index.html">Shared Components</a>
+ </li>
+ <li class="none">
+ <a href="../../surefire/index.html">Surefire</a>
+ </li>
+ <li class="none">
+ <a href="../../wagon/index.html">Wagon</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink">Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink">Sponsoring Apache</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/thanks.html" class="externalLink">Thanks</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../../images/logos/maven-feather.png"/>
+ </a>
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section"><h2>Guide to Creating Archetypes<a name="Guide_to_Creating_Archetypes"></a></h2><p>Creating an archetype is a pretty straight forward process. An archetype is a very simple artifact, that contains the project prototype you wish to create. An archetype is made up of:</p><ul><li>an <a class="externalLink" href="http://maven.apache.org/archetype/archetype-common/archetype.html">archetype descriptor</a> (<tt>archetype.xml</tt> in directory: <tt>src/main/resources/META-INF/maven/</tt>). It lists all the files that will be contained in the archetype and categorizes them so they can be processed correctly by the archetype generation mechanism.</li><li>the prototype files that are copied by the archetype plugin (directory: <tt>src/main/resources/archetype-resources/</tt>)</li><li>the prototype pom (<tt>pom.xml</tt> in: <tt>src/main/resources/archetype-resources</tt>)</li><li>a pom for the archetype (<tt>pom.xml</tt> in the archetype's root directory).</l
i></ul><p>Note: this mini-guide has been written for <a class="externalLink" href="http://maven.apache.org/plugins/maven-archetype-plugin-1.0-alpha-7/">archetype plugin version 1.0.x</a>, with its <a class="externalLink" href="http://maven.apache.org/archetype/archetype-common/archetype.html">old archetype descriptor</a> (stored in <tt>archetype.xml</tt> file). <a class="externalLink" href="http://maven.apache.org/archetype/maven-archetype-plugin/">Archetype plugin 2.0.x</a> is a new generation that fully supports archetypes created for 1.0.x, and adds a <a class="externalLink" href="http://maven.apache.org/archetype/archetype-common/archetype-descriptor.html">new archetype descriptor</a> (stored in <tt>archetype-metadata.xml</tt> file): it's more flexible, has more features, but the basis is absolutely the same.</p><p>To create an archetype follow these steps:</p><div class="section"><h3>1. Create a new project and pom.xml for the archetype artifact<a name="a1._Create_a_new
_project_and_pom.xml_for_the_archetype_artifact"></a></h3><p>An example <tt>pom.xml</tt> for an archetype artifact looks as follows:</p><div class="source"><pre>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>my.groupId</groupId>
+ <artifactId>my-archetype-id</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+</project>
+</pre></div><p>All you need to specify is a <tt>groupId</tt>, <tt>artifactId</tt> and <tt>version</tt>. These three parameters will be needed later for invoking the archetype via <tt>archetype:generate</tt> from the commandline.</p></div><div class="section"><h3>2. Create the archetype descriptor<a name="a2._Create_the_archetype_descriptor"></a></h3><p>The <a class="externalLink" href="http://maven.apache.org/archetype/archetype-common/archetype.html">archetype descriptor</a> is a file called <tt>archetype.xml</tt> which must be located in the <tt>src/main/resources/META-INF/maven/</tt> directory. An example of an archetype descriptor can be found in the quickstart archetype:</p><div class="source"><pre>
+<archetype xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype/1.0.0 http://maven.apache.org/xsd/archetype-1.0.0.xsd">
+ <id>quickstart</id>
+ <sources>
+ <source>src/main/java/App.java</source>
+ </sources>
+ <testSources>
+ <source>src/test/java/AppTest.java</source>
+ </testSources>
+</archetype>
+</pre></div><p>The <tt><id></tt> tag should be the same as the <tt>artifactId</tt> in the archetype <tt>pom.xml</tt>.</p><p>An optional <tt><allowPartial>true</allowPartial></tt> tag makes it possible to run the <tt>archetype:generate</tt> even on existing projects.</p><p>The <tt><sources></tt>, <tt><resources></tt>, <tt><testSources></tt>, <tt><testResources></tt> and <tt><siteResources></tt> tags represent the different sections of the project:</p><ul><li><tt><sources></tt> = <tt>src/main/java</tt></li><li><tt><resources></tt> = <tt>src/main/resources</tt></li><li><tt><testSources></tt> = <tt>src/test/java</tt></li><li><tt><testResources></tt> = <tt>src/test/resources</tt></li><li><tt><siteResources></tt> = <tt>src/site</tt></li></ul><p><tt><sources></tt> and <tt><testSources></tt> can contain <tt><source></tt> elements that specify a source file.</p><p><tt><testResources>
</tt> and <tt><siteResources></tt> can contain <tt><resource></tt> elements that specify a resource file.</p><p>Place other resources such as the ones in the <tt>src/main/webapp</tt> directory inside the <tt><resources></tt> tag.</p><p>At this point one can only specify individual files to be created but not empty directories.</p><p>Thus the quickstart archetype shown above defines the following directory structure:</p><div class="source"><pre>
+archetype
+|-- pom.xml
+`-- src
+ `-- main
+ `-- resources
+ |-- META-INF
+ | `-- maven
+ | `--archetype.xml
+ `-- archetype-resources
+ |-- pom.xml
+ `-- src
+ |-- main
+ | `-- java
+ | `-- App.java
+ `-- test
+ `-- java
+ `-- AppTest.java
+</pre></div></div><div class="section"><h3>3. Create the prototype files and the prototype pom.xml<a name="a3._Create_the_prototype_files_and_the_prototype_pom.xml"></a></h3><p>The next component of the archetype to be created is the prototype <tt>pom.xml</tt>. Any <tt>pom.xml</tt> will do, just don't forget to the set <tt>artifactId</tt> and <tt>groupId</tt> as variables ( <tt>${artifactId}</tt> / <tt>${groupId}</tt> ). Both variables will be initialized from the commandline when calling <tt>archetype:generate</tt>.</p><p>An example for a prototype <tt>pom.xml</tt> is:</p><div class="source"><pre>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>${groupId}</groupId>
+ <artifactId>${artifactId}</artifactId>
+ <version>${version}</version>
+ <packaging>jar</packaging>
+
+ <name>A custom project</name>
+ <url>http://www.myorganization.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+</project>
+</pre></div></div><div class="section"><h3>4. Install the archetype and run the archetype plugin<a name="a4._Install_the_archetype_and_run_the_archetype_plugin"></a></h3><p>Now you are ready to install the archetype:</p><div class="source"><pre>
+mvn install
+</pre></div><p>Now that you have created an archetype, you can try it on your local system by using the following command. In this command, you need to specify the full information about the archetype you want to use (its <tt>groupId</tt>, its <tt>artifactId</tt>, its <tt>version</tt>) and the information about the new project you want to create (<tt>artifactId</tt> and <tt>groupId</tt>). Don't forget to include the version of your archetype (if you don't include the version, you archetype creation may fail with a message that version:RELEASE was not found)</p><div class="source"><pre>
+mvn archetype:generate \
+ -DarchetypeGroupId=<archetype-groupId> \
+ -DarchetypeArtifactId=<archetype-artifactId> \
+ -DarchetypeVersion=<archetype-version> \
+ -DgroupId=<my.groupid> \
+ -DartifactId=<my-artifactId>
+</pre></div><p>Once you are happy with the state of your archetype, you can deploy (or submit it to ibiblio) it as any other artifact and the archetype will then be available to any user of Maven.</p></div><div class="section"><h3>Alternative way to start creating your Archetype<a name="Alternative_way_to_start_creating_your_Archetype"></a></h3><p>Instead of manually creating the directory structure needed for an archetype, simply use</p><div class="source"><pre>mvn archetype:generate
+ -DgroupId=[your project's group id]
+ -DartifactId=[your project's artifact id]
+ -DarchetypeArtifactId=maven-archetype-archetype</pre></div><p>Afterwhich, you can now customize the contents of the <tt>archetype-resources</tt> directory, and <tt>archetype.xml</tt>, then, proceed to Step#4 (Install the archetype and run the archetype plugin).</p></div></div>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+ © 2002-2012
+ The Apache Software Foundation
+
+ - <a href="http://maven.apache.org/privacy-policy.html">Privacy Policy</a>.
+ Apache Maven, Maven, Apache, the Apache feather logo, and the Apache Maven project logos are trademarks of The Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>