Jason van Zyl Pete Kazmier

Developer Guide

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.

Plugins

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.

How to create your first plugin

  1. Create a directory for the 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/ 
                
  2. Create the project.xml file

    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>  
                
  3. Create the plugin.jelly file

    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> 
                
  4. Other useful files

    There are a couple of other useful files that you might want to know of:

    project.properties
    the same as always, it's for customizing the build process of the plugin itself.
    plugin.properties
    This is simply the default values of the properties that the plugin exposes for the user to customize
  5. Install the plugin

    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
    to install it to MAVEN_HOME.

  6. Invoke the plugin

    Start maven using

    maven hello

    And there's your first plug-in!

Sharing Your Plugin

Please see Sharing Your Plugin for guidelines on how to share your Maven plugins with the community.

Reporting Protocol

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:

AttributeValue
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: