pmd:cpd

Note:

This goal should be used as a Maven report.

Full name:

org.apache.maven.plugins:maven-pmd-plugin:3.24.0:cpd

Description:

Creates a report for PMD's Copy/Paste Detector (CPD) tool. It can also generate a cpd results file in any of these formats: xml, csv or txt.

See Finding duplicated code for more details.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 2.0.

Required Parameters

Name Type Since Description
<targetDirectory> File - The output directory for the intermediate XML report.
User Property: project.build.directory

Optional Parameters

Name Type Since Description
<aggregate> boolean 2.2
Deprecated.
since 3.15.0 Use the goals pmd:aggregate-pmd and pmd:aggregate-cpd instead. See FAQ: Why do I get sometimes false positive and/or false negative violations? for an explanation.

Whether to build an aggregated report at the root, or build individual reports.
Default: false
User Property: aggregate
<compileSourceRoots> List<String> 3.7 Specifies the location of the source directories to be used for PMD. Defaults to project.compileSourceRoots.
Default: ${project.compileSourceRoots}
<excludeFromFailureFile> String 3.7 File that lists classes and rules to be excluded from failures. For PMD, this is a properties file. For CPD, this is a text file that contains comma-separated lists of classes that are allowed to duplicate.
User Property: pmd.excludeFromFailureFile
<excludeRoots> File[] 2.2 The project source directories that should be excluded.
<excludes> List<String> 2.2 A list of files to exclude from checking. Can contain Ant-style wildcards and double wildcards. Note that these exclusion patterns only operate on the path of a source file relative to its source root directory. In other words, files are excluded based on their package and/or class name. If you want to exclude entire source root directories, use the parameter excludeRoots instead.
<format> String - Set the output format type, in addition to the HTML report. Must be one of: "none", "csv", "xml", "txt" or the full class name of the PMD renderer to use. See the net.sourceforge.pmd.renderers package javadoc for available renderers. XML is produced in any case, since this format is needed for the check goals (pmd:check, pmd:aggregator-check, pmd:cpd-check, pmd:aggregator-cpd-check).
Default: xml
User Property: format
<ignoreAnnotations> boolean 3.11.0 If true, CPD ignores annotations.
Default: false
User Property: cpd.ignoreAnnotations
<ignoreIdentifiers> boolean 2.5 Similar to ignoreLiterals but for identifiers; i.e., variable names, methods names, and so forth.
Default: false
User Property: cpd.ignoreIdentifiers
<ignoreLiterals> boolean 2.5 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.
Default: false
User Property: cpd.ignoreLiterals
<includeTests> boolean 2.2 Run PMD on the tests as well.
Default: false
<includeXmlInSite> boolean 3.0 Whether to include the xml files generated by PMD/CPD in the site.
Default: false
<includes> List<String> 2.2 A list of files to include from checking. Can contain Ant-style wildcards and double wildcards. Defaults to **\/*.java.
<jdkToolchain> Map<String,String> 3.14.0

Allow for configuration of the jvm used to run PMD via maven toolchains. This permits a configuration where the project is built with one jvm and PMD is executed with another. This overrules the toolchain selected by the maven-toolchain-plugin.

Examples:

(see Guide to Toolchains for more info)

   <configuration>
       ...
       <jdkToolchain>
           <version>1.11</version>
       </jdkToolchain>
   </configuration>

   <configuration>
       ...
       <jdkToolchain>
           <version>1.8</version>
           <vendor>zulu</vendor>
       </jdkToolchain>
   </configuration>
   
note: requires at least Maven 3.3.1
<language> String 3.5 The programming language to be analyzed by CPD. Valid values are currently java, javascript or jsp.
Default: java
<linkXRef> boolean - Link the violation line numbers to the source xref. Links will be created automatically if the jxr plugin is being used.
Default: true
User Property: linkXRef
<minimumTokens> int - The minimum number of tokens that need to be duplicated before it causes a violation.
Default: 100
User Property: minimumTokens
<showPmdLog> boolean 3.9.0
Deprecated.
With 3.22.0 and the upgrade to PMD 7, this parameter has no effect anymore. The PMD log is now always redirected into the maven log and this can't be disabled by this parameter anymore. In order to disable the logging, see Maven Logging. You'd need to start maven with MAVEN_OPTS=-Dorg.slf4j.simpleLogger.log.net.sourceforge.pmd=off mvn <goals>.

Redirect PMD log into maven log out. When enabled, the PMD log output is redirected to maven, so that it is visible in the console together with all the other log output. Also, if maven is started with the debug flag (-X or --debug), the PMD logger is also configured for debug.
Default: true
User Property: pmd.showPmdLog
<skip> boolean 2.1 Skip the CPD report generation. Most useful on the command line via "-Dcpd.skip=true".
Default: false
User Property: cpd.skip
<skipEmptyReport> boolean 3.1 Skip the PMD/CPD report generation if there are no violations or duplications found. Defaults to false.

Note: the default value was changed from true to false with version 3.13.0.


Default: false
<testSourceRoots> List<String> 3.7 The directories containing the test-sources to be used for PMD. Defaults to project.testCompileSourceRoots
Default: ${project.testCompileSourceRoots}
<xrefLocation> File - Location of the Xrefs to link to.
Default: ${project.reporting.outputDirectory}/xref
<xrefTestLocation> File - Location of the Test Xrefs to link to.
Default: ${project.reporting.outputDirectory}/xref-test

Parameter Details

<aggregate>

Deprecated.
since 3.15.0 Use the goals pmd:aggregate-pmd and pmd:aggregate-cpd instead. See FAQ: Why do I get sometimes false positive and/or false negative violations? for an explanation.

Whether to build an aggregated report at the root, or build individual reports.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • User Property: aggregate
  • Default: false

<compileSourceRoots>

Specifies the location of the source directories to be used for PMD. Defaults to project.compileSourceRoots.
  • Type: java.util.List<java.lang.String>
  • Since: 3.7
  • Required: No
  • Default: ${project.compileSourceRoots}

<excludeFromFailureFile>

File that lists classes and rules to be excluded from failures. For PMD, this is a properties file. For CPD, this is a text file that contains comma-separated lists of classes that are allowed to duplicate.
  • Type: java.lang.String
  • Since: 3.7
  • Required: No
  • User Property: pmd.excludeFromFailureFile

<excludeRoots>

The project source directories that should be excluded.
  • Type: java.io.File[]
  • Since: 2.2
  • Required: No

<excludes>

A list of files to exclude from checking. Can contain Ant-style wildcards and double wildcards. Note that these exclusion patterns only operate on the path of a source file relative to its source root directory. In other words, files are excluded based on their package and/or class name. If you want to exclude entire source root directories, use the parameter excludeRoots instead.
  • Type: java.util.List<java.lang.String>
  • Since: 2.2
  • Required: No

<format>

Set the output format type, in addition to the HTML report. Must be one of: "none", "csv", "xml", "txt" or the full class name of the PMD renderer to use. See the net.sourceforge.pmd.renderers package javadoc for available renderers. XML is produced in any case, since this format is needed for the check goals (pmd:check, pmd:aggregator-check, pmd:cpd-check, pmd:aggregator-cpd-check).
  • Type: java.lang.String
  • Required: No
  • User Property: format
  • Default: xml

<ignoreAnnotations>

If true, CPD ignores annotations.
  • Type: boolean
  • Since: 3.11.0
  • Required: No
  • User Property: cpd.ignoreAnnotations
  • Default: false

<ignoreIdentifiers>

Similar to ignoreLiterals but for identifiers; i.e., variable names, methods names, and so forth.
  • Type: boolean
  • Since: 2.5
  • Required: No
  • User Property: cpd.ignoreIdentifiers
  • Default: false

<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.
  • Type: boolean
  • Since: 2.5
  • Required: No
  • User Property: cpd.ignoreLiterals
  • Default: false

<includeTests>

Run PMD on the tests as well.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • Default: false

<includeXmlInSite>

Whether to include the xml files generated by PMD/CPD in the site.
  • Type: boolean
  • Since: 3.0
  • Required: No
  • Default: false

<includes>

A list of files to include from checking. Can contain Ant-style wildcards and double wildcards. Defaults to **\/*.java.
  • Type: java.util.List<java.lang.String>
  • Since: 2.2
  • Required: No

<jdkToolchain>

Allow for configuration of the jvm used to run PMD via maven toolchains. This permits a configuration where the project is built with one jvm and PMD is executed with another. This overrules the toolchain selected by the maven-toolchain-plugin.

Examples:

(see Guide to Toolchains for more info)

   <configuration>
       ...
       <jdkToolchain>
           <version>1.11</version>
       </jdkToolchain>
   </configuration>

   <configuration>
       ...
       <jdkToolchain>
           <version>1.8</version>
           <vendor>zulu</vendor>
       </jdkToolchain>
   </configuration>
   
note: requires at least Maven 3.3.1
  • Type: java.util.Map<java.lang.String, java.lang.String>
  • Since: 3.14.0
  • Required: No

<language>

The programming language to be analyzed by CPD. Valid values are currently java, javascript or jsp.
  • Type: java.lang.String
  • Since: 3.5
  • Required: No
  • Default: java

<linkXRef>

Link the violation line numbers to the source xref. Links will be created automatically if the jxr plugin is being used.
  • Type: boolean
  • Required: No
  • User Property: linkXRef
  • Default: true

<minimumTokens>

The minimum number of tokens that need to be duplicated before it causes a violation.
  • Type: int
  • Required: No
  • User Property: minimumTokens
  • Default: 100

<showPmdLog>

Deprecated.
With 3.22.0 and the upgrade to PMD 7, this parameter has no effect anymore. The PMD log is now always redirected into the maven log and this can't be disabled by this parameter anymore. In order to disable the logging, see Maven Logging. You'd need to start maven with MAVEN_OPTS=-Dorg.slf4j.simpleLogger.log.net.sourceforge.pmd=off mvn <goals>.

Redirect PMD log into maven log out. When enabled, the PMD log output is redirected to maven, so that it is visible in the console together with all the other log output. Also, if maven is started with the debug flag (-X or --debug), the PMD logger is also configured for debug.
  • Type: boolean
  • Since: 3.9.0
  • Required: No
  • User Property: pmd.showPmdLog
  • Default: true

<skip>

Skip the CPD report generation. Most useful on the command line via "-Dcpd.skip=true".
  • Type: boolean
  • Since: 2.1
  • Required: No
  • User Property: cpd.skip
  • Default: false

<skipEmptyReport>

Skip the PMD/CPD report generation if there are no violations or duplications found. Defaults to false.

Note: the default value was changed from true to false with version 3.13.0.

  • Type: boolean
  • Since: 3.1
  • Required: No
  • Default: false

<targetDirectory>

The output directory for the intermediate XML report.
  • Type: java.io.File
  • Required: Yes
  • User Property: project.build.directory

<testSourceRoots>

The directories containing the test-sources to be used for PMD. Defaults to project.testCompileSourceRoots
  • Type: java.util.List<java.lang.String>
  • Since: 3.7
  • Required: No
  • Default: ${project.testCompileSourceRoots}

<xrefLocation>

Location of the Xrefs to link to.
  • Type: java.io.File
  • Required: No
  • Default: ${project.reporting.outputDirectory}/xref

<xrefTestLocation>

Location of the Test Xrefs to link to.
  • Type: java.io.File
  • Required: No
  • Default: ${project.reporting.outputDirectory}/xref-test