9c7c08b449
Submitted By: Joakim Erdfelt Reviewed By: Brett Porter PMD plugin cleanup. Rulesets are kept inside PMD jar, upgraded to v1.3. Clean documentation. git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@115459 13f79535-47bb-0310-9956-ffa450edef68
307 lines
10 KiB
XML
307 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<faqs title="Frequently Asked Questions">
|
|
|
|
<part id="general">
|
|
<title>General</title>
|
|
|
|
<faq id="whats-pmd">
|
|
<question>
|
|
What is PMD?
|
|
</question>
|
|
<answer>
|
|
<p>According to the official website (
|
|
<a href="http://pmd.sourceforge.net/">pmd.sourceforge.net</a> ),
|
|
PMD scans Java source code and looks for potential problems like:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Unused local variables</li>
|
|
<li>Empty catch blocks</li>
|
|
<li>Unused parameters</li>
|
|
<li>Empty 'if' statements</li>
|
|
<li>Duplicate import statements</li>
|
|
<li>Unused private methods</li>
|
|
<li>Classes which could be Singletons</li>
|
|
<li>Short/long variable and method names</li>
|
|
</ul>
|
|
|
|
<p>This plugin provides a means to integrate the pmd report into the
|
|
maven process.</p>
|
|
|
|
</answer>
|
|
</faq>
|
|
</part>
|
|
|
|
<part id="installation">
|
|
<title>Installation</title>
|
|
|
|
<faq id="basic-install">
|
|
<question>
|
|
How do I install the maven-pmd-plugin?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
The maven-pmd-plugin is considered an optional maven-plugin, but
|
|
the default installation of maven comes with it.
|
|
|
|
There is nothing special you need to do, other than use it.
|
|
see <a href="#basic-usage">Basic Usage</a> for examples on how to use it.
|
|
</p>
|
|
</answer>
|
|
</faq>
|
|
|
|
<faq id="manual-install">
|
|
<question>
|
|
I want to install a different version of the maven-pmd-plugin than
|
|
what is available to me right now. How do I do that?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
Starting with the <a href="http://maven.apache.org/reference/plugins/plugin/">
|
|
maven-plugin-plugin</a> 1.2 (which first appeared with
|
|
maven 1.0-rc1), you issue the following command to maven to
|
|
download the version of your choice.
|
|
</p>
|
|
<source>
|
|
<![CDATA[
|
|
$ maven -DgroupId=maven -DartifactId=maven-pmd-plugin -Dtype=plugin -Dversion=1.3 plugin:download
|
|
]]>
|
|
</source>
|
|
<p>
|
|
This command will download the plugin, remove the other versions of
|
|
the maven-pmd-plugin and make this recently downloaded version
|
|
immediately available to all projects that depend on maven-pmd-plugin.
|
|
</p>
|
|
</answer>
|
|
</faq>
|
|
|
|
</part>
|
|
|
|
<part id="usage">
|
|
<title>Usage</title>
|
|
|
|
<faq id="basic-usage">
|
|
<question>
|
|
How do I use it?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
The quickest, and easiest way to use the maven-pmd-plugin is to
|
|
add the <code>maven-pmd-plugin</code> entry to your
|
|
<a href="http://maven.apache.org/reference/project-descriptor.html#reports">
|
|
reports</a> section in your project's project.xml
|
|
<a href="http://maven.apache.org/reference/project-descriptor.html">
|
|
project descriptor</a>.
|
|
</p>
|
|
|
|
<source>
|
|
<![CDATA[
|
|
<reports>
|
|
...
|
|
<report>maven-pmd-plugin</report>
|
|
...
|
|
</reports>
|
|
]]>
|
|
</source>
|
|
</answer>
|
|
</faq>
|
|
|
|
<faq id="manual-running">
|
|
<question>
|
|
I don't want to use it via the project.xml. What are my options?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
The PMD plugin can be started through "maven pmd"
|
|
or integrated by using the following code snippet in
|
|
maven.xml:
|
|
</p>
|
|
|
|
<source>
|
|
<![CDATA[
|
|
<?xml version="1.0"?>
|
|
<preGoal name="site:generate">
|
|
<attainGoal name="pmd"/>
|
|
</preGoal>
|
|
]]>
|
|
</source>
|
|
|
|
<p>
|
|
The generated report has to be added manually to the
|
|
website which is usually done with navigation.xml.
|
|
</p>
|
|
|
|
<source>
|
|
<![CDATA[
|
|
<?xml version="1.0"?>
|
|
<menu name="Custom Reports">
|
|
<item name="PMD Report" href="/pmd-report.html"/>
|
|
<!-- Add more custom reports here -->
|
|
</menu>
|
|
]]>
|
|
</source>
|
|
</answer>
|
|
</faq>
|
|
|
|
<faq id="disable-subproject">
|
|
<question>
|
|
I have a large projects with many sub-projects, I want to use
|
|
the maven-pmd-plugin, but not for a specific sub-project.
|
|
How do I accomplish this?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
Assume that you have generated a DB layer having a few
|
|
hundreds Java source files. Apart from being curious you
|
|
don't want to have a PMD report for generated source files.
|
|
Simply put <code>maven.pmd.enable=false</code> into your
|
|
<code>project properties</code> for that one sub-project.
|
|
</p>
|
|
</answer>
|
|
</faq>
|
|
|
|
<faq id="disable-select-files">
|
|
<question>
|
|
How do I disable certain files from being checked by the
|
|
maven-pmd-plugin?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
The maven-pmd-plugin will scan all <code>*.java</code> files in
|
|
your defined <code><sourceDirectory></code> path
|
|
specified in your <a href="http://maven.apache.org/reference/project-descriptor.html">
|
|
project descriptor</a>.
|
|
</p>
|
|
<p>
|
|
Use the <code>maven.pmd.excludes</code> property to exclude
|
|
certain files from being checked by the maven-pmd-plugin.
|
|
</p>
|
|
<p>
|
|
Lets assume that you have generated a DB layer within your project.
|
|
Simply put <code>maven.pmd.excludes=**/database/**</code> into your
|
|
<code>project.properties</code> file to exclude the files in your
|
|
database directory and below.
|
|
</p>
|
|
</answer>
|
|
</faq>
|
|
|
|
<faq id="zillion-violations">
|
|
<question>
|
|
How do I get rid of these zillions of rule violations?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
You could fix the rule violations.
|
|
</p>
|
|
<p>
|
|
On the other hand, if you want to configure the maven-pmd-plugin
|
|
to pick and choose the type of tests to perform, then you need
|
|
to specify your ruleset.
|
|
</p>
|
|
<p>
|
|
There are two ways to accomplish this.
|
|
<ol>
|
|
<li>
|
|
<p>
|
|
Define which default pmd rulesets you want to use in the
|
|
<code>maven.pmd.rulesetfiles</code> property.
|
|
</p>
|
|
|
|
<p>
|
|
The default setting for the <code>maven.pmd.rulesetfiles</code>
|
|
property is:
|
|
<source>
|
|
<![CDATA[
|
|
maven.pmd.rulesetfiles = rulesets/basic.xml,rulesets/unusedcode.xml,rulesets/imports.xml
|
|
]]>
|
|
</source>
|
|
</p>
|
|
<p>
|
|
The following list of default pmd rulesets was obtained from
|
|
the <a href="http://pmd.sourceforge.net/">official pmd
|
|
project</a> page.
|
|
<ul>
|
|
<li><a href="http://pmd.sourceforge.net/rules/basic.html">Basic</a> = <code>ruleset/basic.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/naming.html">Naming</a> = <code>ruleset/naming.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/unusedcode.html">Unused Code</a> = <code>ruleset/unusedcode.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/design.html">Design</a> = <code>ruleset/design.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/imports.html">Import Statements</a> = <code>ruleset/imports.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/junit.html">JUnit Tests</a> = <code>ruleset/junit.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/strings.html">Strings</a> = <code>ruleset/strings.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/braces.html">Braces</a> = <code>ruleset/braces.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/codesize.html">Code Size</a> = <code>ruleset/codesize.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/javabeans.html">Javabeans</a> = <code>ruleset/javabeans.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/coupling.html">Coupling</a> = <code>ruleset/coupling.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/strictexception.html">Strict Exceptions</a> = <code>ruleset/strictexception.xml</code>.</li>
|
|
<li><a href="http://pmd.sourceforge.net/rules/controversial.html">Controversial</a> = <code>ruleset/controversial.xml</code>.</li>
|
|
</ul>
|
|
</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Define a custom ruleset.xml and reference it via the
|
|
<code>maven.pmd.rulesetfiles</code> property.
|
|
</p>
|
|
<p>
|
|
Example of a custom ruleset, saved as file called
|
|
<code>favorite-pmd.xml</code> in your project root.
|
|
<source>
|
|
<![CDATA[
|
|
<?xml version="1.0"?>
|
|
|
|
<ruleset name="Favorites">
|
|
<description>
|
|
The Favorites ruleset contains links to rules that I like to use.
|
|
I like the basic.xml, unusedcode.xml, and import.xml, and some of
|
|
the rules in design.xml, strings.xml, and controversial.xml.
|
|
</description>
|
|
|
|
<rule ref="rulesets/basic.xml" />
|
|
<rule ref="rulesets/unusedcode.xml" />
|
|
<rule ref="rulesets/import.xml" />
|
|
<rule ref="rulesets/design.xml/SimplifyBooleanReturnsRule" />
|
|
<rule ref="rulesets/design.xml/SwitchStmtsShouldHaveDefault" />
|
|
<rule ref="rulesets/strings.xml/StringToString" />
|
|
<rule ref="rulesets/strings.xml/StringInstantiation" />
|
|
<rule ref="rulesets/controversial.xml/UnnecessaryConstructorRule" />
|
|
<rule ref="rulesets/controversial.xml/NullAssignment" />
|
|
<rule ref="rulesets/controversial.xml/UnusedModifier" />
|
|
|
|
</ruleset>
|
|
]]>
|
|
</source>
|
|
</p>
|
|
<p>
|
|
How it's referenced in your <code>project.properties</code>
|
|
file.
|
|
<source>
|
|
<![CDATA[
|
|
maven.pmd.rulesetfiles = ${basedir}/favorite-pmd.xml
|
|
]]>
|
|
</source>
|
|
</p>
|
|
</li>
|
|
</ol>
|
|
</p>
|
|
</answer>
|
|
</faq>
|
|
|
|
<faq id="how-to-upgrade-pmd-jar">
|
|
<question>
|
|
How do I manually upgrade to a newer PMD jar?
|
|
</question>
|
|
<answer>
|
|
<p>
|
|
The JAR picked up the plugin is defined in
|
|
$MAVEN_HOME/plugins/pmd/project.xml and can be
|
|
changed.
|
|
</p>
|
|
</answer>
|
|
|
|
</faq>
|
|
|
|
</part>
|
|
|
|
</faqs>
|
|
|