diff --git a/maven-site/src/site/apt/guides/plugin/build-plugin.apt b/maven-site/src/site/apt/guides/plugin/build-plugin.apt new file mode 100644 index 0000000000..eedd0a6cdd --- /dev/null +++ b/maven-site/src/site/apt/guides/plugin/build-plugin.apt @@ -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: + +*------------------+----------------------------------------------------------+ +|<<>> |This is the group ID for the plugin, and should match the | +| |common prefix to the packages used by the mojos | +*------------------+----------------------------------------------------------+ +|<<>> |This is the name of the plugin | +*------------------+----------------------------------------------------------+ +|<<>> |This is the version of the plugin | +*------------------+----------------------------------------------------------+ +|<<>> |This should be set to "<<>>" | +*------------------+----------------------------------------------------------+ +|<<>>|A dependency must be declared to the Maven Plugin Tools | +| |API to resolve "<<>>" and related classes | +*------------------+----------------------------------------------------------+ + + Listed below is a POM for a plugin which uses the simple sample mojo: + ++----+ + + 4.0.0 + sample.plugin + maven-hello-plugin + maven-plugin + 1.0-SNAPSHOT + Sample Parameter-less Maven Plugin + + + org.apache.maven + maven-plugin-tools-api + 2.0-beta-2 + + + ++----+ + +Build Goals + + There are a few goals which are defined with the Maven plugin + packaging as part of a standard build lifecycle: + +*-------------+----------------------------------------------------+ +|<<>>|Compiles the Java code for the plugin and builds the| +| |plugin descriptor | +*-------------+----------------------------------------------------+ +|<<>> |Runs the plugin's unit tests | +*-------------+----------------------------------------------------+ +|<<>>|Builds the plugin jar | +*-------------+----------------------------------------------------+ +|<<>>|Installs the plugin jar in the local repository | +*-------------+----------------------------------------------------+ +|<<>> |Deploys the plugin jar to the remote repository | +*-------------+----------------------------------------------------+ diff --git a/maven-site/src/site/apt/guides/plugin/first-mojo.apt b/maven-site/src/site/apt/guides/plugin/first-mojo.apt new file mode 100644 index 0000000000..e8a01b6a5a --- /dev/null +++ b/maven-site/src/site/apt/guides/plugin/first-mojo.apt @@ -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 + <<>> + looks for classes with a "<<>>" 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 <<>> provides most of the + infrastructure required to implement a mojo except for the + <<>> 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 <<>> method can throw two exceptions: + + * <<>> if an unexpected + problem occurs. Throwing this exception causes a "BUILD ERROR" message + to be displayed. + + * <<>> if an expected + problem (such as a compilation failure) occurs. Throwing this exception + causes a "BUILD FAILURE" message to be displayed. + + * The <<>> method (defined in <<>>) 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. diff --git a/maven-site/src/site/apt/guides/plugin/first-plugin.apt b/maven-site/src/site/apt/guides/plugin/first-plugin.apt new file mode 100644 index 0000000000..62d4df5b79 --- /dev/null +++ b/maven-site/src/site/apt/guides/plugin/first-plugin.apt @@ -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. diff --git a/maven-site/src/site/apt/guides/plugin/first-run.apt b/maven-site/src/site/apt/guides/plugin/first-run.apt new file mode 100644 index 0000000000..52f3e8a0f1 --- /dev/null +++ b/maven-site/src/site/apt/guides/plugin/first-run.apt @@ -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 + "<<>>" 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 + <<>> 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 <<>> file: + ++----+ + + sample.plugin + ++----+ + + At this point, you can run the mojo with "<<>>". diff --git a/maven-site/src/site/apt/guides/plugin/index.apt b/maven-site/src/site/apt/guides/plugin/index.apt new file mode 100644 index 0000000000..8abbfd6212 --- /dev/null +++ b/maven-site/src/site/apt/guides/plugin/index.apt @@ -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\xBB + + \xAB\xBB