From b87d5675257a95e845bfcdaf1f5b8aa0235e316f Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Sat, 22 Jul 2017 11:06:01 +0200 Subject: [PATCH] [doc] Add remaining pages from old "usage" section --- docs/_data/sidebars/pmd_sidebar.yml | 12 + docs/pages/pmd/languages/pmd_languages_jsp.md | 52 ++ .../pages/pmd/userdocs/pmd_getting_started.md | 339 +++++++++- docs/pages/pmd/userdocs/pmd_tools.md | 604 ++++++++++++++++++ docs/pages/pmd/userdocs/pmd_userdocs_cpd.md | 493 ++++++++++++++ .../pmd/userdocs/pmd_userdocs_suppressing.md | 166 +++++ 6 files changed, 1664 insertions(+), 2 deletions(-) create mode 100644 docs/pages/pmd/languages/pmd_languages_jsp.md create mode 100644 docs/pages/pmd/userdocs/pmd_userdocs_cpd.md create mode 100644 docs/pages/pmd/userdocs/pmd_userdocs_suppressing.md diff --git a/docs/_data/sidebars/pmd_sidebar.yml b/docs/_data/sidebars/pmd_sidebar.yml index c597daf2c8..ec411d5ca9 100644 --- a/docs/_data/sidebars/pmd_sidebar.yml +++ b/docs/_data/sidebars/pmd_sidebar.yml @@ -36,6 +36,12 @@ entries: - title: Best Pratices url: /pmd_best_practices.html output: web, pdf + - title: Copy-Paste Detection + url: /pmd_userdocs_cpd.html + output: web, pdf + - title: Suppressing + url: /pmd_userdocs_suppressing.html + output: web, pdf - title: Tools / Integrations url: /pmd_tools.html output: web, pdf @@ -69,6 +75,12 @@ entries: - title: Java Rules url: /pmd_rules_java.html output: web, pdf + - title: Language Specific Documentation + output: web, pdf + folderitems: + - title: JSP Support + url: /pmd_languages_jsp.html + output: web, pdf - title: Developer Documentation output: web, pdf folderitems: diff --git a/docs/pages/pmd/languages/pmd_languages_jsp.md b/docs/pages/pmd/languages/pmd_languages_jsp.md new file mode 100644 index 0000000000..6a1a589fed --- /dev/null +++ b/docs/pages/pmd/languages/pmd_languages_jsp.md @@ -0,0 +1,52 @@ +--- +title: JSP Support +sidebar: pmd_sidebar +permalink: pmd_languages_jsp.html +folder: pmd/languages +--- + +## 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 "<HR>" + 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: + + <MyTag myAttr1=true myAttr2=1024/> + +* < and > 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. diff --git a/docs/pages/pmd/userdocs/pmd_getting_started.md b/docs/pages/pmd/userdocs/pmd_getting_started.md index 52be716fc2..a1d8940c6f 100644 --- a/docs/pages/pmd/userdocs/pmd_getting_started.md +++ b/docs/pages/pmd/userdocs/pmd_getting_started.md @@ -5,6 +5,341 @@ sidebar: pmd_sidebar folder: pmd/userdocs --- -## Installation +## How to install PMD and CPD -## Running +### Windows + +Requirements: + +* [Java JRE](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 1.7 or higher +* [Winzip](http://winzip.com) or the free [7-zip](http://www.7-zip.org/) + +Download the latest binary distribution from [the github releases page](https://github.com/pmd/pmd/releases). + +Unzip it into any directory, i.e., c:\pmd\ + +### Linux / Unix + +Requirements: + +* [Java JRE](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 1.7 or higher +* The Unix "zip" utility [InfoZip](http://www.info-zip.org/pub/infozip/) + +Download the latest binary distribution from [the github releases page](https://github.com/pmd/pmd/releases). + +Unzip it into any directory: + + [tom@hal tmp]$ unzip -q pmd-bin-6.0.0.zip + [tom@hal tmp]$ ls -l + total 4640 + drwxrwxr-x 5 tom tom 4096 Apr 17 16:38 pmd-bin-6.0.0 + -rw-rw-r-- 1 tom tom 4733312 Jun 9 15:44 pmd-bin-6.0.0.zip + [tom@hal tmp]$ + + +Note that the PMD binary distribution file contains both [PMD](running.html) and [CPD](cpd-usage.html). + + +## 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 + + + + Avoid unused local variables such as 'fr' + + + + /home/user/tmp/pmd-bin-${project.version}/pmd/bin> + + +### Basic usage for Windows + +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 + + + + Avoid unused local variables such as 'fr' + + + + 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. + +### Options + +The tool comes with a rather extensive help text, simply running with `-help`! + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionRequiredApplies for language
-rulesets / -RComma separated list of ruleset names to useyes
-dir / -dRoot directory for sourcesyes
-format / -fReport format type. Default format is `text`.no
-auxclasspath + 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. + no
-uri / -uDatabase URI for sources. If this is given, then you don't need to provide `-dir`.noplsql
-filelistPath to file containing a comma delimited list of files to analyze. If this is given, then you don't need to provide `-dir`.no
-debug / -verbose / -D / -VDebug mode. Prints more log output.no
-help / -h / -HDisplay help on usage.no
-encoding / -eSpecifies the character set encoding of the source code files PMD is reading (i.e. UTF-8). Default is `UTF-8`.no
-threads / -tSets the number of threads used by PMD. Default is `1`. Set threads to '0' to disable multi-threading processing.no
-benchmark / -bBenchmark mode - output a benchmark report upon completion; defaults to System.errno
-stress / -SPerforms a stress test.no
-shortnamesPrints shortened filenames in the report.no
-showsuppressedReport should show suppressed rule violations.no
-suppressmarkerSpecifies the string that marks the line which PMD should ignore; default is `NOPMD`.no
-minimumpriority / -minRule priority threshold; rules with lower priority than configured here won't be used. Default is `5` - which is the lowest priority.no
-property / -P`{name}={value}`: Define a property for a report format.no
-reportfile / -rSend report output to a file; default to System.outno
-version / -vSpecify version of a language PMD should use.no
-language / -lSpecify a language PMD should use.no
-failOnViolation {true|false}By default PMD exits with status 4 if violations are found. + Disable this option with '-failOnViolation false' to exit with 0 instead and just write the report. + no
-cacheSpecify a location for the analysis cache file to use. + This can greatly improve analysis performance and is highly recommended.no
+ + +### Exit Status + +Please note that if PMD detects any violations, it will exit with status 4 (since 5.3). +This behavior has been introduced to ease PMD integration into scripts or hooks, such as SVN hooks. + + + + + +
0Everything is fine, now violations found
1Couldn't understand command line parameters or PMD exited with an exception
4At least one violation has been detected unless '-failOnViolation false' is set.
+ + +### Supported Languages + +* [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) + + +### Available Report Formats / Renderers + +PMD comes with many different renderer types: + +* **codeclimate**: Renderer for Code Climate JSON format. + +* **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. diff --git a/docs/pages/pmd/userdocs/pmd_tools.md b/docs/pages/pmd/userdocs/pmd_tools.md index 04d7609085..e55d225138 100644 --- a/docs/pages/pmd/userdocs/pmd_tools.md +++ b/docs/pages/pmd/userdocs/pmd_tools.md @@ -10,3 +10,607 @@ folder: pmd/userdocs * [Ant Task Usage](/pmd_userdocs_ant.html) * [Continuous Integrations plugins](/pmd_userdocs_ci.html) * GUIs + + + +## IDE Integrations + +### Summary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDEHomepageSource CodeMaintainers
BlueJpmd-bluejTom Copeland
Codacygithub: codacy/codacy-pmdjavaCodacy
CodeGuideN/AAustin Moore
Eclipsegithub: pmd/pmd-eclipsePhilippe Herlin
eclipse-pmdhttp://acanda.github.io/eclipse-pmd/github: acanda/eclipse-pmdPhilip Graf
Emacsgithub: pmd/pmd-emacsNascif Abousalh Neto
Gelgithub: pmd/pmd-misc/pmd-gelAndrei Lumianski
GradleGradle: The PMD Plugingithub: gradle/gradleGradle.org
IntelliJ IDEAgithub: amitdev/PMD-IntellijAmit Dev
IntelliJ IDEA - QAPlughttp://qaplug.com/N/AJakub Sławiński
JBuildergithub: pmd/pmd-misc/pmd-jbuilderTom Copeland
JCreatorN/ABrant Gurganus
JDevelopergithub: pmd/pmd-jdeveloperTorsten Kleiber
JEditjEdit - PMD Pluginsourceforge: jedit/PMDPluginJiger Patel, Dale Anson
MavenN/AN/A
Maven 2 and 3N/Aapache.org / maven
NetBeansSQEgithub: sqe-team/sqeN/A
TextPadN/AJeff Epstein
WebLogic Workshop 8.1.xN/AKevin Conaway
Codacygithub: codacy/codacy-pmdjavaCodacy
+ + +### General comments + +A general note - most plugins include the PMD jar files, which has the rulesets +inside it. So even though the rulesets parameter that some plugins +use (i.e., "rulesets/java/unusedcode.xml") looks like a filesystem reference, it's really +being used by a getResourceAsStream() call to load it out of the PMD jar files. + + +### BlueJ + +[BlueJ](http://bluej.org/) is a teaching IDE. To install the PMD extension for BlueJ, download +the [PMDExtension jar file](http://sourceforge.net/projects/pmd/files/pmd-bluej/pmd-bluej-1.0/) +and place it in your `bluej/lib/extensions/` directory. + + +### Codacy + +Although it is not an IDE, with [Codacy](https://www.codacy.com/) you have PMDJava analysis out-of-the-box, +and it is free for open source projects. + + +### Code Guide + +Here's how to set up PMD with Omnicore's CodeGuide: + +* Download the PMD zip file from [here](http://sourceforge.net/projects/pmd/files/pmd/) +* Unpack the zip file to your local disk. I put it in /Applications/ +* Add the following tool to CodeGuide (Tools->Configure Tools->New): + * Name: PMD + * Kind: Tool for directories + * Executable: /Applications/pmd-bin-${project.version}/bin/run.sh + * Arguments: pmd -d $DIRECTORY_PATH$ -f emacs $USER_ARGUMENTS$ + +Now you can right click on a source directory, select the PMD tool and a dialog box will appear. +Type in the name of a rule set (e.g. unusedcode). PMD is then executed on the directory you +selected with the rule set you specified. Since CodeGuide understands the emacs syntax you can +click on the file name and CodeGuide will jump to that file and line number. + +Note: I set this up on Mac OS X. It should work on other unix variations just the same. +Of course you need to change the "Executable" setting above to where your PMD is installed. +On Windows you need to use the pmd.bat file instead of pmd.sh. + +If you haven't heard of CodeGuide before, [check it out](http://www.omnicore.com/). +It's a great IDE. + + +### Eclipse + +To install the PMD plugin for Eclipse: + +* Start Eclipse and open a project +* Select "Help"->"Software Updates"->"Find and Install" +* Click "Next", then click "New remote site" +* Enter "PMD" into the Name field and into the URL field +* Click through the rest of the dialog boxes to install the plugin + +Alternatively, you can download the latest zip file and follow the above procedures +except for using "New local site" and browsing to the downloaded zip file. + +To configure PMD, select "Windows"->"Preferences", then select PMD. + +To run PMD, right-click on a project node and select "PMD"->"Check code with PMD". + +To run the duplicate code detector, right-click on a project node and +select "PMD"->"Find suspect cut and paste". The report will be placed in a "reports" directory +in a file called "cpd-report.txt". + +To find additional help for other features, please read included help by selecting +Help->Help Contents and browse the "How to..." section in the "PMD Plugin Documentation" book. + +After installing an update, if you get an Exception such as +"java.lang.RuntimeException: Couldn't find that class xxxxx", +try deleting the ruleset.xml file in the .metadata/plugins/net.sourceforge.pmd.eclipse directory in your workspace. + +To get Eclipse to not flag the @SuppressWarnings("PMD") annotation, look +under the menu headings Java -> Compiler -> Errors/Warnings -> Annotations -> Unhandled Warning Token. + + +### Emacs + +Integration with GNU Emacs is performed through an ELisp package, pmd.el. +It supports two commands, "pmd-current-buffer" and "pmd-current-dir". +The output is captured in a compilation buffer which allows the user to "jump" +directly to the source code position associated with the PMD warnings. + + +### Gel + +Here's how to set up the Gel plugin: + +* Download the pmd-gel-[version].zip file +* Close Gel +* Remove any old plugin versions from your gel\plugins directory +* Unzip the new zip file into your gel\plugins directory +* Start Gel +* Go to Tools->Options->Plugin +* Select the PMD plugin and click "Remove" +* Click "Add" and select "net.sourceforge.pmd.gel.PMDPlugin" +* Restart Gel + +That's pretty much it. Now you can open a Java project and click on Plugins->PMD and +a configuration panel will pop up. You can pick which ruleset you want to run and +you can also pick whether you want to run PMD on the current file or on every +source file in your project. + + +### IDEA + +You can use an integrated plugin or just use it as an IDEA "External Tool". + +Amit Dev wrote an integrated plugin for IDEA; you can download that +[from the IntelliJ plugins site](http://plugins.jetbrains.com/idea/plugin/1137-pmdplugin). + +Here's how to set it up as an "External Tool": + +* Open IDEA and go to File->Settings +* Click on the "External Tools" icon +* Click on the Add button +* Fill in the blocks + * Name: PMD + * Description: PMD, good for what ails you. + * Menu: Select the "Main menu", "Project views", "Editor menu", and "Search results" checkboxes. + * Program: $JDKPath$\bin\java.exe + * For the next parameter you'll need to plug in the location of your PMD installation + and the rulesets you want to use + * Parameters: + `-cp %CLASSPATH%;c:\pmd\lib\pmd-${project.version}.jar;c:\pmd\lib\asm-3.2.jar;c:\pmd\lib\jaxen-1.1.1.jar net.sourceforge.pmd.PMD "$FilePath$" ideaj unusedcode,imports "$Sourcepath$" $FileClass$.method $FileName$` + +That's pretty much it. Now you can right click on a source directory and select PMD, +it'll run recursively on the source files, and the results should +be displayed in a window and hyperlinked into the correct file and line of code. I usually +right-click on the message window title bar and unselect "autohide" so the window doesn't go +away every time I fix something in the code window. + + +### IDEA - QAPlug + +QAPlug is an Intellij IDEA plugin to manage code quality. It integrates no less than Checkstyle, FindBugs, and PMD. + +The plugin is available at . + +Also available at the JetBrains site, [QAPlug-PMD](http://plugins.jetbrains.com/idea/plugin/4596-qaplug--pmd) +and [QAPlug](http://plugins.jetbrains.com/idea/plugin/4594-qaplug). + + +### JBuilder + +To enable this OpenTool in JBuilder: + +* Download the [latest binary release](https://sourceforge.net/projects/pmd/files/pmd-jbuilder/) +* Unzip it into your `jbuilder/lib/ext/` directory +* Restart JBuilder + +What you can do: + +* Check a single file by bringing up the context menu from the file tab and selecting PMDCheck +* Configure the rulesets that the PMD OpenTool will use by selecting Tools->PMD->Configure PMD +* Check all the files in a project by bringing up the context menu for + the project node and selecting PMD Check Project +* Locate duplicate code by right clicking on a package and selection "Check with CPD" + +When running PMD, the results will be displayed in the MessageView under a tab called PMD Results. If you click on a +violation message within this view, you will be taken to the line in the source code where the violation was detected. + +Things still to do: + +* Enable selection of individual rules within a rule set (maybe) +* Optional insertion of @todo comments at the point of a violation +* Possibly provide configurable ability to limit the number of violations per rule per file + + +### JCreator + +1. Open Configure > Options +2. Go to the Tools panel +3. Click New > Program +4. Browse for PMD's pmd.bat +5. Put quotations around the path if it has spaces. +6. Set the initial directory to PMD's \bin directory +7. Check capture output +8. Put '"$[PrjDir]" emacs' followed by desired rulesets in the arguments + +To run PMD on a project, just pick pmd from the Tools menu. + + +### JDeveloper + +To install the PMD plugin for JDeveloper: + +* JDeveloper 10.1.2: Download the binary release and unzip it into your jdev/lib/ext directory +* JDeveloper 10.1.3 upwards: Click "Help", click "Check for Updates" + * JDeveloper 10.1.3: + * Press "Add" to add a new update center + * Name: PMD Update Center + * Location: + * Select Update Center: PMD Update Center + * JDeveloper 11 upwards: Select Update Center: Open Source and Partner Extensions + * Press Next and select the actual PMD Plugin and install it +* Restart JDeveloper + +To run the PMD plugin for JDeveloper: + +* Open the Tools-&Preferences menu +* Click on the PMD option +* Select a couple of rules to try +* To run PMD, right click on either a file, folder, package, project or workspace and select PMD via + Toolbar Icon, Context Menu or File Menu +* Any rule violations should show up in a LogWindow tab at the bottom of the screen + + +### JEdit + +The way I use the JEdit plugin is: + +* Dock the ErrorList by going to Utilities->Global Options->Docking and + putting ErrorList at the bottom of the screen +* Open the File Browser if it isn't already open +* Double-click on a source directory +* Select Plugins->PMD->Check directory recursively + +Note that you can select individual rules by going to Utilities->Global Options->Plugin Options->PMD. +Also, you can change the plugin to prompt you for a directory to check by going to that same menu and +selecting the "Ask for Directory" checkbox. + + +### Maven + +This section is about the maven 1 PMD plugin. The maven 2 PMD plugin page is available +[below](#Maven_2_and_3). + +#### 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: + + maven-pmd-plugin + +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 +maven.pmd.rulesets. 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: + + + +### Maven 2 and 3 + +#### 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: + + + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + + + + ... + + +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: + + + + + + org.apache.maven.plugins + maven-pmd-plugin + + + /rulesets/java/braces.xml + /rulesets/java/naming.xml + d:\rulesets\strings.xml + http://localhost/design.xml + + + + + + +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: + + + org.apache.maven.plugins + maven-pmd-plugin + + true + ISO-8859-1 + 30 + 1.4 + + + +#### Reference + +For more data, please see the well documented PMD plugin project page here: + +Also, the bug tracker for this plugin is [here](http://jira.codehaus.org/browse/MPMD). + + + + +### NetBeans + +The [SQE](http://kenai.com/projects/sqe/) project includes PMD integration for NetBeans. + + +### TextPad + +**Assumptions** + +* The Java Development Kit, version 1.4.2 (versions 1.4 and higher are acceptable) is properly installed + into your machine, and exists in `D:\java\jdk\_142\`. This means that `D:\java\jdk\_142\bin\java.exe` exists. +* PMD version 5.0 exists in `D:\java\pmd-bin-${project.version}\`. + This means that `D:\java\pmd-bin-${project.version}\lib\pmd-${project.version}.jar` (among other jar files + in the same directory) exist. + +**To integrate into TextPad** + +1. In the **Configure** menu, choose **Preferences...**. This opens the Preferences dialog +2. In the left pane of the Preferences dialog, choose the **Tools** branch by clicking on the *word* "Tools". +3. On the far right of the dialog, click on the **Add** button, and then select **Program...** from the drop-down. + This opens the standard Windows Open File dialog. +4. Type `D:\java\jdk_142\bin\java.exe` and click the **Open** button. In the center pane of the Preferences dialog, + an item "Java" has now been added, and is currently selected. +5. Click the word Java, which makes the word editable. Select the entire word, and type "PMD directory". Press Return. +6. Repeat steps three through five, but type "PMD file", instead of "PMD directory". +7. Click **Apply**. +8. Expand the **Tools** branch (if not already) by clicking on the '`+`' directly to its left. +9. In the expanded list, select **PMD directory**. This changes the right side of this dialog to the "tool" form. +10. In the "tool" form, enter these parameters: + * **Parameters:** `-classpath D:\java\pmd-bin-${project.version}\lib\pmd-${project.version}.jar;D:\java\pmd-bin-${project.version}\lib\asm-3.2.jar;D:\java\pmd-bin-${project.version}\lib\jaxen-1.1.1.jar net.sourceforge.pmd.PMD -d $FileDir -f net.sourceforge.pmd.renderers.TextPadRenderer -R E:\directory\my_pmd_ruleset.xml -debug` + * **Initial Folder:** `$FileDir` + * **Save all documents first:** `Checked` + * **Capture output:** `Checked` + * **_All other checkboxes_:** Unchecked + * **Regular expression to match output:** `^\([^(]+\)(\([0-9]+\),` + * **Registers/File:** `1` + * **Registers/Line:** `2` +11. In the expanded list, select **PMD file**. +12. In the "tool" form, enter the same parameters as above, except replace '`$FileDir`' with '`$File`', + in the Parameters textbox. +13. To save your work (truly, given a quirk of TextPad), click on **OK**, which closes the Preferences dialog. + Restart TextPad and re-open the Preferences dialog. +14. Go back to both the "PMD directory" and "PMD file" Tools branches, and replace '`E:\directory\my_pmd_ruleset.xml`' + with the ruleset of your choice. For example, `basic`. +15. Go to the **Keyboard** branch in the left pane (above **Tools**), which changes the right side to + the "keyboard configuration" form. +16. In the **Categories** list box, select **Tools**. +17. In the **Command** list box, select **PMD directory**. +18. Put your cursor into the **Press new shortcut key**, and type your desired key command. + For example `Ctrl+Page Up` +19. Click **Assign**. +20. In the **Command** list box, select **PMD file**. +21. Put your cursor into the **Press new shortcut key**, and type your desired key command. + For example `Ctrl+Page Down` +22. Click **Assign**. +23. Save your work again: Click on **OK**, which closes the Preferences dialog, and then restart TextPad. + + +**To run PMD against a single Java file** + +1. In TextPad, open any Java file. +2. Click `Ctrl+Page Down`. This opens an empty, read-only text document (titled "Command Results"). + When PMD completes its analysis, this document will be populated with a listing of violated rules + (or "Command completed successfully" indicating no violations). +3. Double click any line to go to it. + + +**To run PMD against a directory of Java files** + +1. In TextPad, open *any* file in the *root* directory you wish to analyze. Unfortunately, you'll need to + create a dummy file, if no file exists there. +2. Click `Ctrl+Page Up`. This opens an empty, read-only text document (titled "Command Results"). + When PMD completes its analysis, this document will be populated with a listing of violated rules + (or "Command completed successfully" indicating no violations). +3. Double click any line to go to it. + +Because directory analysis may take a while, you may choose to cancel this operation. Do so by closing +the (blank Command Results) document, and then confirming that, "yes, I do really want to exit the tool". + + +### WebLogic Workshop 8.1.x + +Please see [the WebLogic Workshop plugin project home page](http://pmdwlw.sf.net/) for more information. diff --git a/docs/pages/pmd/userdocs/pmd_userdocs_cpd.md b/docs/pages/pmd/userdocs/pmd_userdocs_cpd.md new file mode 100644 index 0000000000..bfc38dcc9b --- /dev/null +++ b/docs/pages/pmd/userdocs/pmd_userdocs_cpd.md @@ -0,0 +1,493 @@ +--- +title: Finding duplicated code +sidebar: pmd_sidebar +permalink: pmd_userdocs_cpd.html +folder: pmd/userdocs +--- + +Or how to find copied and pasted code + +* [Overview](#Overview) +* [Command line usage](#Command_line_usage) +* [Ant task](#Ant_task) +* [GUI](#GUI) +* [Suppression](#Suppression) + + +## 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). + +Note that CPD works with Java, JSP, C, C++, C#, Fortran and PHP code and some more languages. For the +full list, see below [Supported Languages](#Supported_Languages). + +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). + + +## Command line usage + +### Windows + +CPD comes with its own starter batch file: `cpd.bat`. It's located in the `bin` subdirectory in the PMD +binary distribution zip-file. Let's assume, you are in this directory, then you can start CPD this way: + + cpd.bat --minimum-tokens 100 --files c:\temp\src\java + +The options "minimum-tokens" and "files" are the two required options; there are more options, see below. + + +### Linux + +For Linux, there is since PMD 5.0 a combined start script for all command line tools. This includes CPD. +The start script is called `run.sh` and is located in the `bin` subdirectory in the PMD binary distribution +zip-file. Let's assume, you are in this directory, then you can start CPD this way: + + ./run.sh cpd --minimum-tokens 100 --files /tmp/src/java + +The options "minimum-tokens" and "files" are the two required options; there are more options, see below. + +### Options + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionRequiredApplies for language
--minimum-tokensThe minimum token length which should be reported as a duplicate.yes
--filesList of files and directories to processyes
--filelistPath to file containing a comma delimited list of files to analyze. If this is given, then you don't need to provide `--files`.no
--languageSources code language. Default value is `java`no
--encodingCharacter encoding to use when processing filesno
--skip-duplicate-filesIgnore multiple copies of files of the same name and length in comparison.no
--excludeFiles to be excluded from CPD checkno
--non-recursiveDon't scan subdirectioriesno
--skip-lexical-errorsSkip files which can't be tokenized due to invalid characters instead of aborting CPDno
--formatReport format. Default value is `text`.no
--failOnViolation {true|false}By default CPD exits with status 4 if code duplications are found. + Disable this option with '--failOnViolation false' to exit with 0 instead and just write the report.no
--ignore-literalsIgnore number values and string contents when comparing textnojava
--ignore-identifiersIgnore constant and variable names when comparing textnojava
--ignore-annotationsIgnore language annotations when comparing textnojava
--ignore-usingsIgnore using directives in C# when comparing textnoC#
--no-skip-blocksDo not skip code blocks marked with --skip-blocks-pattern (e.g. #if 0 until #endif)nocpp
--skip-blocks-pattern + Pattern to find the blocks to skip. Start and End pattern separated by |. + Default is `#if 0|#endif`. + nocpp
--uriURI to processnoplsql
--help / -hPrint help textno
+ +### Examples + +_Note:_ The following example use the Linux start script. For Windows, just replace "./run.sh cpd" by "cpd.bat". + + +Minimum required options: Just give it the minimum duplicate size and the source directory: + + $ ./run.sh cpd --minimum-tokens 100 --files /usr/local/java/src/java + +You can also specify the language: + + $ ./run.sh cpd --minimum-tokens 100 --files /path/to/c/source --language cpp + +You may wish to check sources that are stored in different directories: + + $ ./run.sh cpd --minimum-tokens 100 --files /path/to/other/source --files /path/to/other/source --files /path/to/other/source --language fortran + +There should be no limit to the number of '--files', you may add... But if you stumble one, please tell us ! + +And if you're checking a C source tree with duplicate files in different architecture directories +you can skip those using --skip-duplicate-files: + + $ ./run.sh cpd --minimum-tokens 100 --files /path/to/c/source --language cpp --skip-duplicate-files + +You can also specify the encoding to use when parsing files: + + $ ./run.sh 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: + + $ ./run.sh cpd --minimum-tokens 100 --files /usr/local/java/src/java --format xml + +The default format is a text report, and there's also a `csv` report. + +Note that CPD is pretty memory-hungry; you may need to give Java more memory to run it, like this: + + $ export HEAPSIZE=512m + $ ./run.sh cpd --minimum-tokens 100 --files /usr/local/java/src/java + +In order to change the heap size under Windows, you'll need to edit the batch file `cpd.bat` set the "OPTS" +variable to `-Xmx512m`. + + +If you specify a source directory but don't want to scan the sub-directories, you can use the non-recursive option: + + $ ./run.sh cpd --minimum-tokens 100 --non-recursive --files /usr/local/java/src/java + +### Exit status + +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 scripts or hooks, such as SVN hooks. + + + + + +
0Everything is fine, now code duplications found
1Couldn't understand command line parameters or CPD exited with an exception
4At least one code duplication has been detected unless '--failOnViolation false' is used.
+ + +### Supported Languages + +* cs +* cpp +* ecmascript (JavaScript) +* fortran +* go +* java +* jsp +* matlab +* objectivec +* php +* plsql +* python +* ruby +* scala +* swift + + +### Available formats + +* text : Default format +* xml +* csv +* csv_with_linecount_per_file +* vs + + +## Ant task + +Andy Glover wrote an Ant task for CPD; here's how to use it: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionApplies for languageRequired
encoding + 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.
+ If not specified, CPD uses the system default encoding. + 		No
formatThe format of the report (e.g. `csv`, `text`, `xml`); defaults to `text`.No
ignoreLiterals + 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`. + javaNo
ignoreIdentifiers + Similar to `ignoreLiterals` but for identifiers; i.e., variable names, methods names, + and so forth; defaults to `false`. + javaNo
ignoreAnnotations + 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`. + javaNo
ignoreUsings + Ignore using directives in C#. + C#No
skipDuplicateFiles + Ignore multiple copies of files of the same name and length in comparison; defaults to `false`. + No
skipLexicalErrors + Skip files which can't be tokenized due to invalid characters instead of aborting CPD; defaults to `false`. + No
skipBlocks + Enables or disabled skipping of blocks like a pre-processor; defaults to `true`. + See also option skipBlocksPattern. + cppNo
skipBlocksPattern + 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`. + cppno
language + Flag to select the appropriate language (e.g. `c`, `cpp`, `cs`, `java`, `jsp`, `php`, `ruby`, `fortran` + `ecmascript`, and `plsql`); defaults to `java`. + No
minimumtokencountA positive integer indicating the minimum duplicate size.Yes
outputfileThe destination file for the report. If not specified the console will be used instead.No
+ +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: + + + +## GUI + +CPD also comes with a simple GUI. You can start it via some scripts in the `bin` folder: + +For Windows: + + cpdgui.bat + +For Linux: + + ./run.sh cpdgui + +Here's a [screenshot](../images/screenshot_cpd.png) of CPD after running on the JDK 8 java.lang package: + +![CPD Screenshot after running on the JDK 8 java.lang package](../images/screenshot_cpd.png) + + +## Suppression + +Arbitrary blocks of code can be ignored through comments on **Java** by including the keywords `CPD-OFF` and `CPD-ON`. + + public Object someParameterizedFactoryMethod(int x) throws Exception { + // some unignored code + + // tell cpd to start ignoring code - CPD-OFF + + // mission critical code, manually loop unroll + goDoSomethingAwesome(x + x / 2); + goDoSomethingAwesome(x + x / 2); + goDoSomethingAwesome(x + x / 2); + goDoSomethingAwesome(x + x / 2); + goDoSomethingAwesome(x + x / 2); + goDoSomethingAwesome(x + x / 2); + + // resume CPD analysis - CPD-ON + + // further code will *not* be ignored + } + + +Additionally, **Java** allows to toggle suppression by adding the annotations +**`@SuppressWarnings("CPD-START")`** and **`@SuppressWarnings("CPD-END")`** +all code within will be ignored by CPD. + +This approach however, is limited to the locations were `@SuppressWarnings` is accepted. +It's legacy and the new comment's based approch should be favored. + + //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() { + } + + +Other languages currently have no support to suppress CPD reports. In the future, +the comment based approach will be extended to those of them that can support it. diff --git a/docs/pages/pmd/userdocs/pmd_userdocs_suppressing.md b/docs/pages/pmd/userdocs/pmd_userdocs_suppressing.md new file mode 100644 index 0000000000..fb659fcb73 --- /dev/null +++ b/docs/pages/pmd/userdocs/pmd_userdocs_suppressing.md @@ -0,0 +1,166 @@ +--- +title: Suppressing warnings +sidebar: pmd_sidebar +permalink: pmd_userdocs_suppressing.html +folder: pmd/userdocs +--- + +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 > 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: + + + + + + + + +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: + + + + + + + +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](https://github.com/pmd/pmd/issues). Thanks!