You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jv...@apache.org on 2005/10/07 03:04:43 UTC
svn commit: r306969 - in
/maven/components/trunk/maven-site/src/site/apt/guides/plugin:
build-plugin.apt first-mojo.apt first-plugin.apt first-run.apt index.apt
Author: jvanzyl
Date: Thu Oct 6 18:04:36 2005
New Revision: 306969
URL: http://svn.apache.org/viewcvs?rev=306969&view=rev
Log:
o adding doco contributed by Bob Allison
Added:
maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt (with props)
maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt (with props)
maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt (with props)
maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt (with props)
maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt (with props)
Added: maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt?rev=306969&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt (added)
+++ maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt Thu Oct 6 18:04:36 2005
@@ -0,0 +1,66 @@
+ ------
+ Plugin Development Guide - Building a Plugin
+ -----
+ Bob Allison
+ ------
+ 12 October 2005
+ ------
+
+
+Project Definition
+
+ Once the mojos have been written for the plugin, it is time to
+ build the plugin. To do this properly, the project's descriptor
+ needs to have a number of settings set properly:
+
+*------------------+----------------------------------------------------------+
+|<<<groupId>>> |This is the group ID for the plugin, and should match the |
+| |common prefix to the packages used by the mojos |
+*------------------+----------------------------------------------------------+
+|<<<artifactId>>> |This is the name of the plugin |
+*------------------+----------------------------------------------------------+
+|<<<version>>> |This is the version of the plugin |
+*------------------+----------------------------------------------------------+
+|<<<packaging>>> |This should be set to "<<<maven-plugin>>>" |
+*------------------+----------------------------------------------------------+
+|<<<dependencies>>>|A dependency must be declared to the Maven Plugin Tools |
+| |API to resolve "<<<AbstractMojo>>>" and related classes |
+*------------------+----------------------------------------------------------+
+
+ Listed below is a POM for a plugin which uses the simple sample mojo:
+
++----+
+<project>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>sample.plugin</groupId>
+ <artifactId>maven-hello-plugin</artifactId>
+ <packaging>maven-plugin</packaging>
+ <version>1.0-SNAPSHOT</version>
+ <name>Sample Parameter-less Maven Plugin</name>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-plugin-tools-api</artifactId>
+ <version>2.0-beta-2</version>
+ </dependency>
+ </dependencies>
+</project>
++----+
+
+Build Goals
+
+ There are a few goals which are defined with the Maven plugin
+ packaging as part of a standard build lifecycle:
+
+*-------------+----------------------------------------------------+
+|<<<compile>>>|Compiles the Java code for the plugin and builds the|
+| |plugin descriptor |
+*-------------+----------------------------------------------------+
+|<<<test>>> |Runs the plugin's unit tests |
+*-------------+----------------------------------------------------+
+|<<<package>>>|Builds the plugin jar |
+*-------------+----------------------------------------------------+
+|<<<install>>>|Installs the plugin jar in the local repository |
+*-------------+----------------------------------------------------+
+|<<<deploy>>> |Deploys the plugin jar to the remote repository |
+*-------------+----------------------------------------------------+
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/build-plugin.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt?rev=306969&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt (added)
+++ maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt Thu Oct 6 18:04:36 2005
@@ -0,0 +1,66 @@
+ -------
+ Plugin Development Guide - Your First Mojo
+ -------
+ Bob Allison
+ -------
+ 12 October 2005
+ -------
+
+Your First Mojo
+
+ At its simplest, a Java mojo consists simply of a single class. There is
+ no requirement for multiple classes like EJBs, although a plugin which
+ contains a number of similar mojos is likely to use an abstract
+ superclass for the mojos to consolidate code common to all mojos.
+
+ When processing the source tree to find mojos, the class
+ <<<org.apache.maven.tools.plugin.extractor.java.JavaMojoDescriptorExtractor>>>
+ looks for classes with a "<<<goal>>>" annotation on the class. Any class
+ with this annotation are included in the plugin configuration file.
+
+A Simple Mojo
+
+ Listed below is a simple mojo class which has no parameters. This is
+ about as simple as a mojo can be. After the listing is a description
+ of the various parts of the source.
+
++---+
+package sample.plugin;
+
+import org.apache.maven.plugin.AbstractMojo;
+import org.apache.maven.plugin.MojoExecutionException;
+
+/**
+ * @goal sayhi
+ * @description Says "Hi" to the user
+ */
+public class GreetingMojo extends AbstractMojo {
+ public void execute() throws MojoExecutionException {
+ getLog().info("Hello, world.");
+ }
+}
++---+
+
+ * The class <<<org.apache.maven.plugin.AbstractMojo>>> provides most of the
+ infrastructure required to implement a mojo except for the
+ <<<execute>>> method.
+
+ * The comment lines starting with "<<<...@goal>>>" and "<<<...@description>>>"
+ are examples of annotations. These two annotations are required, but
+ there are a number of annotations which can be used to control how and
+ when the mojo is executed.
+
+ * The <<<execute>>> method can throw two exceptions:
+
+ * <<<org.apache.maven.plugin.MojoExecutionException>>> if an unexpected
+ problem occurs. Throwing this exception causes a "BUILD ERROR" message
+ to be displayed.
+
+ * <<<org.apache.maven.plugin.MojoFailureException>>> if an expected
+ problem (such as a compilation failure) occurs. Throwing this exception
+ causes a "BUILD FAILURE" message to be displayed.
+
+ * The <<<getLog>>> method (defined in <<<AbstractMojo>>>) returns a
+ log4j-like logger object which allows plugins to create messages at levels
+ of "debug", "info", "warn", and "error". This logger is the accepted means
+ to display information to the user.
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-mojo.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt?rev=306969&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt (added)
+++ maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt Thu Oct 6 18:04:36 2005
@@ -0,0 +1,15 @@
+ -------
+ Plugin Development Guide - Your First Plugin
+ -------
+ Bob Allison
+ -------
+ 12 October 2005
+ -------
+
+Your First Plugin
+
+ This section of the document walks the reader through the process
+ of building a simple plugin which takes no parameters and simply
+ displays a message on the screen when run. It covers the basics of
+ setting up a project to create a plugin, the minimal contents of a
+ Java mojo, and the means to cause the mojo to be executed.
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-plugin.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt?rev=306969&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt (added)
+++ maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt Thu Oct 6 18:04:36 2005
@@ -0,0 +1,44 @@
+ ------
+ Plugin Development Guide - Executing Your First Mojo
+ ------
+ Bob Allison
+ ------
+ 12 October 2005
+ ------
+
+
+Executing Your First Mojo
+
+ The most direct means of executing your new plugin is to specify the
+ plugin goal directly on the command line. To do this, you need to
+ specify a fully-qualified goal in the form of:
+
++----+
+groupID:artifactID:version:goal
++----+
+
+ For example, to run the simple mojo in the sample plugin, you would enter
+ "<<<m2 sample.plugin:maven-hello-plugin:1.0-SNAPSHOT:sayhi>>>" on the
+ command line.
+
+Shortening the Command Line
+
+ It is possible to shorten the amount of typing needed on the command
+ line. To do this, you need to install the plugin with the
+ <<<updateReleaseInfo>>> option set to true; for example:
+
++----+
+m2 -DupdateReleaseInfo=true install
++----+
+
+ You also need to add your plugin's group ID to the list of group IDs
+ searched by default. To do this, you need to add the following to
+ your <<<settings.xml>>> file:
+
++----+
+<pluginGroups>
+ <pluginGroup>sample.plugin</pluginGroup>
+</pluginGroups>
++----+
+
+ At this point, you can run the mojo with "<<<m2 hello:sayhi>>>".
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/first-run.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt
URL: http://svn.apache.org/viewcvs/maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt?rev=306969&view=auto
==============================================================================
--- maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt (added)
+++ maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt Thu Oct 6 18:04:36 2005
@@ -0,0 +1,17 @@
+ ------
+ Plugin Development Guide - Introduction
+ ------
+ Bob Allison
+ ------
+ 12 October 2005
+ -----
+
+Introduction
+
+ This web site contains documentation to assist users in developing
+ their own plugins. \xAB<Text like this are comments identifying known
+ problems with this documentation. As the problems are fixed these
+ comments should be removed.>\xBB
+
+ \xAB<Should the plugin overview (at least the first part of it) be
+ repeated here for clarity?>\xBB
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/components/trunk/maven-site/src/site/apt/guides/plugin/index.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"