From 3f2362e528996bd65d4bd9cf2aaf668266aeba8b Mon Sep 17 00:00:00 2001 From: John Dennis Casey Date: Sat, 30 Jul 2005 04:16:21 +0000 Subject: [PATCH] Adding doco on plugin registry. git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@226471 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/site/apt/plugin-registry-overview.apt | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 maven-site/src/site/apt/plugin-registry-overview.apt diff --git a/maven-site/src/site/apt/plugin-registry-overview.apt b/maven-site/src/site/apt/plugin-registry-overview.apt new file mode 100644 index 0000000000..6b3078b0ea --- /dev/null +++ b/maven-site/src/site/apt/plugin-registry-overview.apt @@ -0,0 +1,193 @@ + --- + Plugin Registry Overview + --- + John Casey + --- + 29-July-2005 + --- + +Plugin Registry Overview + +* Introduction + + The Maven 2 plugin registry (~/.m2/plugin-registry.xml) is a mechanism to + help the user exert some control over their build environment. Rather than + simply fetching the latest version of every plugin used in a given build, + this registry allows the user to peg a plugin to a particular version, and + only update to newer versions under certain restricted circumstances. There + are various ways to configure or bypass this feature, and the feature itself + can be managed on either a per-user or global level. + +* A Tour of plugin-registry.xml + + The plugin registry file (per-user: ~/.m2/plugin-registry.xml, global: + $M2_HOME/conf/plugin-registry.xml) contains a set of plugin-version + registrations, along with some configuration parameters for the registry + itself. + + Currently, the plugin registry supports configuration options for the + following: + + * <> - Determines how often (or whether) the registered + plugins are checked for updates. + + Combined with the <> plugin attribute, this determines whether + a particular plugin will be checked for updates during a given build. Valid + settings are: never, always, and interval:TTT (TTT is a short specification + for a time interval, which follows the pattern /([0-9]+[wdhm])+/). Intervals + are specified down to the minute resolution. An example of an interval + specification might be: + + <<>> (check every 4 weeks, 2 hours, and 30 minutes) + + * <> - Specifies whether the user should be prompted before + registering plugin-version updates. This is a boolean value, accepting + true/false. + + * <> - Specifies whether the LATEST artifact metadata should + be consulted while determining versions for plugins. + + LATEST metadata is always published when a plugin is installed or deployed + to a repository, and so will always reference the newest copy of the plugin, + regardless of whether this is a snapshot version or not. + + Registered plugins will currently only ever be updated with the + results of RELEASE metadata resolution. + + Obviously, the plugin registry also contains information about resolved plugin + versions. The following information is tracked for each registered plugin: + + * <> - The plugin's group id. + + * <> - The plugin's artifact id. + + * <> - The timestamp from the last time updates were checked for + this plugin. + + * <> - The currently registered version for this plugin. This is + the version Maven will use when executing this plugin's mojos. + + * <> - A list of versions discovered for this plugin which + have been rejected by the user. This keeps Maven from continually prompting + the user to update a given plugin to the same new version. + +* Using (or not) the Plugin Registry + + There are many ways you can override the default plugin registry settings. + Often, this will be desirable for a single, one-off build of a project that + deviates from your normal environment configuration. However, before discussing + these options, it's important to understand how the plugin registry resolves + versions for unregistered plugins, along with plugins in need of an update + check. + +** Resolving Plugin Versions + + The plugin registry uses a relatively straightforward algorithm for resolving + plugin versions. However, considerations for when to check, when to prompt the + user, and when to persist resolved plugin versions complicate this + implementation considerably. In general, plugin versions are resolved using a + four-step process: + + [[1]] Check for a plugin configuration in the MavenProject instance. Any + plugin configuration found in the MavenProject is treated as authoritative, + and will stop the plugin-version resolution/persistence process when + found. + + [[2]] If the plugin registry is enabled, check it for an existing registered + version. If the plugin has been registered, a combination of the + updateInterval configuration and the lastChecked attribute (on the + plugin) determine whether the plugin needs to be checked for updates. + If the plugin doesn't need an update check, the registered version is + used. + + If the plugin is due for an update check, the plugin-artifact's RELEASE + metadata is resolved. Resolution of this metadata may trigger a prompt + to notify the user of the new version, and/or persistence of the new + version in the registry. If the update is performed, the lastChecked + attribute is updated to reflect this. + + [[3]] the <> configuration is set to <<>>, or the + <<<'--check-plugin-latest'>>> CLI option (discussed later) is + provided, then the LATEST artifact metadata is resolved for the plugin. + + If this metadata is resolved successfully, that version is used. + This may trigger a prompt to ask the user whether to register the + plugin, and a successive persistence step for the new plugin version. + + [[4]] If the version still has not been resolved, RELEASE artifact + metadata is checked for the plugin. If this metadata resolves + successfully, it is the version used. This may also trigger a prompt + to ask the user whether to register the plugin, and a persistence step + registering the new plugin version. + + I've alluded to prompting the user and persisting the plugin version into + the registry. Now, let's examine the circumstances under which these steps + actually take place. + + There are two cases where the user may be prompted to change the plugin + registry; when the plugin is not registered, and when the plugin is registered, + but an updated version is discovered. By default, the user is prompted to save + the resolved version for each plugin, with the option of specifying that a + decision should be remembered and applied to all (either yes to all, or no + to all) plugins registry updates. However, it is also possible to bypass + this behavior in the following ways: + + * Specify <> == <<>> in the plugin-registry.xml. This + configuration parameter means that the user is not prompted, and all + updated/discovered versions are to be persisted. + + * Specify <<<'--batch-mode'>>> (or <<<'-B'>>>) from the command line. + This functions in the same way as the <> config parameter + above. + + * Specify <<<'--no-plugin-updates'>>> | <<<'-npu'>>> from the command line. + This prevents any updates or new registrations from taking place, but + existing plugin versions in the registry will be used when available. + + * Specify <<<'--check-plugin-updates'>>> | <<<'--update-plugins'>>> | + <<<'-up'>>> | <<<'-cpu'>>> (synonyms) from the command line. + + * Specify <<<'--no-plugin-registry'>>> | <<<'-npr'>>> from the command line. + This prevents resolution of plugin versions using the plugin-registry.xml + file. The plugin version will be resolved either from the project or + from the repository in this case. + + * Specify <> == <<>> in the settings.xml. This + configuration parameter will disable use of the plugin registry for the + entire build environment, as opposed to the immediate build execution + (as in the case of the corresponding command line switch above). + + These force all registered plugins to be updated. The user will still + be prompted to approve plugin versions, unless one of the above switches + is also provided. + +** Summary of Command Line Options for the Plugin Registry + + The following summary of command line options is provided for quick reference: + + * <<<--no-plugin-registry>>> - Bypass the plugin registry. + + <<<-npr>>> + + * <<<--no-plugin-latest>>> - Don't check the LATEST artifact metadata when + resolving plugin versions, regardless of the value of <> in + the plugin-registry.xml file. + + <<<-npl>>> + + * <<<--check-plugin-latest>>> - Check the LATEST artifact metadata when + resolving plugin versions, regardless of the value of <> in + the plugin-registry.xml file. + + <<<-cpl>>> + + * <<<--no-plugin-updates>>> - Do not search for updated versions of registered + plugins. Only use the repository to resolve unregistered plugins. + + <<<-npu>>> + + * <<<--check-plugin-updates>>> - Force the plugin version manager to check for + updated versions of any registered plugins, currently using RELEASE metadata + <>. + + <<<--update-plugins>>> <<<-up>>> <<<-cpu>>>