mirror of https://github.com/apache/maven.git
Adding doco on plugin registry.
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@226471 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
John Dennis Casey
parent
44abb5383a
commit
3f2362e528
|
|
@ -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:
|
||||||
|
|
||||||
|
* <<updateInterval>> - Determines how often (or whether) the registered
|
||||||
|
plugins are checked for updates.
|
||||||
|
|
||||||
|
Combined with the <<lastChecked>> 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:
|
||||||
|
|
||||||
|
<<<interval:4w2h30m>>> (check every 4 weeks, 2 hours, and 30 minutes)
|
||||||
|
|
||||||
|
* <<autoUpdate>> - Specifies whether the user should be prompted before
|
||||||
|
registering plugin-version updates. This is a boolean value, accepting
|
||||||
|
true/false.
|
||||||
|
|
||||||
|
* <<checkLatest>> - Specifies whether the LATEST artifact metadata should
|
||||||
|
be consulted while determining versions for <unregistered> 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.
|
||||||
|
|
||||||
|
<NOTE:> 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:
|
||||||
|
|
||||||
|
* <<groupId>> - The plugin's group id.
|
||||||
|
|
||||||
|
* <<artifactId>> - The plugin's artifact id.
|
||||||
|
|
||||||
|
* <<lastChecked>> - The timestamp from the last time updates were checked for
|
||||||
|
this plugin.
|
||||||
|
|
||||||
|
* <<useVersion>> - The currently registered version for this plugin. This is
|
||||||
|
the version Maven will use when executing this plugin's mojos.
|
||||||
|
|
||||||
|
* <<rejectedVersions>> - 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]] <If> the <<checkLatest>> configuration is set to <<<true>>>, 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 <<autoUpdate>> == <<<true>>> 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 <<autoUpdate>> 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 <<usePluginRegistry>> == <<<false>>> 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.
|
||||||
|
|
||||||
|
<Synonym:> <<<-npr>>>
|
||||||
|
|
||||||
|
* <<<--no-plugin-latest>>> - Don't check the LATEST artifact metadata when
|
||||||
|
resolving plugin versions, regardless of the value of <<useLatest>> in
|
||||||
|
the plugin-registry.xml file.
|
||||||
|
|
||||||
|
<Synonym:> <<<-npl>>>
|
||||||
|
|
||||||
|
* <<<--check-plugin-latest>>> - Check the LATEST artifact metadata when
|
||||||
|
resolving plugin versions, regardless of the value of <<useLatest>> in
|
||||||
|
the plugin-registry.xml file.
|
||||||
|
|
||||||
|
<Synonym:> <<<-cpl>>>
|
||||||
|
|
||||||
|
* <<<--no-plugin-updates>>> - Do not search for updated versions of registered
|
||||||
|
plugins. Only use the repository to resolve unregistered plugins.
|
||||||
|
|
||||||
|
<Synonym:> <<<-npu>>>
|
||||||
|
|
||||||
|
* <<<--check-plugin-updates>>> - Force the plugin version manager to check for
|
||||||
|
updated versions of any registered plugins, currently using RELEASE metadata
|
||||||
|
<<only>>.
|
||||||
|
|
||||||
|
<Synonyms:> <<<--update-plugins>>> <<<-up>>> <<<-cpu>>>
|
||||||
Loading…
Reference in New Issue