You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-commits@maven.apache.org by sl...@apache.org on 2023/02/09 00:34:07 UTC
svn commit: r1907531 [10/25] - in /maven/website/content: ./ apache-resource-bundles/ archives/maven-2.x/ background/ developers/ developers/conventions/ developers/release/ developers/website/ docs/ docs/2.0.1/ docs/2.0.10/ docs/2.0.11/ docs/2.0.2/ do...
Modified: maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html (original)
+++ maven/website/content/guides/introduction/introduction-to-optional-and-excludes-dependencies.html Thu Feb 9 00:34:05 2023
@@ -2,7 +2,7 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md at 2023-02-09
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
@@ -48,8 +48,8 @@
<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 ">Optional Dependencies and Dependency Exclusions <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.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-08</li>
+ <li class="active ">Optional Dependencies and Dependency Exclusions <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md"><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-09</li>
<li class="pull-right"><span class="divider">|</span>
<a href="../../scm.html" title="Get Sources">Get Sources</a></li>
<li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li>
@@ -148,17 +148,36 @@
</div>
</header>
<main id="bodyColumn" class="span10" >
-<section>
-<h1>Introduction</h1>
+<!--
+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>Introduction</h2>
<p>This section discusses optional dependencies and dependency exclusions. This will help users to understand what they are and when and how to use them. It also explains why exclusions are made on a per dependency basis instead of at the POM level.</p><section>
-<h2>Optional Dependencies</h2>
-<p>Optional dependencies are used when it's not possible (for whatever reason) to split a project into sub-modules. The idea is that some of the dependencies are only used for certain features in the project and will not be needed if that feature isn't used. Ideally, such a feature would be split into a sub-module that depends on the core functionality project. This new subproject would have only non-optional dependencies, since you'd need them all if you decided to use the subproject's functionality. </p>
+<h3>Optional Dependencies</h3>
+<p>Optional dependencies are used when it's not possible (for whatever reason) to split a project into sub-modules. The idea is that some of the dependencies are only used for certain features in the project and will not be needed if that feature isn't used. Ideally, such a feature would be split into a sub-module that depends on the core functionality project. This new subproject would have only non-optional dependencies, since you'd need them all if you decided to use the subproject's functionality.</p>
<p>However, since the project cannot be split up (again, for whatever reason), these dependencies are declared optional. If a user wants to use functionality related to an optional dependency, they have to redeclare that optional dependency in their own project. This is not the clearest way to handle this situation, but both optional dependencies and dependency exclusions are stop-gap solutions.</p><section>
-<h3>Why use optional dependencies?</h3>
-<p>Optional dependencies save space and memory. They prevent problematic jars that violate a license agreement or cause classpath issues from being bundled into a WAR, EAR, fat jar, or the like. </p></section><section>
-<h3>How do I use the optional tag?</h3>
-<p>A dependency is declared optional by setting the <code><optional></code> element to true in its dependency declaration:</p>
-<div class="source"><pre class="prettyprint linenums">
+<h4>Why use optional dependencies?</h4>
+<p>Optional dependencies save space and memory. They prevent problematic jars that violate a license agreement or cause classpath issues from being bundled into a WAR, EAR, fat jar, or the like.</p></section><section>
+<h4>How do I use the optional tag?</h4>
+<p>A dependency is declared optional by setting the <code>\<optional\></code> element to true in its dependency declaration:</p>
+
+<div class="source"><pre class="prettyprint linenums"><code>
<project>
...
<dependencies>
@@ -172,25 +191,29 @@
</dependency>
</dependencies>
</project>
-</pre></div></section><section>
-<h3>How do optional dependencies work?</h3>
-<div>
-<pre>
+
+</code></pre></div></section><section>
+<h4>How do optional dependencies work?</h4>
+
+<div class="source"><pre class="prettyprint linenums"><code>
Project-A -> Project-B
-</pre></div>
+
+</code></pre></div>
<p>The diagram above says that Project-A depends on Project-B. When A declares B as an optional dependency in its POM, this relationship remains unchanged. It's just like a normal build where Project-B will be added in Project-A's classpath.</p>
-<div>
-<pre>
+
+<div class="source"><pre class="prettyprint linenums"><code>
Project-X -> Project-A
-</pre></div>
+
+</code></pre></div>
<p>When another project (Project-X) declares Project-A as a dependency in its POM, the optional nature of the dependency takes effect. Project-B is not included in the classpath of Project-X. You need to declare it directly in the POM of Project X for B to be included in X's classpath.</p></section><section>
-<h3>Example</h3>
-<p>Suppose there is a project named <i>X2</i> that has similar functionality to <i>Hibernate</i>. It supports many databases such as MySQL, PostgreSQL, and several versions of Oracle. Each supported database requires an additional dependency on a driver jar. All of these dependencies are needed at compile time to build X2. However your project only uses one specific database and doesn't need drivers for the others. X2 can declare these dependencies as optional, so that when your project declares X2 as a direct dependency in its POM, all the drivers supported by the X2 are not automatically included in your project's classpath. Your project will have to include an explicit dependency on the specific driver for the one database it does use.</p></section></section><section>
-<h2>Dependency Exclusions</h2>
-<p>Since Maven resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath. For example, a certain older jar may have security issues or be incompatible with the Java version you're using. To address this, Maven allows you to exclude specific dependencies. Exclusions are set on a specific dependency in your POM, and are targeted at a specific groupId and artifactId. When you build your project, that artifact will not be added to your project's classpath <i>by way of the dependency in which the exclusion was declared</i>.</p><section>
-<h3>How to use dependency exclusions</h3>
-<p>Add an <code><exclusions></code> element in the <code><dependency></code> element by which the problematic jar is included.</p>
-<div class="source"><pre class="prettyprint linenums">
+<h4>Example</h4>
+<p>Suppose there is a project named <em>X2</em> that has similar functionality to <em>Hibernate</em>. It supports many databases such as MySQL, PostgreSQL, and several versions of Oracle. Each supported database requires an additional dependency on a driver jar. All of these dependencies are needed at compile time to build X2. However your project only uses one specific database and doesn't need drivers for the others. X2 can declare these dependencies as optional, so that when your project declares X2 as a direct dependency in its POM, all the drivers supported by the X2 are not automatically included in your project's classpath. Your project will have to include an explicit dependency on the specific driver for the one database it does use.</p></section></section><section>
+<h3>Dependency Exclusions</h3>
+<p>Since Maven resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath. For example, a certain older jar may have security issues or be incompatible with the Java version you're using. To address this, Maven allows you to exclude specific dependencies. Exclusions are set on a specific dependency in your POM, and are targeted at a specific groupId and artifactId. When you build your project, that artifact will not be added to your project's classpath <em>by way of the dependency in which the exclusion was declared</em>.</p><section>
+<h4>How to use dependency exclusions</h4>
+<p>Add an <code>\<exclusions\></code> element in the <code>\<dependency\></code> element by which the problematic jar is included.</p>
+
+<div class="source"><pre class="prettyprint linenums"><code>
<project>
...
<dependencies>
@@ -208,29 +231,35 @@ Project-X -> Project-A
</dependency>
</dependencies>
</project>
-</pre></div></section><section>
-<h3>How dependency exclusion works and when to use it <b>( as a last resort! )</b></h3>
-<div>
-<pre>
+
+</code></pre></div></section><section>
+<h4>How dependency exclusion works and when to use it <strong>( as a last resort! )</strong></h4>
+
+<div class="source"><pre class="prettyprint linenums"><code>
Project-A
-> Project-B
-> Project-D <! -- This dependency should be excluded -->
-> Project-E
-> Project-F
-> Project C
-</pre></div>
+
+</code></pre></div>
<p>The diagram shows that Project-A depends on both Project-B and C. Project-B depends on Project-D. Project-D depends on both Project-E and F. By default, Project A's classpath will include:</p>
-<div>
-<pre>B, C, D, E, F</pre></div>
-<p>Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D <code><optional>true</optional></code>:</p>
-<div class="source"><pre class="prettyprint linenums"><dependency>
+
+<div class="source"><pre class="prettyprint linenums"><code>B, C, D, E, F
+</code></pre></div>
+<p>Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D <code>\<optional\>true\</optional\></code>:</p>
+
+<div class="source"><pre class="prettyprint linenums"><code><dependency>
<groupId>sample.ProjectD</groupId>
<artifactId>ProjectD</artifactId>
<version>1.0-SNAPSHOT</version>
<optional>true</optional>
-</dependency></pre></div>
+</dependency>
+</code></pre></div>
<p>Unfortunately, they didn't. As a last resort, you can exclude it on your own POM for Project-A like this:</p>
-<div class="source"><pre class="prettyprint linenums">
+
+<div class="source"><pre class="prettyprint linenums"><code>
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>sample.ProjectA</groupId>
@@ -252,34 +281,39 @@ Project-A
</dependency>
</dependencies>
</project>
-</pre></div>
+
+</code></pre></div>
<p>If you deploy Project-A to a repository, and Project-X declares a normal dependency on Project-A, will Project-D still be excluded from the classpath?</p>
-<div>
-<pre>
+
+<div class="source"><pre class="prettyprint linenums"><code>
Project-X -> Project-A
-</pre></div>
-<p>The answer is <b>Yes</b>. Project-A has declared that it doesn't need Project-D to run, so it won't be brought in as a transitive dependency of Project-A. </p>
+
+</code></pre></div>
+<p>The answer is <strong>Yes</strong>. Project-A has declared that it doesn't need Project-D to run, so it won't be brought in as a transitive dependency of Project-A.</p>
<p>Now, consider that Project-X depends on Project-Y, as in the diagram below:</p>
-<div>
-<pre>
+
+<div class="source"><pre class="prettyprint linenums"><code>
Project-X -> Project-Y
-> Project-B
-> Project-D
...
-</pre></div>
-<p>Project-Y also has a dependency on Project-B, and it does need the features supported by Project-D. Therefore, it will NOT place an exclusion on Project-D in its dependency list. It may also supply an additional repository, from which it can resolve Project-E. In this case, it's important that Project-D <b>is not</b> excluded globally, since it is a legitimate dependency of Project-Y. </p>
+
+</code></pre></div>
+<p>Project-Y also has a dependency on Project-B, and it does need the features supported by Project-D. Therefore, it will NOT place an exclusion on Project-D in its dependency list. It may also supply an additional repository, from which it can resolve Project-E. In this case, it's important that Project-D <strong>is not</strong> excluded globally, since it is a legitimate dependency of Project-Y.</p>
<p>As another scenario, suppose the dependency you don't want is Project-E instead of Project-D. How do you exclude it? See the diagram below:</p>
-<div>
-<pre>
+
+<div class="source"><pre class="prettyprint linenums"><code>
Project-A
-> Project-B
-> Project-D
-> Project-E <!-- Exclude this dependency -->
-> Project-F
-> Project C
-</pre></div>
-<p>Exclusions work on the entire dependency graph below the point where they are declared. If you want to exclude Project-E instead of Project-D, simply change the exclusion to point at Project-E, but you don't move the exclusion down to Project-D. You cannot change Project-D's POM. If you could, you would use optional dependencies instead of exclusions, or split Project-D up into multiple subprojects, each with nothing but normal dependencies. </p>
-<div class="source"><pre class="prettyprint linenums">
+
+</code></pre></div>
+<p>Exclusions work on the entire dependency graph below the point where they are declared. If you want to exclude Project-E instead of Project-D, simply change the exclusion to point at Project-E, but you don't move the exclusion down to Project-D. You cannot change Project-D's POM. If you could, you would use optional dependencies instead of exclusions, or split Project-D up into multiple subprojects, each with nothing but normal dependencies.</p>
+
+<div class="source"><pre class="prettyprint linenums"><code>
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>sample.ProjectA</groupId>
@@ -301,10 +335,11 @@ Project-A
</dependency>
</dependencies>
</project>
-</pre></div></section><section>
-<h3>Why exclusions are made on a per-dependency basis, rather than at the POM level</h3>
+
+</code></pre></div></section><section>
+<h4>Why exclusions are made on a per-dependency basis, rather than at the POM level</h4>
<p>This is mainly to be sure the dependency graph is predictable, and to keep inheritance effects from excluding a dependency that should not be excluded. If you get to the method of last resort and have to put in an exclusion, you should be absolutely certain which of your dependencies is bringing in that unwanted transitive dependency.</p>
-<p>If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the <a href="/enforcer/enforcer-rules/bannedDependencies.html">banned dependencies rule</a> can be configured to fail the build if a problematic dependency is found. When the build fails, you'll need to add specific exclusions on each path the enforcer finds. </p></section></section></section>
+<p>If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the <a href="/enforcer/enforcer-rules/bannedDependencies.html">banned dependencies rule</a> can be configured to fail the build if a problematic dependency is found. When the build fails, you'll need to add specific exclusions on each path the enforcer finds.</p></section></section></section></section>
</main>
</div>
</div>
Modified: maven/website/content/guides/introduction/introduction-to-plugin-prefix-mapping.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-plugin-prefix-mapping.html (original)
+++ maven/website/content/guides/introduction/introduction-to-plugin-prefix-mapping.html Thu Feb 9 00:34:05 2023
@@ -2,7 +2,7 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/introduction/introduction-to-plugin-prefix-mapping.md at 2023-02-09
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
@@ -48,8 +48,8 @@
<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 ">Introduction to Plugin Prefix Resolution <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-plugin-prefix-mapping.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-08</li>
+ <li class="active ">Introduction to Plugin Prefix Resolution <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/introduction/introduction-to-plugin-prefix-mapping.md"><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-09</li>
<li class="pull-right"><span class="divider">|</span>
<a href="../../scm.html" title="Get Sources">Get Sources</a></li>
<li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li>
@@ -141,18 +141,41 @@
</div>
</header>
<main id="bodyColumn" class="span10" >
-<section>
-<h1>Introduction to Plugin Prefix Resolution</h1>
-<p>When you execute Maven using a standard lifecycle phase, resolving the plugins that participate in that lifecycle is a relatively simple process. However, when you directly invoke a mojo from the command line, as in the case of <b>clean</b>, Maven must have some way of reliably resolving the <b>clean</b> plugin prefix to the <b>maven-clean-plugin</b>. This provides brevity for command-line invocations, while preserving the descriptiveness of the plugin's real artifactId.</p>
+<!--
+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>Introduction to Plugin Prefix Resolution</h2>
+<p>When you execute Maven using a standard lifecycle phase, resolving the plugins that participate in that lifecycle is a relatively simple process. However, when you directly invoke a mojo from the command line, as in the case of <strong>clean</strong>, Maven must have some way of reliably resolving the <strong>clean</strong> plugin prefix to the <strong>maven-clean-plugin</strong>. This provides brevity for command-line invocations, while preserving the descriptiveness of the plugin's real artifactId.</p>
<p>To complicate matters even more, not all plugins should be forced to have the same groupId in the repository. Since groupIds are presumed to be controlled by one project, and multiple projects may release plugins for Maven, it follows that plugin-prefix mappings must also accommodate multiple plugin groupIds.</p>
<p>To address these concerns, Maven provides a new piece of repository-level metadata (not associated with any single artifact) for plugin groups, along with a plugin mapping manager to organize multiple plugin groups and provide search functionality.</p><section>
-<h2>Specifying a Plugin's Prefix</h2>
-<p>In order to give users a convenient prefix with which to reference your plugin a prefix must be associated with your plugin when it is built. By default, Maven will make a guess at the plugin-prefix to be used, by removing any instances of "maven" or "plugin" surrounded by hyphens in the plugin's artifact ID. The conventional artifact ID formats to use are:</p>
+<h3>Specifying a Plugin's Prefix</h3>
+<p>In order to give users a convenient prefix with which to reference your plugin a prefix must be associated with your plugin when it is built. By default, Maven will make a guess at the plugin-prefix to be used, by removing any instances of “maven” or “plugin” surrounded by hyphens in the plugin's artifact ID. The conventional artifact ID formats to use are:</p>
<ul>
-<li><code>maven-${prefix}-plugin</code> - for official plugins maintained by the Apache Maven team itself (you <b>must not</b> use this naming pattern for your plugin, see <a href="../plugin/guide-java-plugin-development.html#Plugin_Naming_Convention_and_Apache_Maven_Trademark">this note for more informations</a>)</li>
-<li><code>${prefix}-maven-plugin</code> - for plugins from other sources</li></ul>
+
+<li>
+<p><code>maven-$\{prefix\}-plugin</code> - for official plugins maintained by the Apache Maven team itself (you <strong>must not</strong> use this naming pattern for your plugin, see <a href="../plugin/guide-java-plugin-development.html#Plugin_Naming_Convention_and_Apache_Maven_Trademark">this note for more informations</a>)</p></li>
+<li>
+<p><code>$\{prefix\}-maven-plugin</code> - for plugins from other sources</p></li>
+</ul>
<p>If your plugin's artifactId fits this pattern, Maven will automatically map your plugin to the correct prefix in the metadata stored within your plugin's groupId path on the repository. However, if you want to customize the prefix used to reference your plugin, you can specify the prefix directly through a configuration parameter on the <code>maven-plugin-plugin</code> in your plugin's POM:</p>
-<div class="source"><pre class="prettyprint linenums"><project>
+
+<div class="source"><pre class="prettyprint linenums"><code><project>
...
<build>
...
@@ -168,34 +191,42 @@
</plugin>
</plugins>
</build>
-</project></pre></div>
-<p>The above configuration will allow users to refer to your plugin by the prefix <b>somePrefix</b>, as in the following example:</p>
-<div>
-<pre>mvn somePrefix:goal</pre></div></section><section>
-<h2>Mapping Prefixes to Plugins</h2>
+</project>
+</code></pre></div>
+<p>The above configuration will allow users to refer to your plugin by the prefix <strong>somePrefix</strong>, as in the following example:</p>
+
+<div class="source"><pre class="prettyprint linenums"><code>mvn somePrefix:goal
+</code></pre></div></section><section>
+<h3>Mapping Prefixes to Plugins</h3>
<p>For each groupId configured for searching, Maven will:</p>
-<ol style="list-style-type: decimal">
-<li>Download <code>maven-metadata.xml</code> from each remote repository into the local repository, and name it <code>maven-metadata-${repoId}.xml</code> within the path of ${groupId}.</li>
-<li>Load these metadata files, along with <code>maven-metadata-local.xml</code> (if it exists), within the path of ${groupId}. Merge them.</li>
-<li>Lookup the plugin prefix in the merged metadata. If it's mapped, it should refer to a concrete groupId-artifactId pair. Otherwise, go on to #1 for the next groupId in the user's plugin-groups.</li></ol>
-<p>These metadata files consist of the <b>groupId</b> it represents (for clarity when the file is opened outside the context of the directory), and a group of <b>plugin</b> elements. Each <b>plugin</b> in this list contains a <b>prefix</b> element denoting the plugin's command-line prefix, and an <b>artifactId</b> element, which provides the other side of the prefix mapping and provides enough information to lookup and use the plugin. When a plugin is installed or deployed, the appropriate metadata file is located - and if the prefix mapping is missing - modified to include the plugin-prefix mapping.</p></section><section>
-<h2>Configuring Maven to Search for Plugins</h2>
-<p>By default, Maven will search the groupId <b>org.apache.maven.plugins</b> for prefix-to-artifactId mappings for the plugins it needs to perform a given build. However, as previously mentioned, the user may have a need for third-party plugins. Since the Maven project is assumed to have control over the default plugin groupId, this means configuring Maven to search other groupId locations for plugin-prefix mappings.</p>
-<p>As it turns out, this is simple. In the Maven settings file (per-user: <code>${user.home}/.m2/settings.xml</code>; global: <code>${maven.home}/conf/settings.xml</code>), you can provide a custom <b>pluginGroups</b> section, listing the plugin groupIds you want to search (each groupId goes in its own <b>pluginGroup</b> sub-element). For example, if my project uses a Modello model file, I might have the following in my settings:</p>
-<div class="source"><pre class="prettyprint linenums"><pluginGroups>
+<p>1 Download <code>maven-metadata.xml</code> from each remote repository into the local repository, and name it <code>maven-metadata-$\{repoId\}.xml</code> within the path of ${groupId}.</p>
+<p>1 Load these metadata files, along with <code>maven-metadata-local.xml</code> (if it exists), within the path of ${groupId}. Merge them.</p>
+<p>1 Lookup the plugin prefix in the merged metadata. If it's mapped, it should refer to a concrete groupId-artifactId pair. Otherwise, go on to #1 for the next groupId in the user's plugin-groups.</p>
+<p>These metadata files consist of the <strong>groupId</strong> it represents (for clarity when the file is opened outside the context of the directory), and a group of <strong>plugin</strong> elements. Each <strong>plugin</strong> in this list contains a <strong>prefix</strong> element denoting the plugin's command-line prefix, and an <strong>artifactId</strong> element, which provides the other side of the prefix mapping and provides enough information to lookup and use the plugin. When a plugin is installed or deployed, the appropriate metadata file is located - and if the prefix mapping is missing - modified to include the plugin-prefix mapping.</p></section><section>
+<h3>Configuring Maven to Search for Plugins</h3>
+<p>By default, Maven will search the groupId <strong>org.apache.maven.plugins</strong> for prefix-to-artifactId mappings for the plugins it needs to perform a given build. However, as previously mentioned, the user may have a need for third-party plugins. Since the Maven project is assumed to have control over the default plugin groupId, this means configuring Maven to search other groupId locations for plugin-prefix mappings.</p>
+<p>As it turns out, this is simple. In the Maven settings file (per-user: <code>$\{user.home\}/.m2/settings.xml</code>; global: <code>$\{maven.home\}/conf/settings.xml</code>), you can provide a custom <strong>pluginGroups</strong> section, listing the plugin groupIds you want to search (each groupId goes in its own <strong>pluginGroup</strong> sub-element). For example, if my project uses a Modello model file, I might have the following in my settings:</p>
+
+<div class="source"><pre class="prettyprint linenums"><code><pluginGroups>
<pluginGroup>org.codehaus.modello</pluginGroup>
-</pluginGroups></pre></div>
+</pluginGroups>
+</code></pre></div>
<p>This allows me to execute the following, which will generate Java classes from the model:</p>
-<div>
-<pre>mvn -Dversion=4.0.0 -Dmodel=maven.mdo modello:java</pre></div>
-<p>Maven will always search the following groupId's <b>after</b> searching any plugin groups specified in the user's settings:</p>
+
+<div class="source"><pre class="prettyprint linenums"><code>mvn -Dversion=4.0.0 -Dmodel=maven.mdo modello:java
+</code></pre></div>
+<p>Maven will always search the following groupId's <strong>after</strong> searching any plugin groups specified in the user's settings:</p>
<ul>
-<li>org.apache.maven.plugins</li>
-<li>org.codehaus.mojo</li></ul>
-<p><b>NOTE:</b> When specifying plugin groups to be used in searching for a prefix mapping, order is critical! By specifying a pluginGroup of <code>com.myco.plugins</code> with a prefix of <code>clean</code>, I can override the usage of the <code>maven-clean-plugin</code> when <code>clean:clean</code> is invoked.</p>
-<p><b>NOTE2:</b> For more information on <code>settings.xml</code>, see [<a href="#a1">1</a>].</p></section><section>
-<h2>Resources</h2>
-<p><a id="a1">1</a> <a href="../mini/guide-configuring-maven.html">Guide to Configuring Maven</a></p></section></section>
+
+<li>
+<p>org.apache.maven.plugins</p></li>
+<li>
+<p>org.codehaus.mojo</p></li>
+</ul>
+<p><strong>NOTE:</strong> When specifying plugin groups to be used in searching for a prefix mapping, order is critical! By specifying a pluginGroup of <code>com.myco.plugins</code> with a prefix of <code>clean</code>, I can override the usage of the <code>maven-clean-plugin</code> when <code>clean:clean</code> is invoked.</p>
+<p><strong>NOTE2:</strong> For more information on <code>settings.xml</code>, see [<a href="a1">1</a>].</p></section><section>
+<h3>Resources</h3>
+<p>1 <a href="../mini/guide-configuring-maven.html">Guide to Configuring Maven</a></p></section></section></section>
</main>
</div>
</div>
Modified: maven/website/content/guides/introduction/introduction-to-plugins.html
==============================================================================
--- maven/website/content/guides/introduction/introduction-to-plugins.html (original)
+++ maven/website/content/guides/introduction/introduction-to-plugins.html Thu Feb 9 00:34:05 2023
@@ -2,7 +2,7 @@
<!--
- | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/apt/guides/introduction/introduction-to-plugins.apt at 2023-02-08
+ | Generated by Apache Maven Doxia Site Renderer 2.0.0-M4 from content/markdown/guides/introduction/introduction-to-plugins.md at 2023-02-09
| Rendered using Apache Maven Fluido Skin 1.11.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
@@ -48,8 +48,8 @@
<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 ">Introduction to Maven Plugin Development <a href="https://github.com/apache/maven-site/tree/master/content/apt/guides/introduction/introduction-to-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-08</li>
+ <li class="active ">Introduction to Maven Plugin Development <a href="https://github.com/apache/maven-site/tree/master/content/markdown/guides/introduction/introduction-to-plugins.md"><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-09</li>
<li class="pull-right"><span class="divider">|</span>
<a href="../../scm.html" title="Get Sources">Get Sources</a></li>
<li class="pull-right"><a href="../../download.cgi" title="Download">Download</a></li>
@@ -136,22 +136,39 @@
</div>
</header>
<main id="bodyColumn" class="span10" >
-<section>
-<h1>Introduction to Maven Plugin Development</h1>
+<!--
+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>Introduction to Maven Plugin Development</h2>
<p>Maven consists of a core engine which provides basic project-processing capabilities and build-process management, and a host of plugins which are used to execute the actual build tasks.</p><section>
-<h2>What is a Plugin?</h2>
-<p>"Maven" is really just a core framework for a collection of Maven Plugins. In other words, plugins are where much of the real action is performed, plugins are used to: create jar files, create war files, compile code, unit test code, create project documentation, and on and on. Almost any action that you can think of performing on a project is implemented as a Maven plugin.</p>
-<p>Plugins are the central feature of Maven that allow for the reuse of common build logic across multiple projects. They do this by executing an "action" (i.e. creating a WAR file or compiling unit tests) in the context of a project's description - the Project Object Model (POM). Plugin behavior can be customized through a set of unique parameters which are exposed by a description of each plugin goal (or Mojo).</p>
-<p>One of the simplest plugins in Maven is the Clean Plugin. The <a href="../../plugins/maven-clean-plugin/">Maven Clean plugin</a> (maven-clean-plugin) is responsible for removing the target directory of a Maven project. When you run "mvn clean", Maven executes the "clean" goal as defined in the Clean plug-in, and the target directory is removed. The Clean plugin <a href="../../plugins/maven-clean-plugin/clean-mojo.html">defines a parameter</a> which can be used to customize plugin behavior, this parameter is called outputDirectory and it defaults to ${project.build.directory}.</p></section><section>
-<h2>What is a Mojo (<i>And Why the H--- is it Named 'Mojo'</i>)?</h2>
-<p>A Mojo is really just a <b>goal</b> in Maven, and plug-ins consist of any number of goals (Mojos). Mojos can be defined as annotated Java classes or Beanshell script. A Mojo specifies metadata about a goal: a goal name, which phase of the lifecycle it fits into, and the parameters it is expecting.</p>
-<p>MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for "Plain". Mojo is also an interesting word (see <a class="externalLink" href="http://www.answers.com/mojo&r=67">definition</a>). From <a class="externalLink" href="http://www.wikipedia.org">Wikipedia</a>, a "mojo" is defined as: "...a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc."</p></section><section>
-<h2>What is the Build Lifecycle? (Overview)</h2>
-<p>The build lifecycle is a series of common <b>stage</b>s through which all project builds naturally progress. Plugin goals are bound to specific stages in the lifecycle.</p></section></section><section>
-<h1>Resources</h1>
-<ol style="list-style-type: decimal">
-<li><a href="/plugin-developers/index.html">Plugin Development Center</a></li>
-<li><a href="../mini/guide-configuring-plugins.html">Configuring plugins</a></li></ol></section>
+<h3>What is a Plugin?</h3>
+<p>“Maven” is really just a core framework for a collection of Maven Plugins. In other words, plugins are where much of the real action is performed, plugins are used to: create jar files, create war files, compile code, unit test code, create project documentation, and on and on. Almost any action that you can think of performing on a project is implemented as a Maven plugin.</p>
+<p>Plugins are the central feature of Maven that allow for the reuse of common build logic across multiple projects. They do this by executing an “action” (i.e. creating a WAR file or compiling unit tests) in the context of a project's description - the Project Object Model (POM). Plugin behavior can be customized through a set of unique parameters which are exposed by a description of each plugin goal (or Mojo).</p>
+<p>One of the simplest plugins in Maven is the Clean Plugin. The <a href="../../plugins/maven-clean-plugin/">Maven Clean plugin</a> (maven-clean-plugin) is responsible for removing the target directory of a Maven project. When you run “mvn clean”, Maven executes the “clean” goal as defined in the Clean plug-in, and the target directory is removed. The Clean plugin <a href="../../plugins/maven-clean-plugin/clean-mojo.html">defines a parameter</a> which can be used to customize plugin behavior, this parameter is called outputDirectory and it defaults to ${project.build.directory}.</p></section><section>
+<h3>What is a Mojo (<em>And Why the H— is it Named ‘Mojo’</em>)?</h3>
+<p>A Mojo is really just a <strong>goal</strong> in Maven, and plug-ins consist of any number of goals (Mojos). Mojos can be defined as annotated Java classes or Beanshell script. A Mojo specifies metadata about a goal: a goal name, which phase of the lifecycle it fits into, and the parameters it is expecting.</p>
+<p>MOJO is a play on POJO (Plain-old-Java-object), substituting “Maven” for “Plain”. Mojo is also an interesting word (see <a href="http://www.answers.com/mojo&r=67" class="externalLink">definition</a>). From <a href="http://www.wikipedia.org" class="externalLink">Wikipedia</a>, a “mojo” is defined as: “…a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc.”</p></section><section>
+<h3>What is the Build Lifecycle? (Overview)</h3>
+<p>The build lifecycle is a series of common <strong>stage</strong>s through which all project builds naturally progress. Plugin goals are bound to specific stages in the lifecycle.</p></section></section><section>
+<h2>Resources</h2>
+<p>1 <a href="/plugin-developers/index.html">Plugin Development Center</a></p>
+<p>1 <a href="../mini/guide-configuring-plugins.html">Configuring plugins</a></p></section></section>
</main>
</div>
</div>