You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jd...@apache.org on 2005/11/14 23:19:19 UTC
svn commit: r344250 - in /maven/site/trunk/src/site/apt/guides/introduction:
introduction-to-plugin-prefix-mapping.apt
introduction-to-plugin-resolution.apt
Author: jdcasey
Date: Mon Nov 14 14:19:14 2005
New Revision: 344250
URL: http://svn.apache.org/viewcvs?rev=344250&view=rev
Log:
Adding documentation on plugin resolution. Also, updated doco on plugin-prefix mapping.
Added:
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt (with props)
Modified:
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt
Modified: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt
URL: http://svn.apache.org/viewcvs/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt?rev=344250&r1=344249&r2=344250&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt (original)
+++ maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt Mon Nov 14 14:19:14 2005
@@ -29,17 +29,28 @@
* Mapping Prefixes to Plugins
- Quite simply, for each group of plugins in the Maven repository
- (distinguished by a common groupId), there exists a metadata file called
- <<<plugins.xml>>>. This file consists of the <<groupId>> (for clarity when
+ For each groupId configured for searching, Maven will:
+
+ [[1]] Download <<<maven-metadata.xml>>> from each remote repository into the local repository,
+ and name it <<<maven-metadata-${repoId}.xml>>> within the path of ${groupId}.
+
+ [[2]] Load these metadata files, along with <<<maven-metadata-local.xml>>> (if it exists),
+ within the path of ${groupId}. Merge them.
+
+ [[3]] 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.
+
+ []
+
+ These metadata files consist of the <<groupId>> it represents (for clarity when
the file is opened outside the context of the directory), and a group of
<<plugin>> elements. Each <<plugin>> in this list contains a <<prefix>>
element denoting the plugin's command-line prefix, and an <<artifactId>>
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, this metadata file is resolved and if necessary, the prefix
- mapping for the plugin is updated. In the case of deployment, this metadata
- file is persisted to the remote repository.
+ or deployed, the appropriate metadata file is located - and if the prefix
+ mapping is missing - modified to include the plugin-prefix mapping.
* Configuring Maven to Search for Plugins
@@ -70,38 +81,16 @@
mvn -Dversion=4.0.0 -Dmodel=maven.mdo modello:java
+---+
- Adding <<org.codehaus.modello>> to the list of groupIds searched for plugin
- prefixes will automatically import all of the modello maven plugins, but it
- <<will not>> block the import of plugins from the <<org.apache.maven.plugins>>
- group - this plugin groupId is always the default, and cannot be suppressed.
-
-* Current Quirks
-
- The following list of items are on the table to be listed as bugs, and fixed.
- They currently amount to quirks in the prefix resolution process.
-
- * The <<org.apache.maven.plugins>> groupId is only used if <<no other plugin
- groupId can be found to match the given prefix>>. This means that I can
- develop a third-party plugin that overloads the <<<compiler>>> prefix, which
- will drastically change the build behavior. Prefixes already mapped to the
- <<org.apache.maven.plugins>> groupId should <<NOT>> be overridden, IMO.
-
- * <<<plugins.xml>>> metadata are resolved from the first repository possible,
- rather than being merged. If two plugin repositories provide plugins in the
- the same groupId, none but the plugins in the first repository can be
- found using plugin-prefix resolution. IMO, this is by design and should not
- change, particularly if we agree that a single project maintains control
- over the groupId in question.
-
- <<NOTE:>> One interesting side-effect of this is that snapshot-capable
- repositories may have subtle interactions with "normal" repositories in this
- respect (with one repository suppressing or being suppressed by the other,
- but both serving the same project/groupId).
-
- * If you are testing a new plugin, and perform an install, the <<<plugins.xml>>>
- for that plugin groupId will only be modified locally. If, at the next build,
- you reference a plugin prefix that is not mapped in the local copy of any
- configured plugin-prefix metadata, these metadata files will be re-resolved
- from the remote repositories. This refresh step will erase the prefix mapping
- for the locally installed plugin, erasing your ability to reference it without
- configuring it explicitly in your <<<pom.xml>>>.
+ Maven will always search the following groupId's <<after>> searching any plugin groups
+ specified in the user's settings:
+
+ * org.apache.maven.plugins
+
+ * org.codehaus.mojo
+
+ []
+
+ <<NOTE:>> When specifying plugin groups to be used in searching for a prefix mapping,
+ order is critical! By specifying a pluginGroup of <<<com.myco.plugins>>> with a prefix
+ of <<<clean>>>, I can override the usage of the <<<maven-clean-plugin>>> when
+ <<<clean:clean>>> is invoked.
Added: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt
URL: http://svn.apache.org/viewcvs/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt?rev=344250&view=auto
==============================================================================
--- maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt (added)
+++ maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt Mon Nov 14 14:19:14 2005
@@ -0,0 +1,145 @@
+ ---
+ Introduction to Maven Plugin Resolution
+ ---
+ John Casey
+ ---
+ 14-Nov-2005
+ ---
+
+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
++---+
+
+ <<NOTE:>> 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 <<without>>
+ 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 <<<groupId>>> and <<<artifactId>>> 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 \[{{{#1}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]] <the project's POM>
+
+ This includes all plugins specified in the \<build\> 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, <<the \<pluginManagement\>
+ section will also be searched.>>
+
+ <<NOTE:>> Checking of the \<pluginManagement\> section is new for Maven 2.0.1.
+
+ [[2]] <the plugin registry>
+
+ This configuration file, usually located in <<<plugin-registry.xml>>> within the
+ $HOME/.m2 directory, is disabled by default. To enable it, add the following
+ section to the <<<settings.xml>>> file (also within $HOME/.m2):
+
++---+
+<settings>
+ ...
+ <usePluginRegistry>true</usePluginRegistry>
+ ...
+</settings>
++---+
+
+ 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 \[{{{#2}2}}\] for more information on the plugin registry.
+
+ [[3]] <LATEST version metadata>
+
+ 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]] <RELEASE version metadata>
+
+ 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}}.
+
+ []
Propchange: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"