# Frequently Asked Questions

# General

What is PMD?

According to the official website ( pmd.sourceforge.net ), PMD scans Java source code and looks for potential problems like:

- Unused local variables
- Empty catch blocks
- Unused parameters
- Empty 'if' statements
- Duplicate import statements
- Unused private methods
- Classes which could be Singletons
- Short/long variable and method names

This plugin provides a means to integrate the pmd report into the maven process.

# Installation

How do I install the maven-pmd-plugin?

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 Basic Usage for examples on how to use it.

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?

Starting with the maven-plugin-plugin 1.2 (which first appeared with maven 1.0-rc1), you issue the following command to maven to download the version of your choice.

    $ maven -DgroupId=maven -DartifactId=maven-pmd-plugin -Dtype=plugin -Dversion=1.3 plugin:download

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.

# Usage

How do I use it?

The quickest, and easiest way to use the maven-pmd-plugin is to add the `maven-pmd-plugin` entry to your reports section in your project's project.xml project descriptor.

    <reports>
      ...
      <report>maven-pmd-plugin</report>
      ...
    </reports>

I don't want to use it via the project.xml. What are my options?

The PMD plugin can be started through "maven pmd" or integrated by using the following code snippet in maven.xml:

    <?xml version="1.0"?>
      <preGoal name="site:generate">
        <attainGoal name="pmd"/>
      </preGoal>

The generated report has to be added manually to the website which is usually done with navigation.xml.

    <?xml version="1.0"?>
      <menu name="Custom Reports">
        <item name="PMD Report" href="/pmd-report.html"/>
        <!-- Add more custom reports here -->
      </menu>

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?

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 `maven.pmd.enable=false` into your `project properties` for that one sub-project.

How do I disable certain files from being checked by the maven-pmd-plugin?

The maven-pmd-plugin will scan all `*.java` files in your defined `<sourceDirectory>` path specified in your project descriptor.

Use the `maven.pmd.excludes` property to exclude certain files from being checked by the maven-pmd-plugin.

Lets assume that you have generated a DB layer within your project. Simply put `maven.pmd.excludes=**/database/**` into your `project.properties` file to exclude the files in your database directory and below.

How do I get rid of these zillions of rule violations?

You could fix the rule violations.

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.

There are two ways to accomplish this.

1. Define which default pmd rulesets you want to use in the `maven.pmd.rulesetfiles` property.

   The default setting for the `maven.pmd.rulesetfiles` property is:

       maven.pmd.rulesetfiles = rulesets/basic.xml,rulesets/unusedcode.xml,rulesets/imports.xml

   The following list of default pmd rulesets was obtained from the official pmd project page.

   - Basic = `ruleset/basic.xml`.
   - Naming = `ruleset/naming.xml`.
   - Unused Code = `ruleset/unusedcode.xml`.
   - Design = `ruleset/design.xml`.
   - Import Statements = `ruleset/imports.xml`.
   - JUnit Tests = `ruleset/junit.xml`.
   - Strings = `ruleset/strings.xml`.
   - Braces = `ruleset/braces.xml`.
   - Code Size = `ruleset/codesize.xml`.
   - Javabeans = `ruleset/javabeans.xml`.
   - Coupling = `ruleset/coupling.xml`.
   - Strict Exceptions = `ruleset/strictexception.xml`.
   - Controversial = `ruleset/controversial.xml`.

2. Define a custom ruleset.xml and reference it via the `maven.pmd.rulesetfiles` property.

   Example of a custom ruleset, saved as file called `favorite-pmd.xml` in your project root.

       <?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>

   How it's referenced in your `project.properties` file.

       maven.pmd.rulesetfiles = ${basedir}/favorite-pmd.xml

How do I manually upgrade to a newer PMD jar?

The JAR picked up the plugin is defined in $MAVEN_HOME/plugins/pmd/project.xml and can be changed.

Alternatively, you can specify the following in your ~/build.properties file:

    maven.jar.override=on
    maven.jar.pmd=1.4