Mailing-List: contact commits-help@maven.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@maven.apache.org
Message-ID: <20051114221921.72085.qmail@minotaur.apache.org>
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
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 -0000
To: commits@maven.apache.org
From: jdcasey@apache.org

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"