hiifong/pmd
1
0
Fork 0
forked from phoedos/pmd
Code Pull Requests Activity

doc: Improve PMD command line documentation

Browse Source
This commit is contained in:
Andreas Dangel
2015-03-21 17:55:50 +01:00
parent 9312e23a8f
commit fb1e1ba1aa
5 changed files with 288 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
pmd-core/src/main/java/net/sourceforge/pmd/cli/PMDParameters.java
View File

@ -18,61 +18,61 @@ import com.beust.jcommander.validators.PositiveInteger;
public class PMDParameters {
@Parameter(names = { "-rulesets", "-R" }, description = "comma separated list of rulesets name to use", required = true)
@Parameter(names = { "-rulesets", "-R" }, description = "Comma separated list of ruleset names to use.", required = true)
private String rulesets;
@Parameter(names = { "-uri", "-u" }, description = "Database URI for sources", required = false)
@Parameter(names = { "-uri", "-u" }, description = "Database URI for sources.", required = false)
private String uri;
@Parameter(names = { "-dir", "-d" }, description = "root directory for sources", required = false)
@Parameter(names = { "-dir", "-d" }, description = "Root directory for sources.", required = false)
private String sourceDir;
@Parameter(names = { "-format", "-f" }, description = "report format type")
@Parameter(names = { "-format", "-f" }, description = "Report format type.")
private String format = "text"; // Enhance to support other usage
@Parameter(names = { "-debug", "-verbose", "-D", "-V" }, description = "Debug mode")
@Parameter(names = { "-debug", "-verbose", "-D", "-V" }, description = "Debug mode.")
private boolean debug = false;
@Parameter(names = { "-help", "-h", "-H" }, description = "Display help on usage", help = true)
@Parameter(names = { "-help", "-h", "-H" }, description = "Display help on usage.", help = true)
private boolean help = false;
@Parameter(names = { "-encoding", "-e" }, description = "specifies the character set encoding of the source code files PMD is reading (i.e., UTF-8)")
@Parameter(names = { "-encoding", "-e" }, description = "Specifies the character set encoding of the source code files PMD is reading (i.e., UTF-8).")
private String encoding = "UTF-8";
@Parameter(names = { "-threads", "-t" }, description = "set the number of threads used by PMD", validateWith = PositiveInteger.class)
@Parameter(names = { "-threads", "-t" }, description = "Sets the number of threads used by PMD.", validateWith = PositiveInteger.class)
private Integer threads = 1;
@Parameter(names = { "-benchmark", "-b" }, description = "Benchmark mode - output a benchmark report upon completion; default to System.err")
@Parameter(names = { "-benchmark", "-b" }, description = "Benchmark mode - output a benchmark report upon completion; default to System.err.")
private boolean benchmark = false;
@Parameter(names = { "-stress", "-S" }, description = "performs a stress test")
@Parameter(names = { "-stress", "-S" }, description = "Performs a stress test.")
private boolean stress = false;
@Parameter(names = "-shortnames", description = "prints shortened filenames in the report")
@Parameter(names = "-shortnames", description = "Prints shortened filenames in the report.")
private boolean shortnames = false;
@Parameter(names = "-showsuppressed", description = "report should show suppressed rule violations")
@Parameter(names = "-showsuppressed", description = "Report should show suppressed rule violations.")
private boolean showsuppressed = false;
@Parameter(names = "-suppressmarker", description = "specifies the String that marks the a line which PMD should ignore; default is NOPMD")
@Parameter(names = "-suppressmarker", description = "Specifies the string that marks the a line which PMD should ignore; default is NOPMD.")
private String suppressmarker = "NOPMD";
@Parameter(names = { "-minimumpriority", "-min" }, description = "rule priority threshold; rules with lower priority than they will not be used", converter = RulePriorityConverter.class)
@Parameter(names = { "-minimumpriority", "-min" }, description = "Rule priority threshold; rules with lower priority than configured here won't be used. Default is '5' which is the lowest priority.", converter = RulePriorityConverter.class)
private RulePriority minimumPriority = RulePriority.LOW;
@Parameter(names = { "-property", "-P" }, description = "{name}={value}: define a property for the report", converter = PropertyConverter.class)
@Parameter(names = { "-property", "-P" }, description = "{name}={value}: Define a property for the report format.", converter = PropertyConverter.class)
private Properties properties = new Properties();
@Parameter(names = { "-reportfile", "-r" }, description = "send report output to a file; default to System.out")
@Parameter(names = { "-reportfile", "-r" }, description = "Sends report output to a file; default to System.out.")
private String reportfile = null;
@Parameter(names = { "-version", "-v" }, description = "specify version of a language PMD should use")
@Parameter(names = { "-version", "-v" }, description = "Specify version of a language PMD should use.")
private String version = null;
@Parameter(names = { "-language", "-l" }, description = "specify a language PMD should use")
@Parameter(names = { "-language", "-l" }, description = "Specify a language PMD should use.")
private String language = null;
@Parameter(names = "-auxclasspath", description = "specifies the classpath for libraries used by the source code. This is used by the type resolution. Alternatively, a 'file://' URL to a text file containing path elements on consecutive lines can be specified.")
@Parameter(names = "-auxclasspath", description = "Specifies the classpath for libraries used by the source code. This is used by the type resolution. Alternatively, a 'file://' URL to a text file containing path elements on consecutive lines can be specified.")
private String auxclasspath;
// this has to be a public static class, so that JCommander can use it!
@ -99,8 +99,8 @@ public class PMDParameters {
public int validate(String value) throws ParameterException {
int minPriorityValue = Integer.parseInt(value);
if (minPriorityValue < 0 || minPriorityValue > 5) {
throw new ParameterException("Priority values can only be integer value, between 0 and 5," + value
if (minPriorityValue < 1 || minPriorityValue > 5) {
throw new ParameterException("Priority values can only be integer value, between 1 and 5," + value
+ " is not valid");
}
return minPriorityValue;

62
src/site/markdown/usage/ant-task.md
View File

@ -14,62 +14,62 @@ Runs a set of static code analysis rules on some Java source code files and gene
### Parameters
<table border="1" cellpadding="2" cellspacing="0">
<table>
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
<th>Attribute</td>
<th>Description</td>
<th>Required</td>
</tr>
<tr>
<td valign="top">rulesetfiles</td>
<td valign="top">
<td>rulesetfiles</td>
<td>
A comma delimited list of ruleset files ('rulesets/java/basic.xml,rulesets/java/design.xml').
If you write your own ruleset files, you can put them on the classpath and plug them in here.
</td>
<td valign="top" align="center">Yes, unless the ruleset nested element is used</td>
<td>Yes, unless the ruleset nested element is used</td>
</tr>
<tr>
<td valign="top">failonerror</td>
<td valign="top">Whether or not to fail the build if any errors occur while processing the files</td>
<td valign="top" align="center">No</td>
<td>failonerror</td>
<td>Whether or not to fail the build if any errors occur while processing the files</td>
<td>No</td>
</tr>
<tr>
<td valign="top">failOnRuleViolation</td>
<td valign="top">Whether or not to fail the build if PMD finds any problems</td>
<td valign="top" align="center">No</td>
<td>failOnRuleViolation</td>
<td>Whether or not to fail the build if PMD finds any problems</td>
<td>No</td>
</tr>
<tr>
<td valign="top">minimumPriority</td>
<td valign="top">The rule priority threshold; rules with lower priority than they will not be used</td>
<td valign="top" align="center">No</td>
<td>minimumPriority</td>
<td>The rule priority threshold; rules with lower priority than they will not be used</td>
<td>No</td>
</tr>
<tr>
<td valign="top">shortFilenames</td>
<td valign="top">Places truncated filenames in the report. This can reduce your report file size by 15%-20%.</td>
<td valign="top" align="center">No</td>
<td>shortFilenames</td>
<td>Places truncated filenames in the report. This can reduce your report file size by 15%-20%.</td>
<td>No</td>
</tr>
<tr>
<td valign="top">failuresPropertyName</td>
<td valign="top">A property name to plug the number of rule violations into when the task finishes</td>
<td valign="top" align="center">No</td>
<td>failuresPropertyName</td>
<td>A property name to plug the number of rule violations into when the task finishes</td>
<td>No</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</td>
<td valign="top" align="center">No</td>
<td>encoding</td>
<td>The character set encoding (e.g. UTF-8) to use when reading the source code files</td>
<td>No</td>
</tr>
<tr>
<td valign="top">suppressMarker</td>
<td valign="top">The series of characters to use to tell PMD to skip lines - the default is NOPMD.</td>
<td valign="top" align="center">No</td>
<td>suppressMarker</td>
<td>The series of characters to use to tell PMD to skip lines - the default is NOPMD.</td>
<td>No</td>
</tr>
<tr>
<td valign="top">maxRuleViolations</td>
<td valign="top">
<td>maxRuleViolations</td>
<td>
Whether or not to fail the build if PMD finds more than the value of this attribute.
Note that setting this attribute does not require to set the failOnRuleViolation to true.
</td>
<td valign="top" align="center">No</td>
<td>No</td>
</tr>
</table>

21
src/site/markdown/usage/installing.md.vm
View File

@ -3,30 +3,32 @@
<author email="xlv@users.sourceforge.net">Xavier Le Vourch</author>
-->
How to install PMD (and CPD)
============================
How to install PMD and CPD
==========================
Windows
-------
Requirements:
* Java JRE 1.6 or higher
* [Java JRE](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 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
Download the latest binary distribution from [the download page](https://sourceforge.net/projects/pmd/files/pmd/)
- i.e., [pmd-bin-${project.version}.zip](https://sourceforge.net/projects/pmd/files/pmd/${project.version}/pmd-bin-${project.version}.zip).
Unzip it into any directory, i.e., c:\pmd\
Unix
----
Linux / Unix
------------
Requirements:
* Java JRE 1.6 or higher
* [Java JRE](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 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
Download the latest binary distribution from [the download page](https://sourceforge.net/projects/pmd/files/pmd/)
- i.e., [pmd-bin-${project.version}.zip](https://sourceforge.net/projects/pmd/files/pmd/${project.version}/pmd-bin-${project.version}.zip).
Unzip it into any directory:
@ -37,4 +39,5 @@ Unzip it into any directory:
-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.
Note that the PMD binary distribution file contains both [PMD](running.html) and [CPD](cpd-usage.html).

241
src/site/markdown/usage/running.md.vm
View File

@ -9,10 +9,10 @@ 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.
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
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
@ -23,7 +23,7 @@ specific to the utility used.
.../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:
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>
@ -35,10 +35,13 @@ specific to the utility used.
/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:
You can find PMD's starter batch file `pmd.bat` in the `bin` subdirectory.
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>
@ -55,29 +58,221 @@ You can pass a file name, a directory name, or a jar or zip file name containing
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.
to load it out of the PMD jar file.
* If you want to run PMD without the batch file, you can do a:
Options
-------
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
The tool comes with a rather extensive help text, simply running with `-help`!
<table>
<tr>
<th>Option</th>
<th>Description</th>
<th>Required</th>
<th>Applies for language</th>
</tr>
<tr>
<td>-rulesets / -R</td>
<td>Comma separated list of ruleset names to use</td>
<td>yes</td>
<td></td>
</tr>
<tr>
<td>-dir / -d</td>
<td>Root directory for sources</td>
<td>yes</td>
<td></td>
</tr>
<tr>
<td>-format / -f</td>
<td>Report format type. Default format is `text`.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-auxclasspath</td>
<td>
Specifies the classpath for libraries used by the source code. This is used by the type resolution.
Alternatively a `file://` URL to a text file containing path elements on consecutive lines can be
specified.
</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-uri / -u</td>
<td>Database URI for sources. If this is given, then you don't need to provide `-dir`.</td>
<td>no</td>
<td>plsql</td>
</tr>
<tr>
<td>-debug / -verbose / -D / -V</td>
<td>Debug mode. Prints more log output.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-help / -h / -H</td>
<td>Display help on usage.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-encoding / -e</td>
<td>Specifies the character set encoding of the source code files PMD is reading (i.e. UTF-8). Default is `UTF-8`.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-threads / -t</td>
<td>Sets the number of threads used by PMD. Default is `1`. Set threads to '0' to disable multi-threading processing.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-benchmark / -b</td>
<td>Benchmark mode - output a benchmark report upon completion; defaults to System.err</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-stress / -S</td>
<td>Performs a stress test.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-shortnames</td>
<td>Prints shortened filenames in the report.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-showsuppressed</td>
<td>Report should show suppressed rule violations.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-suppressmarker</td>
<td>Specifies the string that marks the line which PMD should ignore; default is `NOPMD`.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-minimumpriority / -min</td>
<td>Rule priority threshold; rules with lower priority than configured here won't be used. Default is `5` - which is the lowest priority.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-property / -P</td>
<td>`{name}={value}`: Define a property for a report format.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-reportfile / -r</td>
<td>Send report output to a file; default to System.out</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-version / -v</td>
<td>Specify version of a language PMD should use.</td>
<td>no</td>
<td></td>
</tr>
<tr>
<td>-language / -l</td>
<td>Specify a language PMD should use.</td>
<td>no</td>
<td></td>
</tr>
</table>
Other options
-------------
Supported Languages
-------------------
The tool comes with a rather extensive help text, simply running with `--help`!
* [java](../pmd-java/rules/index.html)
* [ecmascript](../pmd-javascript/rules/index.html) (JavaScript)
* [jsp](../pmd-jsp/rules/index.html)
* [plsql](../pmd-plsql/rules/index.html)
* [vm](../pmd-vm/rules/index.html) (Apache Velocity)
* [xml and xsl](../pmd-xml/rules/index.html)
Renderers
---------
PMD comes with four different renderer types:
Available Report Formats / Renderers
------------------------------------
* **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...
PMD comes with many different renderer types:
* **csv**: Comma-separated values tabular format.
Properties:
* problem: Include problem column. Default: true.
* package: Include package column. Default: true.
* file: Include file column. Default: true.
* priority: Include priority column. Default: true.
* line: Include line column. Default: true.
* desc: Include description column. Default: true.
* ruleSet: Include Rule set column. Default: true.
* rule: Include Rule column. Default: true.
* **emacs**: GNU Emacs integration.
* **html**: HTML format.
Properties:
* linePrefix: Prefix for line number anchor in the source file.
* linkPrefix: Path to HTML source.
* **ideaj**: IntelliJ IDEA integration.
Properties:
* classAndMethodName: Class and method name, pass '.method' when processing a directory.
* sourcePath:
* fileName:
* **summaryhtml**: Summary HTML format.
Properties:
* linePrefix: Prefix for line number anchor in the source file.
* linkPrefix: Path to HTML source.
* **text**: Text format.
* **textcolor**: Text format, with color support (requires ANSI console support, e.g. xterm, rxvt, etc.).
Properties:
* color: Enables colors with anything other than 'false' or '0'. Default: yes.
* **textpad**: TextPad integration.
* **vbhtml**: Vladimir Bossicard HTML format.
* **xml**: XML format.
Properties:
* encoding: XML encoding format, defaults to UTF-8.
* **xslt**: XML with a XSL transformation applied.
Properties:
* encoding: XML encoding format, defaults to UTF-8.
* xsltFilename: The XSLT file name.
* **yahtml**: Yet Another HTML format.
Properties:
* outputDir: Output directory.

12
src/site/site.xml
View File

@ -69,13 +69,13 @@
</menu>
<menu name="Usage">
<item href="/usage/installing.html" name="Installation"/>
<item href="/usage/running.html" name="Command line usage"/>
<item href="/usage/ant-task.html" name="Ant task usage"/>
<item href="/usage/maven-plugin.html" name="Maven plugin usage"/>
<item href="/usage/mvn-plugin.html" name="Mvn plugin usage"/>
<item href="/usage/running.html" name="PMD: Command line usage"/>
<item href="/usage/ant-task.html" name="PMD: Ant task usage"/>
<item href="/usage/suppressing.html" name="PMD: Suppressing warnings"/>
<item href="/usage/cpd-usage.html" name="CPD: Finding duplicated code"/>
<item href="/usage/maven-plugin.html" name="Maven 1 plugin usage"/>
<item href="/usage/mvn-plugin.html" name="Mvn 2/3 plugin usage"/>
<item href="/usage/integrations.html" name="IDE plugin usage"/>
<item href="/usage/suppressing.html" name="Suppressing warnings"/>
<item href="/usage/cpd-usage.html" name="Finding duplicated code"/>
<item href="/usage/jspsupport.html" name="JSP support"/>
<item href="/usage/ci-plugins.html" name="CI Plugins"/>
<item href="/usage/faq.html" name="FAQ"/>