Welcome. If you are reading this page, you should be a developer interested in contributing to Maven and/or writing plugins for Maven. If you are simply a developer using Maven for your own project, you are looking for the User Guide. With that said, this document contains various snippets of information that every Maven developer should know.
Adding functionality to Maven is done through the Maven plugin mechanism. Maven comes shipped with numerous plugins. Plugins can be used to do virtually any task desired. For example, they can generate reports, create and deploy software distributions, run unit tests, and much more. This section of the document will (in the future) describe how to write a plugin; however, in the meantime it contains snippets of information not necessarily assembled in any paricular order, but of importance for anyone writing a plugin.
Create a local directory for the plugin source code:
~/myprojects/maven-plugins/hello
In this directory create the following directory structure:
./src/java ./src/plugin-resources ./xdocs/
You might use this as a template for you project.xml:
<?xml version="1.0" encoding="ISO-8859-1"?> <project> <pomVersion>3</pomVersion> <id>maven-hello-plugin</id> <name>Maven hello world plugin</name> <currentVersion>1.0.0</currentVersion> <organization> <name>My org name</name> </organization> <inceptionYear>2003</inceptionYear> <shortDescription>Short description of the plugin</shortDescription> <developers> <developer> <name>Trygve Laugstøl</name> <id>trygvis</id> <email>trygvela@ifi.uio.no</email> <organization>My organization</organization> <roles> <role>Developer</role> </roles> </developer> </developers> <dependencies> <!-- <dependency> <id>commons-logging</id> <version>1.0.3</version> </dependency> --> </dependencies> <build> <!-- Useful if your plugin uses some beans --> <sourceDirectory>src/java/main</sourceDirectory> <unitTestSourceDirectory>src/java/test</unitTestSourceDirectory> <unitTest> <includes> <include>**/*Test.java</include> </includes> </unitTest> <resources> <resource> <directory>${basedir}/src/plugin-resources</directory> <targetPath>plugin-resources</targetPath> </resource> <resource> <directory>${basedir}</directory> <includes> <include>plugin.jelly</include> <include>plugin.properties</include> <include>project.properties</include> <include>project.xml</include> </includes> </resource> </resources> </build> </project>
This file is the main file in the plugin. It contains the goals that make up the plugin.
<?xml version="1.0" encoding="ISO-8859-1"?> <project> <goal name="hello"> <echo>Hello Maven Plug-in!</echo> </goal> </project>
There are a couple of other useful files that you might want to know of:
While developing a plugin you probably don't wont the plugin to be accessable for everyone using the same maven installation as you, so you should copy the built plugin to your local plugins directory.
When you have a good version you can do
maven plugin:install
MAVEN_HOME
.
Start maven using
maven hello
And there's your first plug-in!
Please see Sharing Your Plugin for guidelines on how to share your Maven plugins with the community.
If you are writing a plugin which generates output that you want to be included on Maven generated sites, then you need to adhere to a specific protocol. This protocol ensures that your output will be automatically included on a Maven generated site if a user has selected to run the report associated with your plugin. Assuming this is true, a link will be created in the "Project Reports" section of the navigation bar that points to the output generated by your plugin. In addition, an entry will be included in the document that provides an overview of all Maven generated reports (this is the page that a user sees when they click on the "Project Reports" section of the navigation bar).
The protocol consists of three requirements, all of which
require the specification of a goal in your
plugin.jelly
file. The first goal should be
called maven-xyz-plugin:register
, where
xyz
is the name of your plugin. This goal should
contain one or more doc:registerReport
tags. The following is an example is taken from the changelog
plugin included with Maven:
This goal is responsible for "registering" the report that is
generated by your plugin with the xdoc plugin (the plugin that
generates the docs). Note, you must include the
following in your xmlns declarations in order to use the
doc:registerReport
tag:
xmlns:doc="doc"
. The
doc:registerReport
tag has four required
attributes:
Attribute | Value |
---|---|
name |
The is the name of your report. It is the name that will
be used in the navigation bar as well as the
auto-generated maven-reports.xml overview
document. The name should be unique to prevent name
collisions with other plugins.
|
pluginName |
The is the name of the plugin that is registering the report.
The goal ${pluginName}:report will be run to
generate the report.
|
link |
This is a relative link to the output of your plugin but
does not contain an extension. The link is
relative from the root of the generated site. For
example, if you specify changelog-report then
your generated output should be located in the root of
your target/docs directory and called
changelog-report.html .
|
description |
This should be a one line description of the output
produced by your plugin. It is included on the
auto-generated maven-reports.xml overview
document.
|
A plugin may specify more than one report. It is entirely possible to register additional reports as shown below (taken from the javadoc plugin included with Maven):
The above example registers two reports with the xdoc plugin. A keen observer will notice that the above plugin does not register its reports if the project does not have any sources. It is encouraged that plugin developers use conditional logic to prevent their reports from registering if they don't apply to the user's project.
The second part of the plugin protocol is the specification of
a deregistration goal called maven-xyz-plugin:report
.
This goal is optional, but should be included to allow users to
add / remove the report from their site.
The third part of the plugin protocol is the specification of
a goal called maven-xyz-plugin:report
, where
xyz
is the name of your plugin. This goal must
generate the output for your plugin. For example, if you were
writing a plugin to generated javadoc (which you wouldn't
because it already exists), you would create a goal called
maven-javadoc-plugin:report
and it would contain
the logic necessary to produce the resulting JavaDocs.
If you adhere to the following protocol, users will be able to
select which reports they want to be included in their
Maven-generated site by specifying a reports
section in their POM. For example, to include the javadoc and
changelog reports in a site, the POM would include the
following: