Author: vsiveton
Date: Fri Feb 8 03:47:41 2008
New Revision: 619844
URL: http://svn.apache.org/viewvc?rev=619844&view=rev
Log:
o escaped characters: {}
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-plugins.apt
maven/site/trunk/src/site/apt/guides/mini/guide-assemblies.apt
maven/site/trunk/src/site/apt/guides/mini/guide-attached-tests.apt
maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt
maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt
maven/site/trunk/src/site/apt/guides/mini/guide-proxies.apt
Modified:
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugin-prefix-mapping.apt?rev=619844&r1=619843&r2=619844&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
Fri Feb 8 03:47:41 2008
@@ -11,29 +11,29 @@
When you execute Maven using a standard lifecycle phase, resolving the
plugins that participate in that lifecycle is a relatively simple process.
However, when you directly invoke a mojo from the command line, as in the
case
- of <<clean>>, Maven must have some way of reliably resolving the
+ of <<clean>>, Maven must have some way of reliably resolving the
<<clean>> plugin prefix to the <<maven-clean-plugin>>. This provides brevity
for command-line invocations, while preserving the descriptiveness of the
plugin's real artifactId.
- To complicate matters even more, not all plugins should be forced to have
the
+ To complicate matters even more, not all plugins should be forced to have the
same groupId in the repository. Since groupIds are presumed to be controlled
by one project, and multiple projects may release plugins for Maven, it
follows that plugin-prefix mappings must also accommodate multiple plugin
groupIds.
- To address these concerns, Maven provides a new piece of repository-level
+ To address these concerns, Maven provides a new piece of repository-level
metadata (not associated with any single artifact) for plugin groups, along
with a plugin mapping manager to organize multiple plugin groups and provide
search functionality.
-
+
* Specifying a Plugin's Prefix
In order to give users a convenient prefix with which to reference your
plugin
a prefix must be associated with your plugin when it is built. By default,
Maven
will make a guess at the plugin-prefix to be used, by assuming the plugin's
artifactId
fits the pattern:
-
+
+---+
maven-${prefix}-plugin
+---+
@@ -43,7 +43,7 @@
groupId path on the repository. However, if you want to customize the prefix
used to reference your plugin, you can specify the prefix directly through a
configuration parameter on the <<<maven-plugin-plugin>>> in your plugin's
POM:
-
+
+---+
<project>
...
@@ -53,7 +53,7 @@
...
<plugin>
<artifactId>maven-plugin-plugin</artifactId>
-
+
<configuration>
...
<goalPrefix>somePrefix</goalPrefix>
@@ -66,7 +66,7 @@
The above configuration will allow users to refer to your plugin by the
prefix
<<somePrefix>>, as in the following example:
-
+
+---+
mvn somePrefix:goal
+---+
@@ -74,24 +74,24 @@
* Mapping Prefixes to Plugins
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.
-
+
+ [[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
+
+ 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, the appropriate metadata file is located - and if the prefix
mapping is missing - modified to include the plugin-prefix mapping.
@@ -100,16 +100,16 @@
By default, Maven will search the groupId <<org.apache.maven.plugins>>
for prefix-to-artifactId mappings for the plugins it needs to perform a given
- build. However, as previously mentioned, the user may have a need for
+ build. However, as previously mentioned, the user may have a need for
third-party plugins. Since the Maven project is assumed to have control over
the default plugin groupId, this means configuring Maven to search other
groupId locations for plugin-prefix mappings.
- As it turns out, this is simple. In the Maven settings file (per-user:
+ As it turns out, this is simple. In the Maven settings file (per-user:
<<<~/.m2/settings.xml>>>; global: <<<$M2_HOME/conf/settings.xml>>>), you can
provide a custom <<pluginGroups>> section, listing the plugin groupIds you
want to search (each groupId goes in its own <<pluginGroup>> sub-element).
- For example, if my project uses a Modello model file, I might have the
+ For example, if my project uses a Modello model file, I might have the
following in my settings:
+---+
@@ -125,23 +125,22 @@
mvn -Dversion=4.0.0 -Dmodel=maven.mdo modello:java
+---+
- Maven will always search the following groupId's <<after>> searching any
plugin groups
+ 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
+ of <<<clean>>>, I can override the usage of the <<<maven-clean-plugin>>> when
<<<clean:clean>>> is invoked.
-
+
<<NOTE2:>> For more information on <<<settings.xml>>>, see \[{{{#1}1}}\].
-
+
*Resources
{1} {{{../mini/guide-configuring-maven.html}Guide to Configuring Maven}}
-
\ No newline at end of file
Modified:
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugins.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugins.apt?rev=619844&r1=619843&r2=619844&view=diff
==============================================================================
---
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugins.apt
(original)
+++
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-plugins.apt
Fri Feb 8 03:47:41 2008
@@ -30,53 +30,53 @@
Maven consists of a core engine which provides basic project-processing
capabilities and build-process management, and a host of plugins which are
- used to execute the actual build tasks.
-
+ used to execute the actual build tasks.
+
* What is a Plugin?
- "Maven" is really just a core framework for a collection of
- Maven Plugins. In other words, plugins are where much of the real action is
- performed, plugins are used to: create jar files, create war files, compile
- code, unit test code, create project documentation, and on and on. Almost
- any action that you can think of performing on a project is implemented as
+ "Maven" is really just a core framework for a collection of
+ Maven Plugins. In other words, plugins are where much of the real action is
+ performed, plugins are used to: create jar files, create war files, compile
+ code, unit test code, create project documentation, and on and on. Almost
+ any action that you can think of performing on a project is implemented as
a Maven plugin.
-
+
Plugins are the central feature of Maven that allow for the reuse of
common build logic across multiple projects. They do this by executing an
"action" (i.e. creating a WAR file or compiling unit tests) in the context
of a project's description - the Project Object Model (POM). Plugin behavior
- can be customized through a set of unique parameters which are exposed by a
+ can be customized through a set of unique parameters which are exposed by a
description of each plugin goal (or Mojo).
-
- One of the simplest plugins in Maven 2.0 is the Clean Plugin. The
+
+ One of the simplest plugins in Maven 2.0 is the Clean Plugin. The
{{{/plugins/maven-clean-plugin/}Maven
- Clean plugin}} (maven-clean-plugin) is responsible for removing the target
+ Clean plugin}} (maven-clean-plugin) is responsible for removing the target
directory of a Maven 2 project. When you run "mvn clean", Maven 2 executes
the "clean" goal as defined in the Clean plug-in, and the target directory
- is removed. The Clean plugin
- {{{/plugins/maven-clean-plugin/clean-mojo.html}defines
- a parameter}} which can be used to customize plugin behavior, this parameter
is
- called outputDirectory and it defaults to ${project.build.directory}.
+ is removed. The Clean plugin
+ {{{/plugins/maven-clean-plugin/clean-mojo.html}defines
+ a parameter}} which can be used to customize plugin behavior, this parameter
is
+ called outputDirectory and it defaults to $\{project.build.directory\}.
* What is a Mojo (<And Why the H--- is it Named 'Mojo'>)?
- A Mojo is really just a goal in Maven 2, and plug-ins consist of
+ A Mojo is really just a goal in Maven 2, and plug-ins consist of
any number of goals (Mojos). Mojos can be defined as annotated Java classes
or
- Beanshell script. A Mojo specifies
- metadata about a goal: a goal name, which phase of the lifecycle it fits
into,
+ Beanshell script. A Mojo specifies
+ metadata about a goal: a goal name, which phase of the lifecycle it fits
into,
and the parameters it is expecting.
-
+
MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for
- "Plain". Mojo is also an iteresting word (see
{{{http://www.answers.com/mojo&r=67}definition}}).
+ "Plain". Mojo is also an iteresting word (see
{{{http://www.answers.com/mojo&r=67}definition}}).
From {{{http://www.wikipedia.org}Wikipedia}}, a "mojo" is defined as:
- "...a small bag worn by a person under the clothes (also known as a mojo
hand).
- Such bags were thought to have supernatural powers, such as protecting from
evil,
+ "...a small bag worn by a person under the clothes (also known as a mojo
hand).
+ Such bags were thought to have supernatural powers, such as protecting from
evil,
bringing good luck, etc."
* What is the Build Lifecycle? (Overview)
The build lifecycle is a series of common stages through which all project
- builds naturally progress. Plugin goals are bound to specific stages in the
+ builds naturally progress. Plugin goals are bound to specific stages in the
lifecycle.
Resources
@@ -84,105 +84,105 @@
[[1]] {{{../plugin/guide-java-plugin-development.html}Plugin development
guide}}
[[2]] {{{../mini/guide-configuring-plugins.html}Configuring plugins}}
-
+
Comparison to Maven 1.x Plugins
* Similarities to Maven 1.x
- Maven 2.0 is similar to its predecessor in that it has two main
- functions. First, it organizes project data into a coherent whole,
- and exposes this data for use within the build process. Second, Maven
- marshals a set of plugins to do the heavy lifting and execute the
+ Maven 2.0 is similar to its predecessor in that it has two main
+ functions. First, it organizes project data into a coherent whole,
+ and exposes this data for use within the build process. Second, Maven
+ marshals a set of plugins to do the heavy lifting and execute the
actual steps of the build.
-
- Many things in Maven 2 will have at least superficial familiarity
- to users of Maven 1, and the plugin system is no exception. Maven 2
- plugins appear to behave much as their 1.x counterparts do. Like 1.x
- plugins, they use both project information and custom-defined
- configurations to perform their work. Also, Maven 2 plugins are
- organized and executed in a coherent way by the build engine itself -
- that is to say, the engine is still responsible for organizing and
- fulfilling a plugin's requirements before executing the plugin
+
+ Many things in Maven 2 will have at least superficial familiarity
+ to users of Maven 1, and the plugin system is no exception. Maven 2
+ plugins appear to behave much as their 1.x counterparts do. Like 1.x
+ plugins, they use both project information and custom-defined
+ configurations to perform their work. Also, Maven 2 plugins are
+ organized and executed in a coherent way by the build engine itself -
+ that is to say, the engine is still responsible for organizing and
+ fulfilling a plugin's requirements before executing the plugin
itself.
-
- Operationally, Maven 2.0 should feel very much like a more
- performant big brother of Maven 1.x. While the POM has definitely
- changed, it has the same basic layout and features (with notable
- additions). However, this is where the similarity ends. Maven 2.0 is
- a complete redesign and reimplementation of the Maven build concept.
- As such, it has a much different and more evolved architecture - at least to
+
+ Operationally, Maven 2.0 should feel very much like a more
+ performant big brother of Maven 1.x. While the POM has definitely
+ changed, it has the same basic layout and features (with notable
+ additions). However, this is where the similarity ends. Maven 2.0 is
+ a complete redesign and reimplementation of the Maven build concept.
+ As such, it has a much different and more evolved architecture - at least to
our minds. <<;-)>>
-
+
* Differences from Maven 1.x
- However similar the architectures may seem, Maven 2 offers a much
- richer environment for its plugins than Maven 1 ever did. The new
- architecture offers a managed lifecycle, multiple implementation
- languages, reusability outside of the build system, and many more
- advantages. Arguably the biggest advantage is the ability to write
- Maven plugins entirely in Java, which allows developers to tap into a
- rich landscape of development and testing tools to aid in their
+ However similar the architectures may seem, Maven 2 offers a much
+ richer environment for its plugins than Maven 1 ever did. The new
+ architecture offers a managed lifecycle, multiple implementation
+ languages, reusability outside of the build system, and many more
+ advantages. Arguably the biggest advantage is the ability to write
+ Maven plugins entirely in Java, which allows developers to tap into a
+ rich landscape of development and testing tools to aid in their
efforts.
-
- Prior to Maven 2.0, the build system organized relevant plugins
- into a loosely defined lifecycle, which was determined based on goal
- prerequisites and decoration via preGoals and postGoals. That
- experience was critical for the Maven community. It taught us that
- even though there may be a million different build scenarios out
- there, most of the activities in those builds fit into just a few
- broad categories. Moreover, the category to which a goal fits serves
- as an accurate predictor for where in the build process the goal
- should execute. Drawing on this experience, Maven 2.0 defines a
- lifecycle within which plugins are managed according to their
+
+ Prior to Maven 2.0, the build system organized relevant plugins
+ into a loosely defined lifecycle, which was determined based on goal
+ prerequisites and decoration via preGoals and postGoals. That
+ experience was critical for the Maven community. It taught us that
+ even though there may be a million different build scenarios out
+ there, most of the activities in those builds fit into just a few
+ broad categories. Moreover, the category to which a goal fits serves
+ as an accurate predictor for where in the build process the goal
+ should execute. Drawing on this experience, Maven 2.0 defines a
+ lifecycle within which plugins are managed according to their
relative position within this lifecycle.
-
- Starting with Maven 2.0, plugins implemented in different
- programming or scripting languages can coexist within the same build
- process. This removes the requirement that plugin developers learn a
- particular scripting language in order to interact with Maven. It
- also reduced the risk associated with the stability or richness of
+
+ Starting with Maven 2.0, plugins implemented in different
+ programming or scripting languages can coexist within the same build
+ process. This removes the requirement that plugin developers learn a
+ particular scripting language in order to interact with Maven. It
+ also reduced the risk associated with the stability or richness of
any particular scripting language.
-
- Also starting with Maven 2.0 is an effort to integrate multiproject
- builds directly into the core architecture. In Maven 1.x, many large
- projects were fragmented into smaller builds to sidestep issues such
- as conditional compilation of a subset of classes; separation of
- client-server code; or cyclical dependencies between distinct
- application libraries. This in turn created extra complexity with
- running builds, since multiple builds had to be run in order to build
- the application as a whole - one or more per project. While the first
- version (1.x) did indeed address this new multiple projects issue, it
- did so as an afterthought. The Reactor was created to act as a sort
- of <apply-to-all-these> function, and the multiproject plugin
- was later added to provide Reactor settings for some common build
- types. However, this solution (it <is> really only one solution,
- plus some macros) really never integrated the idea of the
- multi-project build process into the maven core conceptual
+
+ Also starting with Maven 2.0 is an effort to integrate multiproject
+ builds directly into the core architecture. In Maven 1.x, many large
+ projects were fragmented into smaller builds to sidestep issues such
+ as conditional compilation of a subset of classes; separation of
+ client-server code; or cyclical dependencies between distinct
+ application libraries. This in turn created extra complexity with
+ running builds, since multiple builds had to be run in order to build
+ the application as a whole - one or more per project. While the first
+ version (1.x) did indeed address this new multiple projects issue, it
+ did so as an afterthought. The Reactor was created to act as a sort
+ of <apply-to-all-these> function, and the multiproject plugin
+ was later added to provide Reactor settings for some common build
+ types. However, this solution (it <is> really only one solution,
+ plus some macros) really never integrated the idea of the
+ multi-project build process into the maven core conceptual
framework.
-
+
* Why Change the Plugin Architecture?
See the previous section for the long version, but the short version can
be summed up by the following list of benefits.
* A managed lifecycle
-
+
* Multiple implementation languages
-
+
* Reusability outside of the build system
-
+
* The ability to write Maven plugins entirely in Java
-
- In Maven 1.0, a plugin was defined using Jelly, and while it was possibly to
+
+ In Maven 1.0, a plugin was defined using Jelly, and while it was possibly to
write a plugin in Java, you still had to wrap your plugin with some
obligatory
Jelly script. An XML-based scripting language which is interpreted at
run-time
isn't going to be the best choice for performance, and the development team
thought it wise to adopt an approach which would allow plugin developers to
- choose from an array of plugin implementation choices. The first choice in
+ choose from an array of plugin implementation choices. The first choice in
Maven 2 should be Java plugins, but you may also use one of the supported
scripting languages like Beanshell.
-
- To summarize, the development team saw some critical gaps in the API and
+
+ To summarize, the development team saw some critical gaps in the API and
architecture of Maven 1.0 plug-ins, and the team decided that addressing
these deficiencies was critical to the future progress of Maven from a useful
tool to something more robust.
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-assemblies.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-assemblies.apt?rev=619844&r1=619843&r2=619844&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-assemblies.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-assemblies.apt Fri Feb 8
03:47:41 2008
@@ -40,7 +40,7 @@
+----+
- You'll notice that the assembly descriptor is located in
<<<${basedir}/src/main/assembly>>> which is the
+ You'll notice that the assembly descriptor is located in
<<<$\{basedir\}/src/main/assembly>>> which is the
{{{../introduction/introduction-to-the-standard-directory-layout.html}standard}}
location for assembly
descriptors.
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-attached-tests.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-attached-tests.apt?rev=619844&r1=619843&r2=619844&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-attached-tests.apt
(original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-attached-tests.apt Fri Feb
8 03:47:41 2008
@@ -9,7 +9,7 @@
Guide to using attached tests
Many times you may want to resuse the tests that you have created for a
project in another. For example if you have
- written <<<foo-core>>> and it contains test code in the
<<<${basedir}/src/test/java>>> it would be useful to package
+ written <<<foo-core>>> and it contains test code in the
<<<$\{basedir\}/src/test/java>>> it would be useful to package
up those compiled tests in a JAR and deploy them for general resuse. To do
this you would configure the
<<<maven-jar-plugin>>> as follows:
Modified:
maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt?rev=619844&r1=619843&r2=619844&view=diff
==============================================================================
---
maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt
(original)
+++
maven/site/trunk/src/site/apt/guides/mini/guide-central-repository-upload.apt
Fri Feb 8 03:47:41 2008
@@ -197,7 +197,7 @@
+----+
The bundle will be created in your <<<target>>> directory with the name:
- <<<${pom.artifactId}-${pom.currentVersion}-bundle.jar>>>
+ <<<$\{pom.artifactId\}-$\{pom.currentVersion\}-bundle.jar>>>
If you want to include a jar with java sources in your upload (recommended,
unless your license doesn't
allow sources to be redistributed) the command to run is:
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt?rev=619844&r1=619843&r2=619844&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt
(original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt Fri
Feb 8 03:47:41 2008
@@ -9,7 +9,7 @@
How Maven's classloaders work
Maven uses the {{{http://classworlds.codehaus.org}Classworlds}} classloading
framework with which we
- create our classloader graph. If you look in your <<<${maven.home}/m2/core>>>
directory you will see a single JAR
+ create our classloader graph. If you look in your
<<<$\{maven.home\}/m2/core>>> directory you will see a single JAR
which is the classworlds JAR we use to boot the classloader graph. The
Classworlds JAR is the only element of
the Java $CLASSPATH and Classworlds then builds the following graph of
classloaders where the <<<plexus.core>>> classloader,
or Realm in Classworlds, is the parent in the context of Maven.
Modified: maven/site/trunk/src/site/apt/guides/mini/guide-proxies.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-proxies.apt?rev=619844&r1=619843&r2=619844&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-proxies.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-proxies.apt Fri Feb 8
03:47:41 2008
@@ -10,7 +10,7 @@
You can configure a proxy to use for some or all of your HTTP requests in
Maven 2.0. The username and password are only
required if your proxy requires basic authentication (note that later
releases may support storing your passwords in
- a secured keystore - in the mean time, please ensure your settings.xml file
(usually ${user.home}/.m2/settings.xml) is secured with permissions
+ a secured keystore - in the mean time, please ensure your settings.xml file
(usually $\{user.home\}/.m2/settings.xml) is secured with permissions
appropriate for your operating system).
The <<<nonProxyHosts>>> setting accepts wild cards, and each host not to
proxy is separated by the | character. This matches
