--- Introduction to Maven Plugin Resolution --- John Casey --- 2009-08-01 ------ ~~ Licensed to the Apache Software Foundation (ASF) under one ~~ or more contributor license agreements. See the NOTICE file ~~ distributed with this work for additional information ~~ regarding copyright ownership. The ASF licenses this file ~~ to you under the Apache License, Version 2.0 (the ~~ "License"); you may not use this file except in compliance ~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ ~~ Unless required by applicable law or agreed to in writing, ~~ software distributed under the License is distributed on an ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Introduction: How Maven Resolves Plugins *Introduction Starting with 2.0, Maven allows users to execute plugins that have not yet been installed. This new feature eliminates the need to maintain local plugin installations, and provides the implicit ability to instantly take advantage of new plugin releases. However, it also means that plugin information must be resolved at build time, which can be a complex task. This document will detail the mechanism used to resolve plugin information. *Referencing Plugins Maven 2.0 brings with it added flexibility for referencing plugins and their mojos. Since plugin information is determined at build time, plugin prefixes can be ambiguous, and dependent on an individual user's Maven configuration. Therefore, in addition to the original mechanism of referencing a plugin by its shorthand prefix and a goal, Maven can also process plugin and mojo references that concretely specify groupId, artifactId, and optionally, version. Most users will have little difficulty using Maven as before, referencing plugins by their prefix. However, with the introduction of the build lifecycle - and mojo bindings to that lifecycle - it is critical that lifecycle mappings be able to refer to a mojo in an unambiguous way. In fact, when dealing with lifecycle mappings, it's illegal to specify a mojo using its plugin-prefix. This helps Maven avoid the case where the 'jar' lifecycle behaves differently on two users' machines, simply due to their local Maven configurations. As a side effect of this requirement, users also have the option to specify plugins and mojos in this way from the command line. For clarity, the following are the three ways to reference a mojo from the command line. These will all result in the clean mojo of the maven-clean-plugin being invoked: +---+ mvn org.apache.maven.plugins:maven-clean-plugin:2.0:clean mvn org.apache.maven.plugins:maven-clean-plugin:clean mvn clean:clean +---+ By contrast, only the following are valid mojo references from inside a lifecycle mapping definition: +---+ org.apache.maven.plugins:maven-clean-plugin:2.0:clean org.apache.maven.plugins:maven-clean-plugin:clean +---+ <> It's probably bad form to pin a plugin reference to a specific version inside a lifecycle mapping definition, since this prevents the user from taking advantage of plugin updates. *Resolving Plugin Information Since users have the ability to reference a plugin by its groupId and artifactId <> a version, Maven must have the ability to resolve the plugin's version given these other two attributes. However, since users can also refer to a plugin by its prefix, Maven must also have the ability to resolve a plugin by this prefix alone - including resolution of the plugin's version. To handle these two scenarios, Maven employs a two-stage process for resolving plugin information. **Resolving <<>> and <<>> for a Plugin Maven's approach to resolving a plugin's groupId and artifactId given its prefix is actually relatively simple. The user can specify a set of plugin groupId's to be searched. Using repository metadata for each configured groupId, Maven will search for plugin prefix mappings using the process detailed in \[{{{a1}1}}\]. **Resolving a Plugin's Version When a plugin's groupId and artifactId are known, but its version is still unknown, Maven will resolve that plugin's version using a variety of sources. It will check, in order, the following: [[1]] This includes all plugins specified in the \ section; this is intuitive. However, since all plugin specifications in the POM are still generally a better source of information than reverting to external sources, < section will also be searched.>> <> Checking of the \ section is new for Maven 2.0.1. [[2]] This configuration file, usually located in <<>> within the $HOME/.m2 directory, is disabled by default. To enable it, add the following section to the <<>> file (also within $HOME/.m2): +---+ ... true ... +---+ The plugin registry will maintain a mapping of {groupId, artifactId} for a plugin to the version to be used. It will also maintain a record of the last time the plugin was checked for updated versions; the configuration for when to check for updated versions; and a list of rejected versions of the plugin which are not to be used. If an updated version is found which has not yet been rejected, the plugin version manager will ask the user whether to use this version. The user can reject the version for now or always, or accept it for now or always. If prompting is disabled (batch mode), the plugin registry can be configured with a default answer to this question. See \[{{{a2}2}}\] for more information on the plugin registry. See \[{{{a3}3}}\] for more information on the <<>> file. [[3]] This is published each time a Maven plugin is deployed or installed. It is simply a pointer to the latest published version of the plugin. It differs from the SNAPSHOT metadata in that it is always present, regardless of the project's version. If you use the plugin registry, you can disable this check. [[4]] Since the LATEST metadata is always published, it obsoletes this check when #3 is enabled. However, RELEASE metadata checking is still important in order to support legacy plugin-releases, where the LATEST metadata has not been published. This check can also be useful if the LATEST metadata check has been disabled. This might be used instead of LATEST metadata if the user only wants to use supported, released plugin versions. [] If all of the above resolution methods fail, the plugin cannot be located and an exception is thrown, stopping the build. *Resources {1}. {{{./introduction-to-plugin-prefix-mapping.html}Introduction to the Plugin Prefix Mapping}}. {2}. {{{./introduction-to-plugin-registry.html}Introduction to the Plugin Registry}}. {3}. {{{../mini/guide-configuring-maven.html}Guide to Configuring Maven}}