phoedos/pmd
1
1 Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Convert xdoc to markdown - usage pages

Browse Source
This commit is contained in:
Andreas Dangel committed 2015-03-14 22:26:35 +01:00
1 parent b182001920
commit c5622d9c21
23 files changed
+1475 -1546
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

src/site/markdown/customizing/cpd-parser-howto.md
+22
View File
@@ -0,0 +1,22 @@
<!--
<author email="belaran@gmail.com">Romain PELISSE</author>
-->
# How to add a new language to CPD
If you wish CPD to parse a unsupported language, you can easily develop a new parser
for CPD. All you need to is implements the following interface:
* net.sourceforge.pmd.cpd.Language
* net.sourceforge.pmd.cpd.Tokenizer
Do not forget to the follow the proper naming convention, as the CPD parser factory
use this convention:
* Language Name + "Language"
* Tokenizer Name + "Tokenizer"
For instance, if you develop a python parser, you should have two classes named PythonLanguage
and PythonTokenizer.
To test your parser, just package it in a jar and add your jar to the classpath.
src/site/markdown/usage/ant-task.md
+311
View File
File diff suppressed because it is too large. Load diff
src/site/markdown/usage/ci-plugins.md
+25
View File
@@ -0,0 +1,25 @@
<!--
<author email="belaran@gmail.com">Romain PELISSE</author>
-->
# Continuous Integrations plugins
## Introduction
PMD can be integrate through some of the Continuous Integration tools that exist now.
Here is a list of known (to us) plugin to do so.
## Hudson Plugin
Hafner Ullrich has developed a [PMD plugin][hudsonplugin] for Hudson.
Please check the plugin homepage for more info.
[hudsonplugin]: http://hudson.gotdns.com/wiki/display/HUDSON/PMD+Plugin
## Continuum
Continous does not have a plugin for PMD per see, but can failed the build according to the
result of the PMD maven plugin.
<!-- TODO: Find out about other plugins ? -->
src/site/markdown/usage/cpd-usage.md
+235
View File
@@ -0,0 +1,235 @@
<!--
<author email="tom@infoether.com">Tom Copeland</author>
-->
# Finding duplicated code
Or - Finding copied and pasted code
## Overview
Duplicate code can be hard to find, especially in a large project.
But PMD's Copy/Paste Detector (CPD) can find it for you!
CPD has been through three major incarnations:
* First we wrote it using a variant of Michael Wise's Greedy String Tiling algorithm (our variant is described
[here](http://www.onjava.com/pub/a/onjava/2003/03/12/pmd_cpd.html)).
* Then it was completely rewritten by Brian Ewins using the
[Burrows-Wheeler transform](http://dogma.net/markn/articles/bwt/bwt.htm).
* Finally, it was rewritten by Steve Hawkins to use the
[Karp-Rabin](http://www.nist.gov/dads/HTML/karpRabin.html) string matching algorithm.
Each rewrite made it much faster, and now it can process the JDK 1.4 java.* packages in about 4 seconds
(on my workstation, at least).
Here's a [screenshot](images/screenshot_cpd.png) of CPD after running on the JDK java.lang package.
Note that CPD works with Java, JSP, C, C++, C#, Fortran and PHP code. Your own language is missing?
See how to add it [here](../customizing/cpd-parser-howto.html).
CPD is included with PMD, which you can download [here](http://sourceforge.net/projects/pmd/files/pmd/).
Or, if you have [Java Web Start](http://java.sun.com/products/javawebstart/),
you can [run CPD by clicking here](http://pmd.sourceforge.net/cpd.jnlp).
[Here](./cpdresults.txt) are the duplicates CPD found in the JDK 1.4 source code.
[Here](./cpp_cpdresults.txt) are the duplicates CPD found in the APACHE_2_0_BRANCH branch of Apache
(just the `httpd-2.0/server/` directory).
## Ant task
Andy Glover wrote an Ant task for CPD; here's how to use it:
<target name="cpd">
<taskdef name="cpd" classname="net.sourceforge.pmd.cpd.CPDTask" />
<cpd minimumTokenCount="100" outputFile="/home/tom/cpd.txt">
<fileset dir="/home/tom/tmp/ant">
<include name="**/*.java"/>
</fileset>
</cpd>
</target>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td valign="top"><b>Applies for language</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">
The character set encoding (e.g., UTF-8) to use when reading the source code files, but also when
producing the report. A piece of warning, even if you set properly the encoding value,
let's say to UTF-8, but you are running CPD encoded with CP1252, you may end up with not UTF-8 file.
Indeed, CPD copy piece of source code in its report directly, therefore, the source files
keep their encoding.<br />
If not specified, CPD uses the system default encoding.
</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">format</td>
<td valign="top">The format of the report (e.g. `csv`, `text`, `xml`); defaults to `text`.</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">ignoreLiterals</td>
<td valign="top">
if `true`, CPD ignores literal
value differences when evaluating a duplicate block. This means that `foo=42;` and `foo=43;`
will be seen as equivalent. You may want to run PMD with this option off to start with and
then switch it on to see what it turns up; defaults to `false`.
</td>
<td valign="top">java</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">ignoreIdentifiers</td>
<td valign="top">
Similar to `ignoreLiterals` but for identifiers; i.e., variable names, methods names,
and so forth; defaults to `false`.
</td>
<td valign="top">java</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">ignoreAnnotations</td>
<td valign="top">
Ignore annotations. More and more modern frameworks use annotations on classes and methods,
which can be very redundant and trigger CPD matches. With J2EE (CDI, Transaction Handling, etc)
and Spring (everything) annotations become very redundant. Often classes or methods have the
same 5-6 lines of annotations. This causes false positives; defaults to `false`.
</td>
<td valign="top">java</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipDuplicateFiles</td>
<td valign="top">
Ignore multiple copies of files of the same name and length in comparison; defaults to `false`.
</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipLexicalErrors</td>
<td valign="top">
Skip files which can't be tokenized due to invalid characters instead of aborting CPD; defaults to `false`.
</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipBlocks</td>
<td valign="top">
Enables or disabled skipping of blocks like a pre-processor; defaults to `true`.
See also option skipBlocksPattern.
</td>
<td valign="top">cpp</td>
<td valign="top">No</td>
</tr>
<tr>
<td valign="top">skipBlocksPattern</td>
<td valign="top">
Configures the pattern, to find the blocks to skip. It is a string property and contains of two parts,
separated by `|`. The first part is the start pattern, the second part is the ending pattern.
The default value is `#if 0|#endif`.
</td>
<td valign="top">cpp</td>
<td valign="top">no</td>
</tr>
<tr>
<td valign="top">language</td>
<td valign="top">
Flag to select the appropriate language (e.g. `c`, `cpp`, `cs`, `java`, `jsp`, `php`, `ruby`, `fortran`
`ecmascript`, and `plsql`); defaults to `java`.
</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">minimumtokencount</td>
<td valign="top">A positive integer indicating the minimum duplicate size.</td>
<td valign="top"></td>
<td valign="top" align="center">Yes</td>
</tr>
<tr>
<td valign="top">outputfile</td>
<td valign="top">The destination file for the report. If not specified the console will be used instead.</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
</table>
Also, you can get verbose output from this task by running ant with the `-v` flag; i.e.:
ant -v -f mybuildfile.xml cpd
Also, you can get an HTML report from CPD by using the XSLT script in pmd/etc/xslt/cpdhtml.xslt. Just run
the CPD task as usual and right after it invoke the Ant XSLT script like this:
<xslt in="cpd.xml" style="etc/xslt/cpdhtml.xslt" out="cpd.html" />
## Command line usage
To run CPD from the command line, just give it the minimum duplicate size and the source directory:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java
You can also specify the language:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /path/to/c/source --language cpp
You may wish to check sources that are stored in different directories:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /path/to/other/source --files /path/to/other/source --files /path/to/other/source --language fortran
<em>There should be no limit to the number of '--files', you may add... But if you stumble one, please tell us !</em>
And if you're checking a C source tree with duplicate files in different architecture directories
you can skip those using --skip-duplicate-files:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /path/to/c/source --language cpp --skip-duplicate-files
You can also the encoding to use when parsing files:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java --encoding utf-16le
You can also specify a report format - here we're using the XML report:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java --format net.sourceforge.pmd.cpd.XMLRenderer
The default format is a text report, and there's also a `net.sourceforge.pmd.cpd.CSVRenderer` report.
Note that CPD is pretty memory-hungry; you may need to give Java more memory to run it, like this:
$ java -Xmx512m net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java
If you specify a source directory but don't want to scan the sub-directories, you can use the non-recursive option:
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --non-recursive --files /usr/local/java/src/java
Please note that if CPD detects duplicated source code, it will exit with status 4 (since 5.0).
This behavior has been introduced to ease CPD integration into scrips or hook, such as SVN hooks.
## Suppression
By adding the annotations **@SuppressWarnings("CPD-START")** and **@SuppressWarnings("CPD-END")**
all code within will be ignored by CPD - thus you can avoid false positivs.
This provides the ability to ignore sections of source code, such as switch/case statements or parameterized factories.
//enable suppression
@SuppressWarnings("CPD-START")
public Object someParameterizedFactoryMethod(int x) throws Exception {
// any code here will be ignored for the duplication detection
}
//disable suppression
@SuppressWarnings("CPD-END)
public void nextMethod() {
}
src/site/markdown/usage/installing.md.vm
+37
View File
@@ -0,0 +1,37 @@
<!--
<author>Tom Copeland</author>
<author email="xlv@users.sourceforge.net">Xavier Le Vourch</author>
-->
# How to install PMD (and CPD)
## Windows
Requirements:
* Java JRE 1.6 or higher
* [Winzip](http://winzip.com) or the free [7-zip](http://www.7-zip.org/)
Download the latest binary distribution - i.e., pmd-bin-x.xx.zip
Unzip it into any directory, i.e., c:\pmd\
## Unix
Requirements:
* Java JRE 1.6 or higher
* The Unix "zip" utility [InfoZip](http://www.info-zip.org/pub/infozip/)
Download the latest binary distribution - i.e., pmd-bin-x.xx.zip
Unzip it into any directory:
[tom@hal tmp]$ unzip -q pmd-bin-${project.version}.zip
[tom@hal tmp]$ ls -l
total 4640
drwxrwxr-x 5 tom tom 4096 Apr 17 16:38 pmd-bin-${project.version}
-rw-rw-r-- 1 tom tom 4733312 Jun 9 15:44 pmd-bin-${project.version}.zip
[tom@hal tmp]$
Note that the PMD jar file contains the [CPD](cpd-usage.html) utility as well.
src/site/markdown/usage/integrations.md.vm
+410
View File
File diff suppressed because it is too large. Load diff
src/site/markdown/usage/jspsupport.md
+51
View File
@@ -0,0 +1,51 @@
<!--
<author email="tom@infoether.org">Pieter Vanraemdonck</author>
-->
# JSP Support
## What is currently supported and what is not
In short, JSP files that are XHTML-compliant, are supported.
Except for files that contain inline DTDs; only references to external
DTD files are supported (having inline DTD will result in a parsing
error).
The XHTML support means that:
* opening tags must be accompanied by corresponding *closing tags*
(or they must be empty tags). This means that currently a "&lt;HR&gt;"
tag without corresponding closing tag will result in a parsing error.
* *attribute values* must be *surrounded by* single or double *quotes*. This means that the following syntax
will result in a parsing error:
&lt;MyTag myAttr1=true myAttr2=1024/&gt;
* &lt; and &gt; characters must be *escaped*, or put inside a CDATA section.
PMD creates a "Abstract Syntax Tree" representation of source code; the rules use such a tree as input.
For JSP files, the following constructs are parsed into nodes of the tree:
* XML-elements, XML-attributes, XML-comments, doctype-declarations, CDATA
* JSP-directives, JSP-declarations, JSP-comments, JSP-scriptlets, JSP-expressions,
Expression Language expressions, JSF value bindings
* everything else is seen as flat text nodes.
* Java code (e.g. in JSP-scriptlets) and EL expressions are not parsed or
further broken down. If you want to create rules that check the code
inside EL expressions or JSP scriptlets (a.o.), you currently would
have to do "manual" string manipulation (e.g. using regular expressions).
## How to use it
Using the command-line interface, two new options can be used in the arguments string:
* "-jsp" : this triggers checking JSP files (they are not checked by default)
* "-nojava" : this tells PMD not to check java source files (they are checked by default)
Using the Ant task, you decide if PMD must check JSP files by choosing
what files are given to the PMD task. If you use a fileset that
contains only ".java" files, JSP files obviously will not be checked.
If you want to call the PMD API for checking JSP files, you should investigate the javadoc of PMD.
src/site/markdown/usage/maven-plugin.md
+49
View File
@@ -0,0 +1,49 @@
<!--
<author email="mikkey@users.sourceforge.net">Miguel Griffa</author>
-->
# Maven 1 PMD plugin
This page is about the maven 1 PMD plugin. The maven 2 PMD plugin page is available
[here](mvn-plugin.html).
## Running the pmd plugin
### report
To include the Maven report in the project reports section add the following line under
the reports element in your project.xml:
<report>maven-pmd-plugin</report>
This will add an entry to the 'project reports' section with the PMD report.
### manual
To run PMD on a Maven project without adding it as a report, simply run
maven pmd xdoc
The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
## Customization
### Changing rulesets
To specify a set of official, built-in rulesets to be used set them in the property
<em>maven.pmd.rulesets</em>. You can include this setting in your project.properties file.
A clean strategy for customizing which rules to use for a project is to write a ruleset file.
In this file you can define which rules to use, add custom rules, and
customizing which rules to include/exclude from official rulesets. More information on
writing a ruleset can be found [here](../customizing/howtomakearuleset.html).
Add to the root of your Maven project a pmd.xml file which contains the ruleset mentioned in
the previous paragraph. Add the following property to your project now:
maven.pmd.rulesetfiles = ${basedir}/pmd.xml
## Reference
See the PMD plugin project page here:
<http://maven.apache.org/maven-1.x/plugins/pmd/>
src/site/markdown/usage/mvn-plugin.md
+91
View File
@@ -0,0 +1,91 @@
<!--
<author email="belaran@gmail.com">Romain PELISSE</author>
-->
# Maven 2 plugin
## Running the pmd plugin
### report
To include the mvn report in the project reports section add the following lines under
the reports element in your pom.xml:
<project>
...
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
</plugin>
</plugins>
</reporting>
...
</project>
This will add an entry to the 'project reports' section with the PMD report.
### manual
To run PMD on a Maven project without adding it as a report, simply run
mvn pmd:pmd
The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
## Customization
### Changing rulesets
To specify a ruleset, simply edit the previous configuration:
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<configuration>
<rulesets>
<ruleset>/rulesets/java/braces.xml</ruleset>
<ruleset>/rulesets/java/naming.xml</ruleset>
<ruleset>d:\rulesets\strings.xml</ruleset>
<ruleset>http://localhost/design.xml</ruleset>
</rulesets>
</configuration>
</plugin>
</plugins>
</reporting>
The value of the 'ruleset' value can either be a relative address, an absolute address or even an url.
A clean strategy for customizing which rules to use for a project is to write a ruleset file.
In this file you can define which rules to use, add custom rules, and
customizing which rules to include/exclude from official rulesets. More information on
writing a ruleset can be found [here](../customizing/howtomakearuleset.html).
Note that if you include other rulesets in your own rulesets, you have to be sure that the plugin
will be able to resolve those other ruleset references.
### Other configurations
The Maven 2 PMD plugin allows you to configure CPD, targetJDK, and the use of XRef to link
the report to html source files, and the file encoding:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<configuration>
<linkXref>true</linkXref>
<sourceEncoding>ISO-8859-1</sourceEncoding>
<minimumTokens>30</minimumTokens>
<targetJdk>1.4</targetJdk>
</configuration>
</plugin>
## Reference
For more data, please see the well documented PMD plugin project page here:
<http://maven.apache.org/plugins/maven-pmd-plugin/index.html>
src/site/markdown/usage/running.md.vm
+78
View File
@@ -0,0 +1,78 @@
<!--
<author email="tom@infoether.com">Tom Copeland</author>
-->
# Running PMD via command line
## On Linux and other UNIX based operating system...
PMD comes with several command line utilities. Previously, each of them had its own start up script, but this has been
greatly simplified since PMD 5.0... at least for Unix systems. There is now only one script, called "run.sh", inside
the bin/ directory of PMD distribution.
The first argument is the name of the utility you want to execute ('pmd', 'designer',...) and the other arguments are
specific to the utility used.
$ ./bin/run.sh pmd -d ../../../src/main/java/ -f text -R rulesets/java/basic.xml -version 1.7 -language java
.../src/main/java/net/sourceforge/pmd/RuleSet.java:123 These nested if statements could be combined
.../src/main/java/net/sourceforge/pmd/RuleSet.java:231 Useless parentheses.
.../src/main/java/net/sourceforge/pmd/RuleSet.java:232 Useless parentheses.
.../src/main/java/net/sourceforge/pmd/RuleSet.java:357 These nested if statements could be combined
.../src/main/java/net/sourceforge/pmd/RuleSetWriter.java:66 Avoid empty catch blocks
.../src/main/java/net/sourceforge/pmd/RuleSetWriter.java:269 Useless parentheses.
* Type "./run.sh pmd -d [filename|jar or zip file containing source code|directory] -f [report format] -R [ruleset file]", i.e:
/home/user/tmp/pmd-bin-${project.version}/pmd/bin>./run.sh pmd -d /home/user/data/pmd/pmd/test-data/Unused1.java -f xml -R rulesets/java/unusedcode.xml
<?xml version="1.0"?><pmd>
<file name="/home/user/data/pmd/pmd/test-data/Unused1.java">
<violation line="5" rule="UnusedLocalVariable">
Avoid unused local variables such as 'fr'
</violation>
</file></pmd>
/home/user/tmp/pmd-bin-${project.version}/pmd/bin>
## Basic usage for Windows
* Type "pmd -d [filename|jar or zip file containing source code|directory] -f [report format] -R [ruleset file]", i.e:
C:\tmp\pmd-bin-${project.version}\pmd\bin>pmd -d c:\data\pmd\pmd\test-data\Unused1.java -f xml -R rulesets/java/unusedcode.xml
<?xml version="1.0"?><pmd>
<file name="c:\data\pmd\pmd\test-data\Unused1.java">
<violation line="5" rule="UnusedLocalVariable">
Avoid unused local variables such as 'fr'
</violation>
</file></pmd>
C:\tmp\pmd-bin-${project.version}\pmd\bin>
You can pass a file name, a directory name, or a jar or zip file name containing Java source code to PMD.
Also, the PMD binary distribution includes the ruleset files
inside the jar file - even though the "rulesets/java/unusedcode.xml" parameter
above looks like a filesystem reference, it's really being used by a getResourceAsStream() call
to load it out of the PMD jar file. And the same applies to the example below.
* If you want to run PMD without the batch file, you can do a:
C:\tmp\pmd-bin-${project.version}\pmd>java -Djava.ext.dirs=lib
net.sourceforge.pmd.PMD
-d c:\j2sdk1.4.1_01\src\java\lang
-f xml
-R rulesets/java/imports.xml
## Other options
The tool comes with a rather extensive help text, simply running with `--help`!
## Renderers
PMD comes with four different renderer types:
* **csv**, provides a Comma Separated Values.
* **text**, provides a basic text output.
* **xml**, provides report output in XML format.
* **html**, provides report as a basic HTML page.
* ... and many more ! See the tool help text...
src/site/markdown/usage/suppressing.md
+165
View File
@@ -0,0 +1,165 @@
<!--
<author email="tom@infoether.com">Tom Copeland</author>
-->
# Suppressing warnings
PMD provides several methods by which Rule violations can be suppressed.
Follow these steps to help you determine which expression method works best
for you:
1. Is the thing you need to suppress universally appealing to other
users of PMD, or is it a false positive? Can you modify the Rule to
support this specific suppression via a configuration property, or to
fix the false positive? If you can do this, then please do so, and
submit a patch back to the PMD project. Since PMD is built by users
for users, your help would be greatly appreciated by everyone. If you
cannot...
2. Can you use Annotations or the NOPMD marker to work around your
particular issue on a case by case basis? If not...
3. Can a regular expression matching the violation message work
around your particular issue? If not...
4. Can a XPath query on the violation node work around your particular
issue? If not...
5. Your last and final option is to see the first point about
changing the Rule, but you do not need to submit a patch back to the
PMD project.
If you need to modify the Rule, see [How to write a rule](../customizing/howtowritearule.html).
Otherwise, the other suppression methods are explain in the following sections.
## Annotations
You can use a JDK 1.5 annotation to suppress PMD warnings, like this:
// This will suppress all the PMD warnings in this class
@SuppressWarnings("PMD")
public class Bar {
void bar() {
int foo;
}
}
Or you can suppress one rule with an annotation like this:
// This will suppress UnusedLocalVariable warnings in this class
@SuppressWarnings("PMD.UnusedLocalVariable")
public class Bar {
void bar() {
int foo;
}
}
PMD also obeys the JDK annotation @SuppressWarnings("unused"), which will apply to all rules in the unused ruleset.
// This will suppress UnusedLocalVariable and UnusedPrivateMethod warnings in this class
@SuppressWarnings("unused")
public class Bar {
void bar() {
int foo;
}
private void foobar(){}
}
## NOPMD
Alternatively, you can tell PMD to ignore a specific line by using the "NOPMD" marker, like this:
public class Bar {
// 'bar' is accessed by a native method, so we want to suppress warnings for it
private int bar; //NOPMD
}
You can use whatever text string you want to suppress warnings, for example, here's
how to use TURN\_OFF\_WARNINGS as the suppressor:
$ cat Foo.java
public class Foo {
void bar() {
int x = 2; // TURN_OFF_WARNINGS
}
}
$ ./run.sh pmd -d Foo.java -f text -R java-unusedcode -suppressmarker TURN_OFF_WARNINGS
No problems found!
UnusedLocalVariable rule violation suppressed by //NOPMD in /home/tom/pmd/pmd/bin/Foo.java
Note that PMD expects the //NOPMD marker to be on the same line as the violation. So, for
example, if you want to suppress an "empty if statement" warning, you'll need to place it on
the line containing the "if" keyword, e.g.:
$ cat ~/tmp/Foo.java
public class Foo {
void bar() {
int x = 42;
if (x &gt; 5) { // NOPMD
}
}
}
$ java net.sourceforge.pmd.PMD -d ~/tmp/Foo.java -f text -R java-basic
No problems found!
$
A message placed after the NOPMD marker will get placed in the report, e.g.:
public class Foo {
void bar() {
try {
bar();
} catch (FileNotFoundException e) {} // NOPMD - this surely will never happen
}
}
## Violation Suppress Regex
If a particular Rule does not provide a property to customize behavior
sufficiently, you can fall back to using the global 'violationSuppressRegex'
property. This property defines a regular expression to match against the
message of the violation. If the regular expression matches,
then the violation will be suppressed.
When using a Rule reference in a RuleSet XML, you can customize the
Rule by adding the 'violationSuppressRegex' property. For example, to
suppress reporting specifically named parameters which are unused:
<rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter">
<properties>
<property name="violationSuppressRegex" value=".*'mySpecialParameterName'.*"/>
</properties>
</rule>
Note for message based suppression to work, you must know who to write
a regular expression that matches the message of violations you wish to
suppress. Regular expressions are explained in the JavaDoc for standard
Java class java.util.regex.Pattern.
## Violation Suppress XPath
If a particular Rule does not provide a property to customize behavior
sufficiently, you can fall back to using the global 'violationSuppressXPath'
property. This property defines an XPath query to be executed using the
violation node as the starting point. If the XPath query matches anything,
then the violation will be suppressed.
When using a Rule reference in a RuleSet XML, you can customize the
Rule by adding the 'violationSuppressXPath' property. For example, to
suppress reporting specifically typed parameters which are unused:
<rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter">
<properties>
<property name="violationSuppressXPath" value=".[typeof('java.lang.String')]"/>
</properties>
</rule>
Note for XPath based suppression to work, you must know how to write
an XPath query that matches the AST structure of the nodes of the
violations you wish to suppress. XPath queries are explained in
[XPath Rule tutorial](../customizing/xpathruletutorial.html).
Suggestions? Comments? Post them [here](http://sourceforge.net/p/pmd/discussion/188192). Thanks!
src/site/site.xml
+1
View File
@@ -90,6 +90,7 @@
<item href="/customizing/pmd-developer.html" name="PMD developers information"/>
<item href="/customizing/pmd-release-process.html" name="PMD Release Process"/>
<item href="/customizing/new-language.html" name="New Language"/>
<item href="/customizing/cpd-parser-howto.html" name="New CPD Language"/>
</menu>
<menu name="For example">
<item href="../scoreboard.html" name="Run PMD on a Sourceforge project"/>
src/site/xdoc/usage/ant-task.xml
-347
View File
File diff suppressed because it is too large. Load diff
src/site/xdoc/usage/ci-plugins.xml
-23
View File
@@ -1,23 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="belaran@gmail.com">Romain PELISSE</author>
<title>Continuous Integrations plugins</title>
</properties>
<body>
<section name="Introduction">
<p>PMD can be integrate through some of the Continuous Integration tools that exist now. Here is a list of known (to us) plugin to do so.</p>
</section>
<section name="Hudson Plugin">
<p>Hafner Ullrich has developed a <a href="http://hudson.gotdns.com/wiki/display/HUDSON/PMD+Plugin">PMD plugin</a> for Hudson. Please check the plugin homepage for more info.</p>
</section>
<section name="Continuum">
<p>Continous does not have a plugin for PMD per see, but can failed the build according to the result of the PMD maven plugin.</p>
</section>
<!-- TODO: Find out about other plugins ? -->
</body>
</document>
src/site/xdoc/usage/cpd-parser-howto.xml
-31
View File
@@ -1,31 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="belaran@gmail.com">Romain PELISSE</author>
<title>How to add a new language to CPD</title>
</properties>
<body>
<section name="How to add a new language to CPD">
<p>
If you wish CPD to parse a unsupported language, you can easily develop a new parser
for CPD. All you need to is implements the following interface:
<ol>
<li>net.sourceforge.pmd.cpd.Language</li>
<li>net.sourceforge.pmd.cpd.Tokenizer</li>
</ol>
Do not forget to the follow the proper naming convention, as the CPD parser factory
use this convention:
<ul>
<li>Language Name + "Language"</li>
<li>Tokenizer Name + "Tokenizer"</li>
</ul>
For instance, if you develop a python parser, you should have two classes named PythonLanguage
and PythonTokenizer.
</p>
<p>
To test your parser, just package it in a jar and add your jar to the classpath.
</p>
</section>
</body>
</document>
src/site/xdoc/usage/cpd-usage.xml
-212
View File
@@ -1,212 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="tom@infoether.com">Tom Copeland</author>
<title>Finding copied and pasted code</title>
</properties>
<body>
<section name="Finding duplicate code">
<subsection name="Overview">
<p>Duplicate code can be hard to find, especially in a large project. But PMD's Copy/Paste Detector (CPD) can find it for you!
CPD has been through three major incarnations:</p>
<ul>
<li>First we wrote it using a variant of Michael Wise's Greedy String Tiling algorithm (our variant is described
<a href="http://www.onjava.com/pub/a/onjava/2003/03/12/pmd_cpd.html">here</a>)</li>
<li>Then it was completely
rewritten by Brian Ewins using the
<a href="http://dogma.net/markn/articles/bwt/bwt.htm">Burrows-Wheeler transform</a></li>
<li>Finally, it was rewritten by Steve Hawkins to use the
<a href="http://www.nist.gov/dads/HTML/karpRabin.html">Karp-Rabin</a> string matching algorithm.</li>
</ul>
<p>Each rewrite made it much faster, and now it can process the JDK 1.4 java.* packages in about 4 seconds (on my workstation, at least).</p>
<p>Here's a <a href="images/screenshot_cpd.png">screenshot</a> of CPD after running on the JDK java.lang package.</p>
<p>Note that CPD works with Java, JSP, C, C++, C#, Fortran and PHP code. Your own language is missing ? See how to add it <a href="cpd-parser-howto.html">here</a></p>
<p>CPD is included with PMD, which you can download <a href="http://sourceforge.net/projects/pmd/files/pmd/">here</a>.
Or, if you have <a href="http://java.sun.com/products/javawebstart/">Java Web Start</a>, you can <a href="http://pmd.sourceforge.net/cpd.jnlp">run CPD by clicking here</a>.
</p>
<p><a href="./cpdresults.txt">Here</a> are the duplicates CPD found in the JDK 1.4 source code.</p>
<p><a href="./cpp_cpdresults.txt">Here</a> are the duplicates CPD found in the APACHE_2_0_BRANCH branch of Apache
(just the <code>httpd-2.0/server/</code> directory).</p>
</subsection>
<subsection name="Ant task">
<p>Andy Glover wrote an Ant task for CPD; here's how to use it:</p>
<source>
<![CDATA[
<target name="cpd">
<taskdef name="cpd" classname="net.sourceforge.pmd.cpd.CPDTask" />
<cpd minimumTokenCount="100" outputFile="/home/tom/cpd.txt">
<fileset dir="/home/tom/tmp/ant">
<include name="**/*.java"/>
</fileset>
</cpd>
</target>
]]>
</source>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td valign="top"><b>Applies for language</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">The character set encoding (e.g., UTF-8) to use when reading the source code files, but also when producing the report. A piece of warning, even if you set properly the encoding value, let's say to UTF-8, but you are running CPD encoded with CP1252, you may end up with not UTF-8 file. Indeed, CPD copy piece of source code in its report directly, therefore, the source files keep their encoding.<br>If not specified, CPD uses the system default encoding.</br></td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">format</td>
<td valign="top">The format of the report (e.g. <code>csv</code>, <code>text</code>, <code>xml</code>); defaults to <code>text</code>.</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">ignoreLiterals</td>
<td valign="top">if <code>true</code>, CPD ignores literal
value differences when evaluating a duplicate block. This means that <code>foo=42;</code> and <code>foo=43;</code>
will be seen as equivalent. You may want to run PMD with this option off to start with and
then switch it on to see what it turns up; defaults to <code>false</code>.</td>
<td valign="top">java</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">ignoreIdentifiers</td>
<td valign="top">Similar to <code>ignoreLiterals</code> but for identifiers; i.e., variable names, methods names, and so forth; defaults to <code>false</code>.</td>
<td valign="top">java</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">ignoreAnnotations</td>
<td valign="top">Ignore annotations. More and more modern frameworks use annotations on classes and methods, which can be very redundant and trigger CPD matches. With J2EE (CDI, Transaction Handling, etc) and Spring (everything) annotations become very redundant. Often classes or methods have the same 5-6 lines of annotations. This causes false positives; defaults to <code>false</code>.</td>
<td valign="top">java</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipDuplicateFiles</td>
<td valign="top">Ignore multiple copies of files of the same name and length in comparison; defaults to <code>false</code>.</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipLexicalErrors</td>
<td valign="top">Skip files which can't be tokenized due to invalid characters instead of aborting CPD; defaults to <code>false</code>.</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipBlocks</td>
<td valign="top">Enables or disabled skipping of blocks like a pre-processor; defaults to <code>true</code>. See also option skipBlocksPattern.</td>
<td valign="top">cpp</td>
<td valign="top">No</td>
</tr>
<tr>
<td valign="top">skipBlocksPattern</td>
<td valign="top">Configures the pattern, to find the blocks to skip. It is a string property and contains of two parts, separated by <code>|</code>.
The first part is the start pattern, the second part is the ending pattern.
The default value is <code>#if 0|#endif</code>.</td>
<td valign="top">cpp</td>
<td valign="top">no</td>
</tr>
<tr>
<td valign="top">language</td>
<td valign="top">
Flag to select the appropriate language (e.g. <code>c</code>, <code>cpp</code>, <code>cs</code>,
<code>java</code>, <code>jsp</code>, <code>php</code>, <code>ruby</code>, <code>fortran</code>
<code>ecmascript</code>, and <code>plsql</code>);
defaults to <code>java</code>.
</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">minimumtokencount</td>
<td valign="top">A positive integer indicating the minimum duplicate size.</td>
<td valign="top"></td>
<td valign="top" align="center">Yes</td>
</tr>
<tr>
<td valign="top">outputfile</td>
<td valign="top">The destination file for the report. If not specified the console will be used instead.</td>
<td valign="top"></td>
<td valign="top" align="center">No</td>
</tr>
</table>
<p>Also, you can get verbose output from this task by running ant with the <code>-v</code> flag; i.e.:</p>
<source>
ant -v -f mybuildfile.xml cpd
</source>
<p>Also, you can get an HTML report from CPD by using the XSLT script in pmd/etc/xslt/cpdhtml.xslt. Just run
the CPD task as usual and right after it invoke the Ant XSLT script like this:</p>
<source>
<![CDATA[
<xslt in="cpd.xml" style="etc/xslt/cpdhtml.xslt" out="cpd.html" />
]]>
</source>
</subsection>
<subsection name="Command line usage">
<p>To run CPD from the command line, just give it the minimum duplicate size and the source directory:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java
</source>
<p>You can also specify the language:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /path/to/c/source --language cpp
</source>
<p>You may wish to check sources that are stored in different directories:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /path/to/other/source --files /path/to/other/source --files /path/to/other/source --language fortran
</source>
<p><span style="font-style : italic;">There should be no limit to the number of '--files', you may add... But if you stumble one, please tell us !</span></p>
<p>And if you're checking a C source tree with duplicate files in different architecture directories
you can skip those using --skip-duplicate-files:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /path/to/c/source --language cpp --skip-duplicate-files
</source>
<p>You can also the encoding to use when parsing files:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java --encoding utf-16le
</source>
<p>You can also specify a report format - here we're using the XML report:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java --format net.sourceforge.pmd.cpd.XMLRenderer
</source>
<p>The default format is a text report, and there's also a <code>net.sourceforge.pmd.cpd.CSVRenderer</code> report.</p>
<p>Note that CPD is pretty memory-hungry; you may need to give Java more memory to run it, like this:</p>
<source>
$ java -Xmx512m net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /usr/local/java/src/java
</source>
<p>If you specify a source directory but don't want to scan the sub-directories, you can use the non-recursive option:</p>
<source>
$ java net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --non-recursive --files /usr/local/java/src/java
</source>
<p>Please note that if CPD detects duplicated source code, it will exit with status 4 (since 5.0). This behavior has been introduced to ease CPD integration into scrips or
hook, such as SVN hooks.</p>
</subsection>
<subsection name="Suppression">
By adding the annotations <strong>@SuppressWarnings("CPD-START")</strong> and <strong>@SuppressWarnings("CPD-END")</strong>
all code within will be ignored by CPD - thus you can avoid false positivs.
This provides the ability to ignore sections of source code, such as switch/case statements or parameterized factories.
<source>
//enable suppression
@SuppressWarnings("CPD-START")
public Object someParameterizedFactoryMethod(int x) throws Exception {
// any code here will be ignored for the duplication detection
}
//disable suppression
@SuppressWarnings("CPD-END)
public void nextMethod() {
}
</source>
</subsection>
</section>
</body>
</document>
src/site/xdoc/usage/installing.xml.vm
-50
View File
@@ -1,50 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author>Tom Copeland</author>
<author email="xlv@users.sourceforge.net">Xavier Le Vourch</author>
<title>Installing PMD</title>
</properties>
<body>
<section name="How to install PMD (and CPD)">
<subsection name="Windows">
<p>
Requirements:
<ul>
<li>Java JRE 1.6 or higher</li>
<li><a href="http://winzip.com">Winzip</a> or the free <a href="http://www.7-zip.org/">7-zip</a></li>
</ul>
</p>
<p>Download the latest binary distribution - i.e., pmd-bin-x.xx.zip</p>
<p>Unzip it into any directory, i.e., c:\pmd\</p>
</subsection>
<subsection name="Unix">
<p>
Requirements:
<ul>
<li>Java JRE 1.6 or higher</li>
<li>The Unix "zip" utility <a href="http://www.info-zip.org/pub/infozip/">InfoZip</a></li>
</ul>
</p>
<p>Download the latest binary distribution - i.e., pmd-bin-x.xx.zip</p>
<p>Unzip it into any directory:
<source>
[tom@hal tmp]$ unzip -q pmd-bin-${project.version}.zip
[tom@hal tmp]$ ls -l
total 4640
drwxrwxr-x 5 tom tom 4096 Apr 17 16:38 pmd-bin-${project.version}
-rw-rw-r-- 1 tom tom 4733312 Jun 9 15:44 pmd-bin-${project.version}.zip
[tom@hal tmp]$
</source>
</p>
<p>Note that the PMD jar file contains the <a href="cpd-usage.html">CPD</a> utility as well.</p>
</subsection>
</section>
</body>
</document>
src/site/xdoc/usage/integrations.xml.vm
-412
View File
File diff suppressed because it is too large. Load diff
src/site/xdoc/usage/jspsupport.xml
-51
View File
@@ -1,51 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="tom@infoether.org">Pieter Vanraemdonck</author>
<title>JSP Support Notes</title>
</properties>
<body>
<section name="Documentation of JSP support in PMD">
<subsection name="What is currently supported and what is not">
<p>In short, JSP files that are XHTML-compliant, are supported.
Except for files that contain inline DTDs; only references to external
DTD files are supported (having inline DTD will result in a parsing
error).</p>
<p>The XHTML support means that:</p>
<ul>
<li>opening tags must be accompanied by corresponding <span style="text-decoration: underline;">closing tags</span>
(or they must be empty tags). This means that currently a "&lt;HR&gt;"
tag without corresponding closing tag will result in a parsing error.</li>
<li><span style="text-decoration: underline;">attribute values</span> must be <span style="text-decoration: underline;">surrounded by</span> single or double <span style="text-decoration: underline;">quotes</span>. This means that the following syntax will result in a parsing error:<br />
&lt;MyTag myAttr1=true myAttr2=1024/&gt;</li>
<li>&lt; and &gt; characters must be <span style="text-decoration: underline;">escaped</span>, or put inside a CDATA section.</li>
<p>PMD creates a "Abstract Syntax Tree" representation of source code; the rules use such a tree as input.
For JSP files, the following constructs are parsed into nodes of the tree:</p>
<ul>
<li>XML-elements, XML-attributes, XML-comments, doctype-declarations, CDATA,</li>
<li>JSP-directives, JSP-declarations, JSP-comments, JSP-scriptlets, JSP-expressions, Expression Language expressions, JSF value bindings</li>
<li>everything else is seen as flat text nodes.</li>
</ul>
<li>Java code (e.g. in JSP-scriptlets) and EL expressions are not parsed or
further broken down. If you want to create rules that check the code
inside EL expressions or JSP scriptlets (a.o.), you currently would
have to do "manual" string manipulation (e.g. using regular
expressions).</li>
</ul>
</subsection>
<subsection name="How to use it">
<p>Using the command-line interface, two new options can be used in the arguments string:</p>
<ul>
<li>"-jsp" : this triggers checking JSP files (they are not checked by default)</li>
<li>"-nojava" : this tells PMD not to check java source files (they are checked by default)</li>
</ul>
<p>Using the Ant task, you decide if PMD must check JSP files by choosing
what files are given to the PMD task. If you use a fileset that
contains only ".java" files, JSP files obviously will not be checked.</p>
<p>If you want to call the PMD API for checking JSP files, you should investigate the javadoc of PMD.</p>
</subsection>
</section>
</body>
</document>
src/site/xdoc/usage/maven-plugin.xml
-59
View File
@@ -1,59 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="mikkey@users.sourceforge.net">Miguel Griffa</author>
<title>Maven plugin</title>
</properties>
<body>
<section name="Maven 1 PMD plugin">
<p>
This page is about the maven 1 PMD plugin. The maven 2 PMD plugin page is available
<a href="mvn-plugin.html">here</a>.
</p>
</section>
<section name="Running the pmd plugin">
<subsection name="report">
<p>
To include the Maven report in the project reports section add the following line under
the reports element in your project.xml:
<source><![CDATA[<report>maven-pmd-plugin</report>]]></source>
This will add an entry to the 'project reports' section with the PMD report.
</p>
</subsection>
<subsection name="manual">
<p>
To run PMD on a Maven project without adding it as a report, simply run
<source><![CDATA[maven pmd xdoc]]></source>
The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
</p>
</subsection>
</section>
<section name="Customization">
<subsection name="Changing rulesets">
<p>
To specify a set of official, built-in rulesets to be used set them in the property
<em>maven.pmd.rulesets</em>. You can include this setting in your project.properties file.
</p>
<p>
A clean strategy for customizing which rules to use for a project is to write a ruleset file.
In this file you can define which rules to use, add custom rules, and
customizing which rules to include/exclude from official rulesets. More information on
writing a ruleset can be found <a href="howtomakearuleset.html">here</a>.
</p>
<p>
Add to the root of your Maven project a pmd.xml file which contains the ruleset mentioned in
the previous paragraph. Add the following property to your project now:
<source>maven.pmd.rulesetfiles = ${basedir}/pmd.xml</source>
</p>
</subsection>
</section>
<section name="Reference">
<p>
See the PMD plugin project page here:
<a href="http://maven.apache.org/maven-1.x/plugins/pmd/">http://maven.apache.org/maven-1.x/plugins/pmd/</a>
</p>
</section>
</body>
</document>
src/site/xdoc/usage/mvn-plugin.xml
-105
View File
@@ -1,105 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="belaran@gmail.com">Romain PELISSE</author>
<title>Maven 2 plugin </title>
</properties>
<body>
<section name="Running the pmd plugin">
<subsection name="report">
<p>
To include the mvn report in the project reports section add the following lines under
the reports element in your pom.xml:
<source>
<![CDATA[
<project>
...
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
</plugin>
</plugins>
</reporting>
...
</project>
]]>
</source>
This will add an entry to the 'project reports' section with the PMD report.
</p>
</subsection>
<subsection name="manual">
<p>
To run PMD on a Maven project without adding it as a report, simply run
<source><![CDATA[mvn pmd:pmd]]></source>
The PMD plugin writes the report in XML which will then be formatted into more readable HTML.
</p>
</subsection>
</section>
<section name="Customization">
<subsection name="Changing rulesets">
<p>
To specify a ruleset, simply edit the previous configuration:
<source>
<![CDATA[
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<configuration>
<rulesets>
<ruleset>/rulesets/braces.xml</ruleset>
<ruleset>/rulesets/naming.xml</ruleset>
<ruleset>d:\rulesets\strings.xml</ruleset>
<ruleset>http://localhost/design.xml</ruleset>
</rulesets>
</configuration>
</plugin>
</plugins>
</reporting>
]]>
</source>
The value of the 'ruleset' value can either be a relative address, an absolute address or even an url.
</p>
<p>
A clean strategy for customizing which rules to use for a project is to write a ruleset file.
In this file you can define which rules to use, add custom rules, and
customizing which rules to include/exclude from official rulesets. More information on
writing a ruleset can be found <a href="howtomakearuleset.html">here</a>.
Note that if you include other rulesets in your own rulesets, you have to be sure that the plugin
will be able to resolve those other ruleset references.
</p>
</subsection>
<subsection name="Other configurations">
<p>
The Maven 2 PMD plugin allows you to configure CPD, targetJDK, and the use of XRef to link the report to html source files,
and the file encoding:
<source>
<![CDATA[
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<configuration>
<linkXref>true</linkXref>
<sourceEncoding>ISO-8859-1</sourceEncoding>
<minimumTokens>30</minimumTokens>
<targetJdk>1.4</targetJdk>
</configuration>
</plugin>
]]>
</source>
</p>
</subsection>
</section>
<section name="Reference">
<p>
For more data, please see the well documented PMD plugin project page here:
<a href="http://maven.apache.org/plugins/maven-pmd-plugin/index.html">http://maven.apache.org/plugins/maven-pmd-plugin/index.html</a>
</p>
</section>
</body>
</document>
src/site/xdoc/usage/running.xml.vm
-88
View File
@@ -1,88 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="tom@infoether.com">Tom Copeland</author>
<title>Running PMD</title>
</properties>
<body>
<section name="Running PMD via command line">
<subsection name="On Linux and other UNIX based operating system...">
<p>PMD comes with several command line utilities. Previously, each of them had its own start up script, but this has been
greatly simplified since PMD 5.0... at least for Unix systems. There is now only one script, called "run.sh", inside
the bin/ directory of PMD distribution.</p>
<p>The first argument is the name of the utility you want to execute ('pmd', 'designer',...) and the other arguments are
specific to the utility used.</p>
<source>
$ ./bin/run.sh pmd -d ../../../src/main/java/ -f text -R rulesets/java/basic.xml -version 1.7 -language java
.../src/main/java/net/sourceforge/pmd/RuleSet.java:123 These nested if statements could be combined
.../src/main/java/net/sourceforge/pmd/RuleSet.java:231 Useless parentheses.
.../src/main/java/net/sourceforge/pmd/RuleSet.java:232 Useless parentheses.
.../src/main/java/net/sourceforge/pmd/RuleSet.java:357 These nested if statements could be combined
.../src/main/java/net/sourceforge/pmd/RuleSetWriter.java:66 Avoid empty catch blocks
.../src/main/java/net/sourceforge/pmd/RuleSetWriter.java:269 Useless parentheses.
</source>
</subsection>
<subsection name="Basic usage for Windows">
<ul>
<li><strong>Windows:</strong> Type &quot;pmd -d [filename|jar or zip file containing source code|directory] -f [report format] -R [ruleset file]&quot;, i.e:</li>
<br/>
<source>
C:\tmp\pmd-bin-${project.version}\pmd\bin&gt;pmd -d c:\data\pmd\pmd\test-data\Unused1.java -f xml -R rulesets/java/unusedcode.xml
&lt;?xml version="1.0"?&gt;&lt;pmd&gt;
&lt;file name="c:\data\pmd\pmd\test-data\Unused1.java"&gt;
&lt;violation line="5" rule="UnusedLocalVariable"&gt;
Avoid unused local variables such as 'fr'
&lt;/violation&gt;
&lt;/file&gt;&lt;/pmd&gt;
C:\tmp\pmd-bin-${project.version}\pmd\bin&gt;
</source>
<p>You can pass a file name, a directory name, or a jar or zip file name containing Java source code to PMD.</p>
<p>Also, the PMD binary distribution includes the ruleset files
inside the jar file - even though the "rulesets/java/unusedcode.xml" parameter
above looks like a filesystem reference, it's really being used by a getResourceAsStream() call
to load it out of the PMD jar file. And the same applies to the example below.</p>
<li>If you want to run PMD without the batch file, you can do a:</li>
<source>
C:\tmp\pmd-bin-${project.version}\pmd&gt;java -Djava.ext.dirs=lib
net.sourceforge.pmd.PMD
-d c:\j2sdk1.4.1_01\src\java\lang
-f xml
-R rulesets/java/imports.xml
</source>
<br/>
<li><strong>Linux:</strong> Type &quot;./run.sh pmd -d [filename|jar or zip file containing source code|directory] -f [report format] -R [ruleset file]&quot;, i.e:</li>
<br/>
<source>
/home/user/tmp/pmd-bin-${project.version}/pmd/bin&gt;./run.sh pmd -d /home/user/data/pmd/pmd/test-data/Unused1.java -f xml -R rulesets/java/unusedcode.xml
&lt;?xml version="1.0"?&gt;&lt;pmd&gt;
&lt;file name="/home/user/data/pmd/pmd/test-data/Unused1.java"&gt;
&lt;violation line="5" rule="UnusedLocalVariable"&gt;
Avoid unused local variables such as 'fr'
&lt;/violation&gt;
&lt;/file&gt;&lt;/pmd&gt;
/home/user/tmp/pmd-bin-${project.version}/pmd/bin&gt;
</source>
</ul>
</subsection>
<subsection name="Other options">
<p>The tool comes with a rather extensive help text, simply running with --help !</p>
</subsection>
<subsection name="Renderers">
<p>PMD comes with four different renderer types:
<ul>
<li><b>csv</b>, provides a Comma Separated Values.</li>
<li><b>text</b>, provides a basic text output.</li>
<li><b>xml</b>, provides report output in XML format.</li>
<li><b>html</b>, provides report as a basic HTML page.</li>
<li>... and many more ! See the tool help text...</li>
</ul>
</p>
</subsection>
</section>
</body>
</document>
src/site/xdoc/usage/suppressing.xml
-168
View File
@@ -1,168 +0,0 @@
<?xml version="1.0"?>
<document>
<properties>
<author email="tom@infoether.com">Tom Copeland</author>
<title>Suppressing warnings</title>
</properties>
<body>
<section name="Suppressing warnings">
<p>PMD provides several methods by which Rule violations can be suppressed.
Follow these steps to help you determine which expression method works best
for you:</p>
<ol>
<li>Is the thing you need to suppress universally appealing to other
users of PMD, or is it a false positive? Can you modify the Rule to
support this specific suppression via a configuration property, or to
fix the false positive? If you can do this, then please do so, and
submit a patch back to the PMD project. Since PMD is built by users
for users, your help would be greatly appreciated by everyone. If you
cannot...</li>
<li>Can you use Annotations or the NOPMD marker to work around your
particular issue on a case by case basis? If not...</li>
<li>Can a regular expression matching the violation message work
around your particular issue? If not...</li>
<li>Can a XPath query on the violation node work around your particular
issue? If not...</li>
<li>Your last and final option is to see the first point about
changing the Rule, but you do not need to submit a patch back to the
PMD project.</li>
</ol>
<p>If you need to modify the Rule, see <a href="howtowritearule.html">How to write a rule</a>.
Otherwise, the other suppression methods are explain in the following sections.</p>
<subsection name="Annotations">
<p>You can use a JDK 1.5 annotation to suppress PMD warnings, like this:</p>
<source>
// This will suppress all the PMD warnings in this class
@SuppressWarnings("PMD")
public class Bar {
void bar() {
int foo;
}
}
</source>
<p>Or you can suppress one rule with an annotation like this:</p>
<source>
// This will suppress UnusedLocalVariable warnings in this class
@SuppressWarnings("PMD.UnusedLocalVariable")
public class Bar {
void bar() {
int foo;
}
}
</source>
<p>PMD also obeys the JDK annotation @SuppressWarnings("unused"), which will apply to all rules in the unused ruleset</p>
<source>
// This will suppress UnusedLocalVariable and UnusedPrivateMethod warnings in this class
@SuppressWarnings("unused")
public class Bar {
void bar() {
int foo;
}
private void foobar(){}
}
</source>
</subsection>
<subsection name="NOPMD">
<p>Alternatively, you can tell PMD to ignore a specific line by using the "NOPMD" marker, like this:</p>
<source>
public class Bar {
// 'bar' is accessed by a native method, so we want to suppress warnings for it
private int bar; //NOPMD
}
</source>
<p>You can use whatever text string you want to suppress warnings, for example, here's
how to use TURN_OFF_WARNINGS as the suppressor:</p>
<source>
$ cat Foo.java
public class Foo {
void bar() {
int x = 2; // TURN_OFF_WARNINGS
}
}
$ ./run.sh pmd -d Foo.java -f text -R java-unusedcode -suppressmarker TURN_OFF_WARNINGS
No problems found!
UnusedLocalVariable rule violation suppressed by //NOPMD in /home/tom/pmd/pmd/bin/Foo.java
</source>
<p>Note that PMD expects the //NOPMD marker to be on the same line as the violation. So, for
example, if you want to suppress an "empty if statement" warning, you'll need to place it on
the line containing the "if" keyword, e.g.:</p>
<source>
$ cat ~/tmp/Foo.java
public class Foo {
void bar() {
int x = 42;
if (x &gt; 5) { // NOPMD
}
}
}
$ java net.sourceforge.pmd.PMD -d ~/tmp/Foo.java -f text -R java-basic
No problems found!
$
</source>
<p>A message placed after the NOPMD marker will get placed in the report, e.g.:</p>
<source>
public class Foo {
void bar() {
try {
bar();
} catch (FileNotFoundException e) {} // NOPMD - this surely will never happen
}
}
</source>
</subsection>
<subsection name="Violation Suppress Regex">
<p>If a particular Rule does not provide a property to customize behavior
sufficiently, you can fall back to using the global 'violationSuppressRegex'
property. This property defines a regular expression to match against the
message of the violation. If the regular expression matches,
then the violation will be suppressed.</p>
<p>When using a Rule reference in a RuleSet XML, you can customize the
Rule by adding the 'violationSuppressRegex' property. For example, to
suppress reporting specifically named parameters which are unused:</p>
<source><![CDATA[
<rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter">
<properties>
<property name="violationSuppressRegex" value=".*'mySpecialParameterName'.*"/>
</properties>
</rule>
]]></source>
<p>Note for message based suppression to work, you must know who to write
a regular expression that matches the message of violations you wish to
suppress. Regular expressions are explained in the JavaDoc for standard
Java class java.util.regex.Pattern.</p>
</subsection>
<subsection name="Violation Suppress XPath">
<p>If a particular Rule does not provide a property to customize behavior
sufficiently, you can fall back to using the global 'violationSuppressXPath'
property. This property defines an XPath query to be executed using the
violation node as the starting point. If the XPath query matches anything,
then the violation will be suppressed.</p>
<p>When using a Rule reference in a RuleSet XML, you can customize the
Rule by adding the 'violationSuppressXPath' property. For example, to
suppress reporting specifically typed parameters which are unused:</p>
<source><![CDATA[
<rule ref="rulesets/java/unusedcode.xml/UnusedFormalParameter">
<properties>
<property name="violationSuppressXPath" value=".[typeof('java.lang.String')]"/>
</properties>
</rule>
]]></source>
<p>Note for XPath based suppression to work, you must know how to write
an XPath query that matches the AST structure of the nodes of the
violations you wish to suppress. XPath queries are explained in
<a href="xpathruletutorial.html">XPath Rule tutorial</a>.</p>
</subsection>
<p>Suggestions? Comments? Post them <a href="http://sourceforge.net/p/pmd/discussion/188192">here</a>. Thanks!</p>
</section>
</body>
</document>