dion 2003/08/19 17:58:19
Added: xdocs/reference/developers developer-guide.xml
Log:
Move developer guide to developers directory
Revision Changes Path
1.1 maven/xdocs/reference/developers/developer-guide.xml
Index: developer-guide.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Developer Guide</title>
<author email="[EMAIL PROTECTED]">Jason van Zyl</author>
<author email="[EMAIL PROTECTED]">Pete Kazmier</author>
</properties>
<body>
<section name="Developer Guide">
<p>
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 <b>using</b>
Maven for your own project, you are looking for the
<a href="user-guide.html">User Guide</a>. With that said, this
document contains various snippets of information that every
Maven developer should know.
</p>
</section>
<section name="Plugins">
<p>
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.
</p>
<subsection name="Reporting Protocol">
<p>
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).
</p>
<p>
The protocol consists of three requirements, all of which
require the specification of a goal in your
<code>plugin.jelly</code> file. The first goal should be
called <code>maven-xyz-plugin:register</code>, where
<code>xyz</code> is the name of your plugin. This goal should
contain one or more <code>doc:registerReport</code>
tags. The following is an example is taken from the changelog
plugin included with Maven:
</p>
<source><![CDATA[
<goal name="maven-changelog-plugin:register">
<doc:registerReport
name="Change Log"
link="changelog-report"
description="Report on the source control changelog."/>
</goal>
]]></source>
<p>
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 <b>must</b> include the
following in your xmlns declarations in order to use the
<code>doc:registerReport</code> tag:
<code>xmlns:doc="doc"</code>. The
<code>doc:registerReport</code> tag has four required
attributes:
</p>
<table>
<tr><th>Attribute</th><th>Value</th></tr>
<tr>
<td>name</td>
<td>
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 <code>maven-reports.xml</code> overview
document. The name should be unique to prevent name
collisions with other plugins.
</td>
</tr>
<tr>
<td>pluginName</td>
<td>
The is the name of the plugin that is registering the report.
The goal <code>${pluginName}:report</code> will be run to
generate the report.
</td>
</tr>
<tr>
<td>link</td>
<td>
This is a relative link to the output of your plugin but
does <b>not</b> contain an extension. The link is
relative from the root of the generated site. For
example, if you specify <code>changelog-report</code> then
your generated output should be located in the root of
your <code>target/docs</code> directory and called
<code>changelog-report.html</code>.
</td>
</tr>
<tr>
<td>description</td>
<td>
This should be a one line description of the output
produced by your plugin. It is included on the
auto-generated <code>maven-reports.xml</code> overview
document.
</td>
</tr>
</table>
<p>
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):
</p>
<source><![CDATA[
<goal name="maven-javadoc-plugin:register">
<j:if test="${sourcesPresent}">
<doc:registerReport
name="JavaDocs"
link="apidocs/index"
description="JavaDoc API documentation."/>
<doc:registerReport
name="JavaDoc Report"
link="javadoc"
description="Report on the generation of JavaDoc."/>
</j:if>
</goal>
]]></source>
<p>
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.
</p>
<p>
The second part of the plugin protocol is the specification of
a deregistration goal called <code>maven-xyz-plugin:report</code>.
This goal is optional, but should be included to allow users to
add / remove the report from their site.
</p>
<source><![CDATA[
<goal name="maven-javadoc-plugin:deregister">
<doc:deregisterReport name="JavaDocs"/>
</goal>
]]></source>
<p>
The third part of the plugin protocol is the specification of
a goal called <code>maven-xyz-plugin:report</code>, where
<code>xyz</code> 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
<code>maven-javadoc-plugin:report</code> and it would contain
the logic necessary to produce the resulting JavaDocs.
</p>
<p>
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 <code>reports</code>
section in their POM. For example, to include the javadoc and
changelog reports in a site, the POM would include the
following:
</p>
<source><![CDATA[
<reports>
<report>maven-changelog-plugin</report>
<report>maven-javadoc-plugin</report>
</reports>
]]></source>
</subsection>
<subsection name="Programmatic Report Control">
<p>If you wish to use the default reports but remove one or add one, the
preferred method is to use a postGoal for xdoc:register-reports
</p>
<source><![CDATA[
<postGoal name="xdoc:register-reports">
<attainGoal name="maven-changelog-plugin:deregister"/>
<attainGoal name="maven-myown-plugin:register"/>
</postGoal>
]]></source>
</subsection>
<subsection name="Class Loaders">
<p>When writing plugins, you will need to control the class loaders that
are used to load your specified dependencies. The following table
shows the classloaders available:
</p>
<table>
<tr>
<th>Class loader</th>
<th>Description</th>
</tr>
<tr>
<td><default></td>
<td>
This class loader is used if none is specified in the dependency.
This means that the dependency is loaded into the plugin's class
loader, making it available to the plugin only.
</td>
</tr>
<tr>
<td><code>root</code></td>
<td>
This is the Ant class loader, and the most common override used in
a plugin. Use this if you need to specify a dependency used by a
custom Ant task used in the plugin.
</td>
</tr>
<tr>
<td><code>root.maven</code></td>
<td>
This is the Maven class loader. Use it if you wish to have the
dependency available to the Maven core.
</td>
</tr>
</table>
<p>To specify a classloader for a dependency, add a section similar to
the following to your plugin's project.xml:
</p>
<source><![CDATA[
<dependency>
<groupId>jaxb</groupId>
<artifactId>jaxb-xjc</artifactId>
<properties>
<classloader>root</classloader>
</properties>
</dependency>
]]></source>
<p>You should also note that the same properties can be used in your
projects, not just plugins. This may be required if you are writing
custom scripts in <code>maven.xml</code>.
</p>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
