Modified: maven/website/content/guides/mini/guide-configuring-plugins.html ============================================================================== --- maven/website/content/guides/mini/guide-configuring-plugins.html (original) +++ maven/website/content/guides/mini/guide-configuring-plugins.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-configuring-plugins.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-configuring-plugins.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -10,7 +10,8 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0-M4" /> - <meta name="author" content="Jason van Zyl, Vincent Siveton" /> + <meta name="author" content="Jason van Zyl +Vincent Siveton" /> <meta name="date" content="2009-08-26" /> <title>Maven – Guide to Configuring Plug-ins</title> <link rel="stylesheet" href="../../css/apache-maven-fluido-1.11.1.min.css" /> @@ -48,7 +49,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Configuring Plug-ins <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-configuring-plugins.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Configuring Plug-ins <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-configuring-plugins.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -141,83 +142,42 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Configuring Plug-ins</h2> +<section> +<h1>Guide to Configuring Plug-ins</h1> <ul> - -<li> -<p><a href="#introduction">Introduction</a></p></li> -<li> -<p><a href="#generic-configuration">Generic Configuration</a></p></li> -<li> -<p><a href="#help-goal">Help Goal</a></p></li> -<li> -<p><a href="#configuring-parameters">Configuring Parameters</a></p></li> -<li> -<p><a href="#mapping-value-objects">Mapping Value Objects</a></p></li> -<li> -<p><a href="#mapping-complex-objects">Mapping Complex Objects</a></p></li> -<li> -<p><a href="#mapping-collection-types">Mapping Collection Types</a></p> +<li><a href="#Introduction">Introduction</a></li> +<li><a href="#Generic_Configuration">Generic Configuration</a> <ul> - -<li> -<p><a href="#mapping-collections-and-arrays">Mapping Collections and Arrays</a></p></li> -<li> -<p><a href="#mapping-maps">Mapping Maps</a></p></li> -<li> -<p><a href="#mapping-properties">Mapping Properties</a></p></li> -</ul></li> -<li> -<p><a href="#configuring-build-plugins">Configuring Build Plugins</a></p></li> -<li> -<p><a href="#using-the-executions-tag">Using the <code><executions></code> Tag</a></p></li> -<li> -<p><a href="#using-the-dependencies-tag">Using the <code><dependencies></code> Tag</a></p></li> -<li> -<p><a href="#using-the-inherited-tag-in-build-plugins">Using the <code><inherited></code> Tag In Build Plugins</a></p></li> -<li> -<p><a href="#configuring-reporting-plugins">Configuring Reporting Plugins</a></p></li> -<li> -<p><a href="#using-the-reporting-tag-vs-build-tag">Using the <code><reporting></code> Tag VS <code><build></code> Tag</a></p></li> -<li> -<p><a href="#using-the-reportsets-tag">Using the <code><reportSets></code> Tag</a></p></li> -<li> -<p><a href="#using-the-inherited-tag-in-reporting-plugins">Using the <code><inherited></code> Tag In Reporting Plugins</a></p></li> -</ul><section> -<h3>Introduction</h3> +<li><a href="#Help_Goal">Help Goal</a></li> +<li><a href="#Configuring_Parameters">Configuring Parameters</a> +<ul> +<li><a href="#Mapping_Value_Objects">Mapping Value Objects</a></li> +<li><a href="#Mapping_Complex_Objects">Mapping Complex Objects</a></li> +<li><a href="#Mapping_Collection_Types">Mapping Collection Types</a> +<ul> +<li><a href="#Mapping_Collections_and_Arrays">Mapping Collections and Arrays</a></li> +<li><a href="#Mapping_Maps">Mapping Maps</a></li> +<li><a href="#Mapping_Properties">Mapping Properties</a></li></ul></li></ul></li></ul></li> +<li><a href="#Configuring_Build_Plugins">Configuring Build Plugins</a> +<ul> +<li><a href="#Using_the_.3Cexecutions.3E_Tag">Using the <executions> Tag</a></li> +<li><a href="#Using_the_.3Cdependencies.3E_Tag">Using the <dependencies> Tag</a></li> +<li><a href="#Using_the_.3Cinherited.3E_Tag_In_Build_Plugins">Using the <inherited> Tag In Build Plugins</a></li></ul></li> +<li><a href="#Configuring_Reporting_Plugins">Configuring Reporting Plugins</a> +<ul> +<li><a href="#Using_the_.3Creporting.3E_Tag_VS_.3Cbuild.3E_Tag">Using the <reporting> Tag VS <build> Tag</a></li> +<li><a href="#Using_the_.3CreportSets.3E_Tag">Using the <reportSets> Tag</a></li> +<li><a href="#Using_the_.3Cinherited.3E_Tag_In_Reporting_Plugins">Using the <inherited> Tag In Reporting Plugins</a></li></ul></li></ul><section> +<h2>Introduction</h2> <p>In Maven, there are two kinds of plugins, build and reporting:</p> <ul> - -<li> -<p><strong>Build plugins</strong> are executed during the build and configured in the <code><build></code> element.</p></li> -<li> -<p><strong>Reporting plugins</strong> are executed during the site generation and configured in the <code><reporting></code> element.</p></li> -</ul> +<li><b>Build plugins</b> are executed during the build and configured in the <code><build/></code> element.</li> +<li><b>Reporting plugins</b> are executed during the site generation and configured in the <code><reporting/></code> element.</li></ul> <p>All plugins should have minimal required <a href="/ref/current/maven-model/maven.html#class_plugin">information</a>: <code>groupId</code>, <code>artifactId</code> and <code>version</code>.</p> -<p><strong>Important Note</strong>: Always define the version of each plugin used to guarantee build reproducibility. A good practice is to specify each build plugin's version in a <code><build><pluginManagement><build></code> element. Often the <code><pluginManagement></code> element is found in the parent POM. For reporting plugins, specify each version in the <code><reporting><plugins><reporting></code> element (and in the <code><build><pluginManagement><build></code> element too).</p></section><section> -<h3>Generic Configuration</h3> +<p><b>Important Note</b>: Always define the version of each plugin used to guarantee build reproducibility. A good practice is to specify each build plugin's version in a <code><build><pluginManagement/></build></code> element. Often the <pluginManagement/> element is found in the parent POM. For reporting plugins, specify each version in the <code><reporting><plugins/></reporting></code> element (and in the <code><build><pluginManagement/></build></code> element too).</p></section><section> +<h2><a id="Generic_Configuration">Generic Configuration</a></h2> <p>Maven plugins (build and reporting) are configured by specifying a <code><configuration></code> element where the child elements of the <code><configuration></code> 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, you have a Mojo that performs 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 class="prettyprint linenums"><code class="language-java">@Mojo( name = "query" ) +<div class="source"><pre class="prettyprint linenums">@Mojo( name = "query" ) public class MyQueryMojo extends AbstractMojo { @@ -235,11 +195,9 @@ public class MyQueryMojo { ... } -} -</code></pre></div> +}</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 class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -259,26 +217,22 @@ public class MyQueryMojo </plugins> </build> ... -</project> -</code></pre></div> +</project></pre></div> <p>The elements in the configuration match the names of the fields in the Mojo. The mapping is straight forward. The <code>url</code> element maps to the <code>url</code> field, the <code>timeout</code> element maps to the <code>timeout</code> field, and the <code>options</code> element maps to the <code>options</code> 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 <code><configuration></code> section in the POM. The plugin documentation for those parameters will list an <em>expression</em> that denotes the system properties for the configuration. In the Mojo above, the parameter <code>url</code> is associated with the expression <code>${query.url}</code>, meaning its value can be specified by the system property <code>query.url</code> as shown below:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn myquery:query -Dquery.url=http://maven.apache.org -</code></pre></div> +<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 <code><configuration></code> 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 <code>url</code> is associated with the expression <code>${query.url}</code>, meaning its value can be specified by the system property <code>query.url</code> as shown below:</p> +<div> +<pre>mvn myquery:query -Dquery.url=http://maven.apache.org</pre></div> <p>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><section> -<h4>Help Goal</h4> +<h3><a id="Help_Goal">Help Goal</a></h3> <p>Most Maven plugins have a <code>help</code> goal that prints a description of the plugin and its parameters and types. For instance, to see help for the javadoc goal, type:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn javadoc:help -Ddetail -Dgoal=javadoc -</code></pre></div> +<div> +<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 href="/plugins/maven-javadoc-plugin/javadoc-mojo.html">page</a>.</p></section><section> -<h4>Configuring Parameters</h4> -<p>Parametrisation of Mojos is relying internally on Plexus Component Configuration API provided by <a href="https://github.com/eclipse/sisu.plexus"; class="externalLink">sisu-plexus</a>.</p><section> -<h5>Mapping Value Objects</h5> +<h3><a id="Configuring_Parameters">Configuring Parameters</a></h3> +<p>Parametrisation of Mojos is relying internally on Plexus Component Configuration API provided by <a class="externalLink" href="https://github.com/eclipse/sisu.plexus";>sisu-plexus</a>.</p><section> +<h4><a id="Mapping_Value_Objects">Mapping Value Objects</a></h4> <p>Mapping value types, like Boolean or Integer, is very simple. The <code><configuration></code> element might look like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <configuration> <myString>a string</myString> @@ -289,71 +243,66 @@ public class MyQueryMojo <myURL>http://maven.apache.org</myURL> </configuration> ... -</project> -</code></pre></div> -<p>The detailed type coercion is explained in the table below. For conversion to primitive types their according <a href="https://docs.oracle.com/javase/tutorial/java/data/autoboxing.html"; class="externalLink">wrapper classes are used and automatically unboxed</a>.</p> -<table class="table table-striped"> -<thead> +</project></pre></div> +<p>The detailed type coercion is explained in the table below. For conversion to primitive types their according <a class="externalLink" href="https://docs.oracle.com/javase/tutorial/java/data/autoboxing.html";>wrapper classes are used and automatically unboxed</a>.</p> +<table class="bodyTable bodyTableBorder"> <tr class="a"> <th>Parameter Class</th> -<th>Conversion from String</th></tr></thead><tbody> +<th>Conversion from String</th></tr> <tr class="b"> -<td><code>Boolean</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html#valueOf-java.lang.String-"; class="externalLink"><code>Boolean.valueOf(String)</code></a></td></tr> +<td style="text-align: center;"><code>Boolean</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Boolean.html#valueOf-java.lang.String-";><code>Boolean.valueOf(String)</code></a></td></tr> <tr class="a"> -<td><code>Byte</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#decode-java.lang.String-"; class="externalLink"><code>Byte.decode(String)</code></a></td></tr> +<td style="text-align: center;"><code>Byte</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#decode-java.lang.String-";><code>Byte.decode(String)</code></a></td></tr> <tr class="b"> -<td><code>Character</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Character.html#valueOf-char-"; class="externalLink"><code>Character.valueOf(char)</code></a> of the first character in the given string</td></tr> +<td style="text-align: center;"><code>Character</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Character.html#valueOf-char-";><code>Character.valueOf(char)</code></a> of the first character in the given string</td></tr> <tr class="a"> -<td><code>Class</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-"; class="externalLink"><code>Class.forName(String)</code></a></td></tr> +<td style="text-align: center;"><code>Class</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#forName-java.lang.String-";><code>Class.forName(String)</code></a></td></tr> <tr class="b"> -<td><code>java.util.Date</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html#parse-java.lang.String-"; class="externalLink"><code>SimpleDateFormat.parse(String)</code></a> for the following patterns: <code>yyyy-MM-dd hh:mm:ss.S a</code>, <code>yyyy-MM-dd hh:mm:ssa</code>, <code>yyyy-MM-dd HH:mm:ss.S</code> or <code>yyyy-MM-dd HH:mm:ss</code></td></tr> +<td style="text-align: center;"><code>java.util.Date</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/text/DateFormat.html#parse-java.lang.String-";><code>SimpleDateFormat.parse(String)</code></a> for the following patterns: <code>yyyy-MM-dd hh:mm:ss.S a</code>, <code>yyyy-MM-dd hh:mm:ssa</code>, <code>yyyy-MM-dd HH:mm:ss.S</code> or <code>yyyy-MM-dd HH:mm:ss</code></td></tr> <tr class="a"> -<td><code>Double</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-"; class="externalLink"><code>Double.valueOf(String)</code></a></td></tr> +<td style="text-align: center;"><code>Double</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html#valueOf-java.lang.String-";><code>Double.valueOf(String)</code></a></td></tr> <tr class="b"> -<td><code>Enum</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#valueOf-java.lang.String-"; class="externalLink"><code>Enum.valueOf(String)</code></a></td></tr> +<td style="text-align: center;"><code>Enum</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html#valueOf-java.lang.String-";><code>Enum.valueOf(String)</code></a></td></tr> <tr class="a"> -<td><code>java.io.File</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/io/File.html#File-java.lang.String-"; class="externalLink"><code>new File(String)</code></a> with the file separators normalized to <code>File.separatorChar</code>. In case the file is relative, is is made absolute by prefixing it with the project's base directory.</td></tr> +<td style="text-align: center;"><code>java.io.File</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/io/File.html#File-java.lang.String-";><code>new File(String)</code></a> with the file separators normalized to <code>File.separatorChar</code>. In case the file is relative, is is made absolute by prefixing it with the project's base directory.</td></tr> <tr class="b"> -<td><code>Float</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#valueOf-java.lang.String-"; class="externalLink"><code>Float.valueOf(String)</code></a></td></tr> +<td style="text-align: center;"><code>Float</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Float.html#valueOf-java.lang.String-";><code>Float.valueOf(String)</code></a></td></tr> <tr class="a"> -<td><code>Integer</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-"; class="externalLink"><code>Integer.decode(String)</code></a></td></tr> +<td style="text-align: center;"><code>Integer</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#decode-java.lang.String-";><code>Integer.decode(String)</code></a></td></tr> <tr class="b"> -<td><code>Long</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#decode-java.lang.String-"; class="externalLink"><code>Long.decode(String)</code></a></td></tr> +<td style="text-align: center;"><code>Long</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Long.html#decode-java.lang.String-";><code>Long.decode(String)</code></a></td></tr> <tr class="a"> -<td><code>Short</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#decode-java.lang.String-"; class="externalLink"><code>Short.decode(String)</code></a></td></tr> +<td style="text-align: center;"><code>Short</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#decode-java.lang.String-";><code>Short.decode(String)</code></a></td></tr> <tr class="b"> -<td><code>String</code></td> -<td>n/a</td></tr> +<td style="text-align: center;"><code>String</code></td> +<td style="text-align: center;">n/a</td></tr> <tr class="a"> -<td><code>StringBuffer</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuffer.html#StringBuffer-java.lang.String-"; class="externalLink"><code>new StringBuffer(String)</code></a></td></tr> +<td style="text-align: center;"><code>StringBuffer</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuffer.html#StringBuffer-java.lang.String-";><code>new StringBuffer(String)</code></a></td></tr> <tr class="b"> -<td><code>StringBuilder</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html#StringBuilder-java.lang.String-"; class="externalLink"><code>new StringBuilder(String)</code></a></td></tr> +<td style="text-align: center;"><code>StringBuilder</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html#StringBuilder-java.lang.String-";><code>new StringBuilder(String)</code></a></td></tr> <tr class="a"> -<td><code>java.net.URI</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html#URI-java.lang.String-"; class="externalLink"><code>new URI(String)</code></a></td></tr> +<td style="text-align: center;"><code>java.net.URI</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/net/URI.html#URI-java.lang.String-";><code>new URI(String)</code></a></td></tr> <tr class="b"> -<td><code>java.net.URL</code></td> -<td><a href="https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-"; class="externalLink"><code>new URL(String)</code></a></td></tr></tbody> -</table> -</section><section> -<h5>Mapping Complex Objects</h5> -<p>Mapping complex types is also fairly straight forward. Let's look at a simple example where we are trying to map a configuration for Person object. The <code><configuration></code> element might look like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<td style="text-align: center;"><code>java.net.URL</code></td> +<td style="text-align: center;"><a class="externalLink" href="https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#URL-java.lang.String-";><code>new URL(String)</code></a></td></tr></table></section><section> +<h4><a id="Mapping_Complex_Objects">Mapping Complex Objects</a></h4> +<p>Mapping complex types is also fairly straight forward. Let's look at a simple example where we are trying to map a configuration for Person object. The <code><configuration/></code> element might look like the following:</p> +<div class="source"><pre class="prettyprint linenums"><project> ... <configuration> <person> @@ -362,20 +311,13 @@ public class MyQueryMojo </person> </configuration> ... -</project> -</code></pre></div> +</project></pre></div> <p>The rules for mapping complex objects are as follows:</p> <ul> - -<li> -<p>There must be a private field that corresponds to name of the element being mapped. So in our case the <code>person</code> element must map to a <code>person</code> field in the mojo.</p></li> -<li> -<p>The object instantiated must be in the same package as the Mojo itself. So if your mojo is in <code>com.mycompany.mojo.query</code> then the mapping mechanism will look in that package for an object named <code>Person</code>. The mechanism capitalizes the first letter of the element name and uses that to search for the object to instantiate.</p></li> -<li> -<p>If you wish to have the object to be instantiated live in a different package or have a more complicated name, specify this using an <code>implementation</code> attribute like the following:</p></li> -</ul> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<li>There must be a private field that corresponds to name of the element being mapped. So in our case the <code>person</code> element must map to a <code>person</code> 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 <code>com.mycompany.mojo.query</code> then the mapping mechanism will look in that package for an object named <code>Person</code>. The mechanism capitalizes the first letter of the element name and uses 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, specify this using an <code>implementation</code> attribute like the following:</li></ul> +<div class="source"><pre class="prettyprint linenums"><project> ... <configuration> <person implementation="com.mycompany.mojo.query.SuperPerson"> @@ -384,13 +326,12 @@ public class MyQueryMojo </person> </configuration> ... -</project> -</code></pre></div></section><section> -<h5>Mapping Collection Types</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>Mapping Collections and Arrays +</project></pre></div></section><section> +<h4><a id="Mapping_Collection_Types">Mapping Collection Types</a></h4> +<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><section> +<h5><a id="Mapping_Collections_and_Arrays">Mapping Collections and Arrays</a></h5> <p>Mapping to collections works in much the same way as mapping to arrays. Each item is given in the XML as dedicated element. The element name does not matter in that case. So if you have a mojo like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">public class MyAnimalMojo +<div class="source"><pre class="prettyprint linenums">public class MyAnimalMojo extends AbstractMojo { @Parameter(property = "animals") @@ -401,11 +342,9 @@ public class MyQueryMojo { ... } -} -</code></pre></div> +}</pre></div> <p>where you have a field named <code>animals</code> then your configuration for the plug-in would look like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -423,17 +362,16 @@ public class MyQueryMojo </plugins> </build> ... -</project> -</code></pre></div> +</project></pre></div> <p>Where each of the animals listed would be entries in the <code>animals</code> field. Unlike arrays, collections do not necessarily have a specific component type. In order to derive the type of a collection item, the following strategy is used:</p> -<p>1 If the XML element contains an <code>implementation</code> hint attribute, try to load the class with the given fully qualified class name from the attribute value</p> -<p>1 If the XML element contains a <code>.</code>, try to load the class with the fully qualified class name given in the element name</p> -<p>1 Try the XML element name (with capitalized first letter) as a class in the same package as the mojo/object being configured</p> -<p>1 Use the parameter type information from either <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()" class="externalLink"><code>Field.getGenericType()</code></a> or <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()" class="externalLink"><code>Method.getGenericParameterTypes()</code></a></p> -<p>1 If the element has no children, assume its type is <code>String</code>. Otherwise, the configuration will fail.</p> -<p>Since Maven 3.3.9 (<a href="https://issues.apache.org/jira/browse/MNG-5440"; class="externalLink">MNG-5440</a>), you can list individual items alternatively as comma-separated list in the XML value of animals directly. This approach is also used if configuring collection/array parameters via command line The following example is equivalent to the example above:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<ol style="list-style-type: decimal"> +<li>If the XML element contains an <code>implementation</code> hint attribute, try to load the class with the given fully qualified class name from the attribute value</li> +<li>If the XML element contains a <code>.</code>, try to load the class with the fully qualified class name given in the element name</li> +<li>Try the XML element name (with capitalized first letter) as a class in the same package as the mojo/object being configured</li> +<li>Use the parameter type information from either <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()"><code>Field.getGenericType()</code></a> or <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()"><code>Method.getGenericParameterTypes()</code></a></li> +<li>If the element has no children, assume its type is <code>String</code>. Otherwise, the configuration will fail.</li></ol> +<p>Since Maven 3.3.9 (<a class="externalLink" href="https://issues.apache.org/jira/browse/MNG-5440";>MNG-5440</a>), you can list individual items alternatively as comma-separated list in the XML value of animals directly. This approach is also used if configuring collection/array parameters via command line The following example is equivalent to the example above:</p> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -447,18 +385,15 @@ public class MyQueryMojo </plugins> </build> ... -</project> -</code></pre></div> -<p>Each item is mapped again according to the rules of this section depending on the type of the collection/array.</p>Mapping Maps +</project></pre></div> +<p>Each item is mapped again according to the rules of this section depending on the type of the collection/array.</p></section><section> +<h5><a id="Mapping_Maps">Mapping Maps</a></h5> <p>In the same way, you could define maps like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">... +<div class="source"><pre class="prettyprint linenums">... @Parameter private Map<String,String> myMap; -... -</code></pre></div> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +...</pre></div> +<div class="source"><pre class="prettyprint linenums"><project> ... <configuration> <myMap> @@ -467,19 +402,16 @@ public class MyQueryMojo </myMap> </configuration> ... -</project> -</code></pre></div> -<p>Unlike Collections the value type for Maps is always derived from the parameter type information from either <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()" class="externalLink"><code>Field.getGenericType()</code></a> or <a href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()" class="externalLink"><code>Method.getGenericParameterTypes()</code></a>. It falls back to <code>String</code>. The key type must always be <code>String</code>.</p> -<p>In contrast to value objects and collections/arrays there is no string coercion defined for maps, i.e. you cannot give parameters of that type via CLI argument.</p>Mapping Properties +</project></pre></div> +<p>Unlike Collections the value type for Maps is always derived from the parameter type information from either <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Field.html#getGenericType()"><code>Field.getGenericType()</code></a> or <a class="externalLink" href="https://docs.oracle.com/javase/7/docs/api/java/lang/reflect/Method.html#getGenericParameterTypes()"><code>Method.getGenericParameterTypes()</code></a>. It falls back to <code>String</code>. The key type must always be <code>String</code>.</p> +<p>In contrast to value objects and collections/arrays there is no string coercion defined for maps, i.e. you cannot give parameters of that type via CLI argument. </p></section><section> +<h5><a id="Mapping_Properties">Mapping Properties</a></h5> <p>Properties should be defined like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-java">... +<div class="source"><pre class="prettyprint linenums">... @Parameter private Properties myProperties; -... -</code></pre></div> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +...</pre></div> +<div class="source"><pre class="prettyprint linenums"><project> ... <configuration> <myProperties> @@ -494,15 +426,13 @@ public class MyQueryMojo </myProperties> </configuration> ... -</project> -</code></pre></div> -<p>In contrast to value objects and collections/arrays there is no string coercion defined for properties, i.e. you cannot give parameters of those type via CLI argument.</p></section></section></section><section> -<h3>Configuring Build Plugins</h3> +</project></pre></div> +<p>In contrast to value objects and collections/arrays there is no string coercion defined for properties, i.e. you cannot give parameters of those type via CLI argument. </p></section></section></section></section><section> +<h2><a id="Configuring_Build_Plugins">Configuring Build Plugins</a></h2> <p>The following is only to configure Build plugins in the <code><build></code> element.</p><section> -<h4>Using the <code><executions></code> Tag</h4> +<h3><a id="Using_the_executions_Tag">Using the <code><executions></code> Tag</a></h3> <p>You can also configure a mojo using the <code><executions></code> 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 <code>MyQueryMojo</code> as an example, you may have something that will look like:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -546,13 +476,11 @@ public class MyQueryMojo </plugins> </build> ... -</project> -</code></pre></div> -<p>The first execution with id “execution1” binds this configuration to the test phase. The second execution does not have a <code><phase></code> 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> +</project></pre></div> +<p>The first execution with id "execution1" binds this configuration to the test phase. The second execution does not have a <code><phase></code> 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 <code>execution2</code> to a phase.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -585,12 +513,10 @@ public class MyQueryMojo </plugins> </build> ... -</project> -</code></pre></div> +</project></pre></div> <p>If there are multiple executions bound to different phases, then the mojo is executed once for each phase indicated. Meaning, <code>execution1</code> will be executed applying the configuration setup when the phase of the build is test, and <code>execution2</code> 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 class="prettyprint linenums"><code class="language-java">@Mojo( name = "query", defaultPhase = LifecyclePhase.PACKAGE ) +<div class="source"><pre class="prettyprint linenums">@Mojo( name = "query", defaultPhase = LifecyclePhase.PACKAGE ) public class MyBoundQueryMojo extends AbstractMojo { @@ -608,11 +534,9 @@ public class MyBoundQueryMojo { ... } -} -</code></pre></div> +}</pre></div> <p>From the above mojo example, <code>MyBoundQueryMojo</code> is by default bound to the package phase (see the <code>@phase</code> 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 <code><phase></code> tag under <code><execution></code>.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -641,18 +565,15 @@ public class MyBoundQueryMojo </plugins> </build> ... -</project> -</code></pre></div> +</project></pre></div> <p>Now, <code>MyBoundQueryMojo</code> default phase which is package has been overridden by install phase.</p> -<p><strong>Note:</strong> Configurations inside the <code><executions></code> element used to differ from those that are outside <code><executions></code> in that they could not be used from a direct command line invocation because they were only applied when the lifecycle phase they were bound to was invoked. So you had to move a configuration section outside of the executions section to apply it globally to all invocations of the plugin. Since Maven 3.3.1 this is not the case anymore as you can specify on the command line the execution id for direct plugin goal invocation. Hence if you want to run the above plugin and it's specific execution1's configuration from the command-line, you can execute:</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn myquery:query@execution1 -</code></pre></div></section><section> -<h4>Using the <code><dependencies></code> Tag</h4> +<p><b>Note:</b> Configurations inside the <code><executions></code> element used to differ from those that are outside <code><executions></code> in that they could not be used from a direct command line invocation because they were only applied when the lifecycle phase they were bound to was invoked. So you had to move a configuration section outside of the executions section to apply it globally to all invocations of the plugin. Since Maven 3.3.1 this is not the case anymore as you can specify on the command line the execution id for direct plugin goal invocation. Hence if you want to run the above plugin and it's specific execution1's configuration from the command-line, you can execute:</p> +<div> +<pre>mvn myquery:query@execution1</pre></div></section><section> +<h3><a id="Using_the_dependencies_Tag">Using the <code><dependencies></code> Tag</a></h3> <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 <code><dependencies></code> element like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -677,12 +598,10 @@ public class MyBoundQueryMojo </plugins> </build> ... -</project> -</code></pre></div></section><section> -<h4>Using the <code><inherited></code> Tag In Build Plugins</h4> +</project></pre></div></section><section> +<h3><a id="Using_the_inherited_Tag_In_Build_Plugins">Using the <code><inherited></code> Tag In Build Plugins</a></h3> <p>By default, plugin configuration should be propagated to child POMs, so to break the inheritance, you could use the <code><inherited></code> tag:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <build> <plugins> @@ -696,18 +615,19 @@ public class MyBoundQueryMojo </plugins> </build> ... -</project> -</code></pre></div></section></section><section> -<h3>Configuring Reporting Plugins</h3> +</project></pre></div></section></section><section> +<h2><a id="Configuring_Reporting_Plugins">Configuring Reporting Plugins</a></h2> <p>The following is only to configure Reporting plugins in the <code><reporting></code> element.</p><section> -<h4>Using the <code><reporting></code> Tag VS <code><build></code> Tag</h4> +<h3><a id="Using_the_reporting_Tag_VS_build_Tag">Using the <code><reporting></code> Tag VS <code><build></code> Tag</a></h3> <p>Configuring a reporting plugin in the <code><reporting></code> or <code><build></code> elements in the pom does not exactly have the same results.</p> -<p>[<code>mvn site</code>] Since maven-site-plugin 3.4, it uses the parameters defined in the <code><configuration></code> element of each reporting Plugin specified in the <code><reporting></code> element, in addition to the parameters defined in the <code><configuration></code> element of each plugin specified in <code><build></code> (parameters from <code><build></code> section were previously ignored).</p> -<p>[<code>mvn aplugin:areportgoal</code>] It <strong>ignores</strong> the parameters defined in the <code><configuration></code> element of each reporting Plugin specified in the <code><reporting></code> element; only parameters defined in the <code><configuration></code> element of each plugin specified in <code><build></code> are used.</p></section><section> -<h4>Using the <code><reportSets></code> Tag</h4> +<dl> +<dt><code>mvn site</code></dt> +<dd>Since maven-site-plugin 3.4, it uses the parameters defined in the <code><configuration></code> element of each reporting Plugin specified in the <code><reporting></code> element, in addition to the parameters defined in the <code><configuration></code> element of each plugin specified in <code><build></code> (parameters from <code><build></code> section were previously ignored).</dd> +<dt><code>mvn aplugin:areportgoal</code></dt> +<dd>It <b>ignores</b> the parameters defined in the <code><configuration></code> element of each reporting Plugin specified in the <code><reporting></code> element; only parameters defined in the <code><configuration></code> element of each plugin specified in <code><build></code> are used.</dd></dl></section><section> +<h3><a id="Using_the_reportSets_Tag">Using the <code><reportSets></code> Tag</a></h3> <p>You can configure a reporting plugin using the <code><reportSets></code> tag. This is most commonly used to generate reports selectively when running <code>mvn site</code>. The following will generate only the project team report.</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <reporting> <plugins> @@ -726,22 +646,19 @@ public class MyBoundQueryMojo </plugins> </reporting> ... -</project> -</code></pre></div> -<p><strong>Notes</strong>:</p> -<p>1 To exclude all reports, you need to use:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> <reportSets> +</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 class="prettyprint linenums"> <reportSets> <reportSet> <reports/> </reportSet> - </reportSets> -</code></pre></div> -<p>1 Refer to each Plugin Documentation (i.e. plugin-info.html) to know the available report goals.</p></section><section> -<h4>Using the <code><inherited></code> Tag In Reporting Plugins</h4> + </reportSets></pre></div></li> +<li>Refer to each Plugin Documentation (i.e. plugin-info.html) to know the available report goals.</li></ol></section><section> +<h3><a id="Using_the_inherited_Tag_In_Reporting_Plugins">Using the <code><inherited></code> Tag In Reporting Plugins</a></h3> <p>Similar to the build plugins, to break the inheritance, you can use the <code><inherited></code> tag:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><project> +<div class="source"><pre class="prettyprint linenums"><project> ... <reporting> <plugins> @@ -754,8 +671,7 @@ public class MyBoundQueryMojo </plugins> </reporting> ... -</project> -</code></pre></div></section></section></section></section> +</project></pre></div></section></section></section> </main> </div> </div>
Modified: maven/website/content/guides/mini/guide-creating-archetypes.html ============================================================================== --- maven/website/content/guides/mini/guide-creating-archetypes.html (original) +++ maven/website/content/guides/mini/guide-creating-archetypes.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-creating-archetypes.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-creating-archetypes.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Creating Archetypes <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-creating-archetypes.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Creating Archetypes <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-creating-archetypes.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -140,43 +140,18 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Creating Archetypes</h2> +<section> +<h1>Guide to Creating Archetypes</h1> <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> -<p>an <a href="/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html">archetype descriptor</a> (<code>archetype-metadata.xml</code> in directory: <code>src/main/resources/META-INF/maven/</code>). 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.</p></li> -<li> -<p>the prototype files that are copied by the archetype plugin (directory: <code>src/main/resources/archetype-resources/</code>)</p></li> -<li> -<p>the prototype pom (<code>pom.xml</code> in: <code>src/main/resources/archetype-resources</code>)</p></li> -<li> -<p>a pom for the archetype (<code>pom.xml</code> in the archetype's root directory).</p></li> -</ul> +<li>an <a href="/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html">archetype descriptor</a> (<code>archetype-metadata.xml</code> in directory: <code>src/main/resources/META-INF/maven/</code>). 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: <code>src/main/resources/archetype-resources/</code>)</li> +<li>the prototype pom (<code>pom.xml</code> in: <code>src/main/resources/archetype-resources</code>)</li> +<li>a pom for the archetype (<code>pom.xml</code> in the archetype's root directory).</li></ul> <p>To create an archetype follow these steps:</p><section> -<h3>1. Create a new project and pom.xml for the archetype artifact</h3> +<h2>1. Create a new project and pom.xml for the archetype artifact</h2> <p>An example <code>pom.xml</code> for an archetype artifact looks as follows:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <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 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -196,13 +171,11 @@ under the License. </extensions> </build> </project> - -</code></pre></div> +</pre></div> <p>All you need to specify is a <code>groupId</code>, <code>artifactId</code> and <code>version</code>. These three parameters will be needed later for invoking the archetype via <code>archetype:generate</code> from the commandline.</p></section><section> -<h3>2. Create the archetype descriptor</h3> +<h2>2. Create the archetype descriptor</h2> <p>The <a href="/archetype/archetype-models/archetype-descriptor/archetype-descriptor.html">archetype descriptor</a> is a file called <code>archetype-metadata.xml</code> which must be located in the <code>src/main/resources/META-INF/maven/</code> directory. An example of an archetype descriptor can be found in the quickstart archetype:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <archetype-descriptor xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-descriptor/1.1.0 https://maven.apache.org/xsd/archetype-descriptor-1.1.0.xsd" @@ -216,24 +189,18 @@ under the License. </fileSet> </fileSets> </archetype-descriptor> - -</code></pre></div> +</pre></div> <p>The attribute <code>name</code> tag should be the same as the <code>artifactId</code> in the archetype <code>pom.xml</code>.</p> <p>The boolean attribute <code>partial</code> show if this archetype is representing a full Maven project or only parts.</p> <p>The <code>requiredProperties</code>, <code>fileSets</code> and <code>modules</code> tags represent the differents parts of the project:</p> <ul> - -<li> -<p><code><requiredProperties></code> : List of required properties to generate a project from this archetype</p></li> -<li> -<p><code><fileSets></code> : File sets definition</p></li> -<li> -<p><code><modules></code> : Modules definition</p></li> -</ul> +<li><code><requiredProperties></code> : List of required properties to generate a project from this archetype</li> +<li><code><fileSets></code> : File sets definition</li> +<li><code><modules></code> : Modules definition</li></ul> <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 class="prettyprint linenums"><code class="language-xml"> +<div> +<pre> archetype |-- pom.xml `-- src @@ -251,13 +218,11 @@ archetype `-- test `-- java `-- AppTest.java - -</code></pre></div></section><section> -<h3>3. Create the prototype files and the prototype pom.xml</h3> +</pre></div></section><section> +<h2>3. Create the prototype files and the prototype pom.xml</h2> <p>The next component of the archetype to be created is the prototype <code>pom.xml</code>. Any <code>pom.xml</code> will do, just don't forget to the set <code>artifactId</code> and <code>groupId</code> as variables ( <code>${artifactId}</code> / <code>${groupId}</code> ). Both variables will be initialized from the commandline when calling <code>archetype:generate</code>.</p> <p>An example for a prototype <code>pom.xml</code> is:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <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 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> @@ -279,37 +244,33 @@ archetype </dependency> </dependencies> </project> - -</code></pre></div></section><section> -<h3>4. Install the archetype and run the archetype plugin</h3> +</pre></div></section><section> +<h2>4. Install the archetype and run the archetype plugin</h2> <p>Now you are ready to install the archetype:</p> - -<div class="source"><pre class="prettyprint linenums"><code> +<div> +<pre> mvn install - -</code></pre></div> +</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 <code>groupId</code>, its <code>artifactId</code>, its <code>version</code>) and the information about the new project you want to create (<code>artifactId</code> and <code>groupId</code>). 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 class="prettyprint linenums"><code> +<div> +<pre> mvn archetype:generate \ -DarchetypeGroupId=<archetype-groupId> \ -DarchetypeArtifactId=<archetype-artifactId> \ -DarchetypeVersion=<archetype-version> \ -DgroupId=<my.groupid> \ -DartifactId=<my-artifactId> - -</code></pre></div> +</pre></div> <p>Once you are happy with the state of your archetype, you can deploy (or submit it to <a href="/guides/mini/guide-central-repository-upload.html">Maven Central</a>) it as any other artifact and the archetype will then be available to any user of Maven.</p></section><section> -<h3>Alternative way to start creating your Archetype</h3> +<h2>Alternative way to start creating your Archetype</h2> <p>Instead of manually creating the directory structure needed for an archetype, simply use</p> - -<div class="source"><pre class="prettyprint linenums"><code>mvn archetype:generate +<div> +<pre>mvn archetype:generate -DgroupId=[your project's group id] -DartifactId=[your project's artifact id] -DarchetypeGroupId=org.apache.maven.archetypes - -DarchetypeArtifactId=maven-archetype-archetype -</code></pre></div> -<p>Afterwhich, you can now customize the contents of the <code>archetype-resources</code> directory, and <code>archetype-metadata.xml</code>, then, proceed to Step#4 (Install the archetype and run the archetype plugin).</p></section></section></section> + -DarchetypeArtifactId=maven-archetype-archetype</pre></div> +<p>Afterwhich, you can now customize the contents of the <code>archetype-resources</code> directory, and <code>archetype-metadata.xml</code>, then, proceed to Step#4 (Install the archetype and run the archetype plugin).</p></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-default-execution-ids.html ============================================================================== --- maven/website/content/guides/mini/guide-default-execution-ids.html (original) +++ maven/website/content/guides/mini/guide-default-execution-ids.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-default-execution-ids.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-default-execution-ids.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Configuring Default Mojo Executions <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-default-execution-ids.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Configuring Default Mojo Executions <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-default-execution-ids.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -141,45 +141,21 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Guide to Configuring Default Mojo Executions</h2> -<p>In most cases where you need to configure a plugin, there are two options that work well: plugin-level configuration and execution-level configuration. Plugin-level configuration is the most common method for configuring plugins that will be used from the command line, are defined as part of the default lifecycle, or that use a common configuration across all invocations. In fact, for direct invocation from the command line, plugin-level configuration has been the <em>only</em> option historically.</p> +<section> +<h1>Guide to Configuring Default Mojo Executions</h1> +<p>In most cases where you need to configure a plugin, there are two options that work well: plugin-level configuration and execution-level configuration. Plugin-level configuration is the most common method for configuring plugins that will be used from the command line, are defined as part of the default lifecycle, or that use a common configuration across all invocations. In fact, for direct invocation from the command line, plugin-level configuration has been the <i>only</i> option historically.</p> <p>On the other hand, in cases where a more advanced build process requires the execution of mojos - sometimes the same mojos, sometimes different ones - from a single plugin that use different configurations, the execution-level configuration is most commonly used. These cases normally involve plugins that are introduced as part of the standard build process, but which aren't present in the default lifecycle mapping for that particular packaging. In these cases, common settings shared between executions are still normally specified in the plugin-level configuration.</p> -<p>However, these two options leave out a few important configuration use cases:</p> +<p>However, these two options leave out a few important configuration use cases: </p> <ul> - -<li> -<p>Mojos run from the command line <em>and</em> during the build, when the CLI-driven invocation requires its own configuration.</p></li> -<li> -<p>Mojo executions that are bound to the lifecycle as part of the default mapping for a particular packaging, especially in cases where the same mojos need to be added to a second execution with different configuration.</p></li> -<li> -<p>Groups of mojos from the same plugin that are bound to the lifecycle as part of the default mapping for a particular packaging, but require separate configurations.</p></li> -</ul><section> -<h3>Default <code>executionId</code>s for Implied Executions</h3> +<li>Mojos run from the command line <i>and</i> during the build, when the CLI-driven invocation requires its own configuration.</li> +<li>Mojo executions that are bound to the lifecycle as part of the default mapping for a particular packaging, especially in cases where the same mojos need to be added to a second execution with different configuration.</li> +<li>Groups of mojos from the same plugin that are bound to the lifecycle as part of the default mapping for a particular packaging, but require separate configurations.</li></ul><section> +<h2>Default <code>executionId</code>s for Implied Executions</h2> <p>When you consider the fact that the aforementioned configuration use cases are for mojos that are not explicitly mentioned in the POM, it's reasonable to refer to them as implied executions. But if they're implied, how can Maven allow users to provide configuration for them? The solution we've implemented is rather simple and low-tech, but should be more than adequate to handle even advanced use cases. Starting in Maven 2.2.0, each mojo invoked directly from the command line will have an execution Id of <code>default-cli</code> assigned to it, which will allow the configuration of that execution from the POM by using this default execution Id. Likewise, each mojo bound to the build lifecycle via the default lifecycle mapping for the specified POM packaging will have an execution Id of <code>default-<goalName></code> assigned to it, to allow configuration of each default mojo execution independently.</p><section> -<h4>Example: Command-line variant invocation of the assembly plugin</h4> +<h3>Example: Command-line variant invocation of the assembly plugin</h3> <p>Consider the case where the user wants to execute the <code>assembly:assembly</code> mojo directly on the command line, but already has a configuration for the <code>assembly:single</code> mojo that runs during the main build lifecycle. Since these configurations require different options, the user cannot use the plugin-level configuration section to specify common elements.</p> <p>In this case, the assembly-plugin configuration might look like this:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><plugin> +<div class="source"><pre class="prettyprint linenums"><plugin> <artifactId>maven-assembly-plugin</artifactId> <configuration> <tarLongFileMode>gnu</tarLongFileMode> @@ -208,16 +184,14 @@ under the License. </configuration> </execution> </executions> -</plugin> -</code></pre></div> +</plugin></pre></div> <p>In the above example, you can see several interesting things. First, the main build process will invoke the <code>assembly:single</code> mojo during the <code>package</code> phase of the build, and produce both binary and source distribution artifacts using custom assembly descriptors included with the project. Second, all invocations of the assembly plugin should use a <code>tarLongFileMode</code> strategy of <code>gnu</code>. Finally, when the assembly plugin is invoked from the command line, it will build the standard <code>jar-with-dependencies</code> and <code>project</code> artifacts for the project, and ignore the custom assembly descriptors in <code>src/main/assembly</code>.</p> <p>Now, notice the difference in the way the two execution blocks reference assembly descriptors. One uses custom descriptors via the <code>descriptors</code> section, and the other uses standard descriptors via the <code>descriptorRefs</code> section. These two sections cannot override one another, so it's impossible to setup one section - say, <code>descriptorRefs</code> - in the plugin-level configuration block (to provide CLI access to it, as historical versions of Maven would require), then have the <code>build-distros</code> invocation override it with the custom descriptors specified in the <code>descriptors</code> section.</p></section><section> -<h4>Example: Configuring <code>compile</code> to run twice</h4> +<h3>Example: Configuring <code>compile</code> to run twice</h3> <p>In this scenario, the user wants to run the <code>compiler:compile</code> mojo twice for his <code>jar</code> packaging project. The main reason for this is to provide an entry point into the application that will warn the user if he's using a Java version older than 1.5, then exit gracefully. Without such an entry point, the user would be confronted with a stacktrace in the event he tried to run this application with a 1.4 or older JRE.</p> -<p>Therefore, the user needs to compile the bulk of his application to target the 1.5 Java specification, then compile the rest (the entry point) to target an older specification…say, 1.3. The first execution will specify the <code>source</code> and <code>target</code> values at <code>1.5</code>, and add an <code>excludes</code> section to avoid compiling the entry point for the application. The second pass will then re-specify <code>source</code> and <code>target</code> to <code>1.3</code>, and basically invert the original <code>excludes</code> section to be an <code>includes</code> section, so as to compile <em>only</em> the entry point class.</p> +<p>Therefore, the user needs to compile the bulk of his application to target the 1.5 Java specification, then compile the rest (the entry point) to target an older specification...say, 1.3. The first execution will specify the <code>source</code> and <code>target</code> values at <code>1.5</code>, and add an <code>excludes</code> section to avoid compiling the entry point for the application. The second pass will then re-specify <code>source</code> and <code>target</code> to <code>1.3</code>, and basically invert the original <code>excludes</code> section to be an <code>includes</code> section, so as to compile <i>only</i> the entry point class.</p> <p>The resulting configuration might look something like this:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><plugin> +<div class="source"><pre class="prettyprint linenums"><plugin> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> @@ -247,23 +221,16 @@ under the License. </configuration> </execution> </executions> -</plugin> -</code></pre></div> +</plugin></pre></div> <p>There are three important things to notice in the above compiler-plugin configuration:</p> <ul> - -<li> -<p>The default <code>source</code> and <code>target</code> compatibility levels are for Java 1.5. This means that the compiler will generate binaries for Java 1.5 from both the main codebase and the test codebase, unless otherwise overridden.</p></li> -<li> -<p>The default pass of the <code>compile</code> goal will <em>exclude</em> the <code>\*\*/cli/\*</code> path pattern, but will compile everything else in <code>src/main/java</code> to run under Java 1.5.</p></li> -<li> -<p>The second pass of the <code>compile</code> mojo - in the execution called <code>build-java14-cli</code> - resets the <code>source</code> and <code>target</code> versions to <code>1.3</code>, and inverts the exclude rule from the first pass. This means the second time around, the compiler will produce 1.4-targeted binaries for the classes matching the <code>\*\*/cli/\*</code> path pattern.</p></li> -</ul></section><section> -<h4>Example: Configuring <code>compile</code> and <code>testCompile</code> mojos separately</h4> +<li>The default <code>source</code> and <code>target</code> compatibility levels are for Java 1.5. This means that the compiler will generate binaries for Java 1.5 from both the main codebase and the test codebase, unless otherwise overridden.</li> +<li>The default pass of the <code>compile</code> goal will <i>exclude</i> the <code>**/cli/*</code> path pattern, but will compile everything else in <code>src/main/java</code> to run under Java 1.5.</li> +<li>The second pass of the <code>compile</code> mojo - in the execution called <code>build-java14-cli</code> - resets the <code>source</code> and <code>target</code> versions to <code>1.3</code>, and inverts the exclude rule from the first pass. This means the second time around, the compiler will produce 1.4-targeted binaries for the classes matching the <code>**/cli/*</code> path pattern.</li></ul></section><section> +<h3>Example: Configuring <code>compile</code> and <code>testCompile</code> mojos separately</h3> <p>Finally, building on our use of the compiler plugin to tease out these different use cases, consider the case where a user wants to target version 1.4 of the Java specification as his runtime platform. However, he still wants the convenience and other advantages to be found in a unit-testing framework like TestNG. This forces the user to configure the <code>compile</code> mojo with one set of <code>source</code> and <code>target</code> values - specifically, <code>1.4</code> - and the <code>testCompile</code> mojo with another (<code>1.5</code>).</p> <p>The resulting compiler-plugin configuration might look something like the following:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"><plugin> +<div class="source"><pre class="prettyprint linenums"><plugin> <artifactId>maven-compiler-plugin</artifactId> <executions> <execution> @@ -281,10 +248,9 @@ under the License. </configuration> </execution> </executions> -</plugin> -</code></pre></div> +</plugin></pre></div> <p>This example is fairly simple and straightforward. First, the <code>default-compile</code> execution sets the <code>source</code> and <code>target</code> values to <code>1.3</code> to allow older Java versions to run the project. Then, the <code>default-testCompile</code> execution resets the <code>source</code> and <code>target</code> values to <code>1.5</code>, which enables the project to use tools like TestNG that use annotations.</p> -<p>Incidentally, it's perhaps useful to point out that the example above is a little bit contrived; the compiler plugin targets Java 1.3 by default, so the only configuration that's really required is the <code>default-testCompile</code> execution. The <code>default-compile</code> execution respecifies plugin defaults. The only time this might be useful is when a parent POM defines a plugin-level configuration for <code>source</code> and <code>target</code> that needs to be changed for the purposes of these different compiler executions. This example is meant to be illustrative of the potential for separate configuration of default lifecycle mojos.</p></section></section></section></section> +<p>Incidentally, it's perhaps useful to point out that the example above is a little bit contrived; the compiler plugin targets Java 1.3 by default, so the only configuration that's really required is the <code>default-testCompile</code> execution. The <code>default-compile</code> execution respecifies plugin defaults. The only time this might be useful is when a parent POM defines a plugin-level configuration for <code>source</code> and <code>target</code> that needs to be changed for the purposes of these different compiler executions. This example is meant to be illustrative of the potential for separate configuration of default lifecycle mojos.</p></section></section></section> </main> </div> </div> Modified: maven/website/content/guides/mini/guide-deployment-security-settings.html ============================================================================== --- maven/website/content/guides/mini/guide-deployment-security-settings.html (original) +++ maven/website/content/guides/mini/guide-deployment-security-settings.html Sat Feb 18 20:40:58 2023 @@ -2,7 +2,7 @@ <!-- - | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/mini/guide-deployment-security-settings.md at 2023-02-18 + | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/mini/guide-deployment-security-settings.apt at 2023-02-18 | Rendered using Apache Maven Fluido Skin 1.11.1 --> <html xmlns="http://www.w3.org/1999/xhtml"; lang=""> @@ -48,7 +48,7 @@ <ul class="breadcrumb"> <li class=""><a href="https://www.apache.org/"; class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> <li class=""><a href="../../index.html" title="Maven">Maven</a><span class="divider">/</span></li> - <li class="active ">Guide to Deployment and Security Settings <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/mini/guide-deployment-security-settings.md";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> + <li class="active ">Guide to Deployment and Security Settings <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/mini/guide-deployment-security-settings.apt";><img src="../../images/accessories-text-editor.png" title="Edit" /></a></li> <li id="publishDate" class="pull-right"><span class="divider">|</span> Last Published: 2023-02-18</li> <li class="pull-right"><span class="divider">|</span> <a href="../../scm.html" title="Get Sources">Get Sources</a></li> @@ -152,31 +152,12 @@ </div> </header> <main id="bodyColumn" class="span10" > -<!-- -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. ---> -<section><section> -<h2>Security and Deployment Settings</h2> +<section> +<h1>Security and Deployment Settings</h1> <p>Repositories to deploy to are defined in a project in the <code>distributionManagement</code> section. However, you cannot put your username, password, or other security settings in that project. For that reason, you should add a server definition to your own settings with an id that matches that of the deployment repository in the project.</p> <p>In addition, some repositories may require authorisation to download from, so the corresponding settings can be specified in a server element in the same way.</p> <p>Which settings are required will depend on the type of repository you are deploying to. As of the first release, only SCP deployments and file deployments are supported by default, so only the following SCP configuration is needed:</p> - -<div class="source"><pre class="prettyprint linenums"><code class="language-xml"> +<div class="source"><pre class="prettyprint linenums"> <settings> . . @@ -194,10 +175,9 @@ under the License. . . </settings> - -</code></pre></div> -<p>To encrypt passwords in these sections, refer to <a href="./guide-encryption.html">Encryption Settings</a>.</p> -<p><strong>Note</strong>: The settings descriptor documentation can be found on the <a href="../../maven-settings/settings.html">Maven Local Settings Model Website</a>.</p></section></section> +</pre></div> +<p>To encrypt passwords in these sections, refer to <a href="./guide-encryption.html"> Encryption Settings</a>.</p> +<p><b>Note</b>: The settings descriptor documentation can be found on the <a href="../../maven-settings/settings.html">Maven Local Settings Model Website</a>.</p></section> </main> </div> </div>
