Installation and basic CLI usage

How to install PMD and CPD

Requirements

• Java 8 or above: Java JRE, OpenJDK from Azul or Adoptium.

• A zip archiver, e.g.:

  • For Windows: Winzip or the free 7-zip
  • For Linux / Unix: InfoZip

Installation

PMD is distributed as a zip archive, which includes both PMD and CPD. You can download the latest binary distribution from the github releases page.

It’s highly recommended (but not required) to include it to your PATH.

On Linux you can do this by adding PATH=$PATH:*path_to_pmd*/bin/ to your ~/.bashrc / ~/.zshrc file.

On Windows this is achieved by:

1. On the Start menu, right-click Computer.
2. On the context menu, click Properties.
3. In the System dialog box, click Advanced system settings.
4. On the Advanced tab of the System Properties dialog box, click Environment Variables
5. In the System Variables box of the Environment Variables dialog box, scroll to Path and select it.
6. Click the lower of the two Edit buttons in the dialog box.
7. In the Edit System Variable dialog box, scroll to the end of the string in the Variable value box and add a semicolon (;).
8. Add the proper value for *path_to_pmd*/bin/ after the semicolon.
9. Click OK in three successive dialog boxes, and then close the System dialog box.

Shell completion

PMD ships with built-in completion support for Bash / Zsh.

To enable it, simply add source <(pmd generate-completion) to your ~/.bashrc / ~/.zshrc file.

Running PMD via command line

Running a PMD analysis (pmd check or pmd.bat check) requires at least one option and a list of sources:

• -R <path>: the ruleset file you want to use. PMD uses xml configuration files, called rulesets, which specify which rules to execute on your sources. You can also run a single rule by referencing it using its category and name (more details here). For example, you can check for unnecessary modifiers on Java sources with -R category/java/codestyle.xml/UnnecessaryModifier.
• <source> …: path to the sources to analyse. This can be a file name, a directory, or a jar or zip file containing the sources. Alternatively You can use the -d or --dir flag, which is equivalent.

Additionally, the following options, are specified most of the time even though they’re not required:

• -f <format>: report format. PMD supports many report formats out of the box. You may want to start with the basic text format (default) or xml format. The supported formats are documented here.
• --aux-classpath <classpath>: class path containing the compiled class files of the analysed Java sources, if any. Setting this up correctly allows PMD to do much deeper analysis using reflection. Some rules, such as MissingOverride, require it to function properly.

Sample usage

The following shows a sample run of PMD with the text format:

~ $ pmd check -f text -R rulesets/java/quickstart.xml src/main/java

.../src/main/java/com/me/RuleSet.java:123  These nested if statements could be combined
.../src/main/java/com/me/RuleSet.java:231  Useless parentheses.
.../src/main/java/com/me/RuleSet.java:232  Useless parentheses.
.../src/main/java/com/me/RuleSet.java:357  These nested if statements could be combined
.../src/main/java/com/me/RuleSetWriter.java:66     Avoid empty catch blocks

C:\> pmd.bat check -f text -R rulesets/java/quickstart.xml ..\..\src\main\java

...\src\main\java\com\me\RuleSet.java:123  These nested if statements could be combined
...\src\main\java\com\me\RuleSet.java:231  Useless parentheses.
...\src\main\java\com\me\RuleSet.java:232  Useless parentheses.
...\src\main\java\com\me\RuleSet.java:357  These nested if statements could be combined
...\src\main\java\com\me\RuleSetWriter.java:66     Avoid empty catch blocks

Running CPD via command line

Like for PMD, CPD is started on Unix by pmd cpd and on Windows by pmd.bat cpd, and it requires one option and a list of sources:

• --minimum-tokens <number>: the minimum token length which should be reported as a duplicate.
• <source> …: path to the sources to analyse. This can be a file name, a directory, or a jar or zip file containing the sources. Alternatively You can use the -d or --dir flag, which is equivalent.

Sample usage

The following shows a sample run of CPD with the text format:

~ $ pmd cpd --minimum-tokens 100 /home/me/src

Found a 7 line (110 tokens) duplication in the following files:
Starting at line 579 of /home/me/src/test/java/foo/FooTypeTest.java
Starting at line 586 of /home/me/src/test/java/foo/FooTypeTest.java

assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());

C:\> pmd.bat cpd --minimum-tokens 100 c:\temp\src

Found a 7 line (110 tokens) duplication in the following files:
Starting at line 579 of c:\temp\src\test\java\foo\FooTypeTest.java
Starting at line 586 of c:\temp\src\test\java\foo\FooTypeTest.java

assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());
assertEquals(Boolean.TYPE, expressions.get(index++).getType());