maven-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r344250 - in /maven/site/trunk/src/site/apt/guides/introduction: introduction-to-plugin-prefix-mapping.apt introduction-to-plugin-resolution.apt
Date Mon, 14 Nov 2005 22:19:19 GMT
Author: jdcasey
Date: Mon Nov 14 14:19:14 2005
New Revision: 344250

Adding documentation on plugin resolution. Also, updated doco on plugin-prefix mapping.

  (with props)

Modified: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt
--- maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt
+++ 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
+        a concrete groupId-artifactId pair. Otherwise, go on to #1 for the next groupId in
+        user's plugin-groups.
+  []
+  These metadata files consist of the <<groupId>> it represents (for clarity
   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
-    groupId can be found to match the given prefix>>. This means that I can 
-    develop a third-party plugin that overloads the <<<compiler>>> prefix,
-    will drastically change the build behavior. Prefixes already mapped to the
-    <<org.apache.maven.plugins>> groupId should <<NOT>> be overridden,
-  * <<<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
+  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
+  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>>>
+  <<<clean:clean>>> is invoked.

Added: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt
--- maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-resolution.apt
+++ 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
+  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
+  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
+  resolving plugin information.
+**Resolving <<<groupId>>> and <<<artifactId>>> for a
+  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):
+  ...
+  <usePluginRegistry>true</usePluginRegistry>
+  ...
+        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
+        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.
+  [[{1}]] {{{./introduction-to-plugin-prefix-mapping.html}Introduction to the Plugin Prefix
+  [[{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"

View raw message