diff --git a/src/site/apt/examples/aggregate.apt.vm b/src/site/apt/examples/aggregate.apt.vm deleted file mode 100644 index 7b1bcd21..00000000 --- a/src/site/apt/examples/aggregate.apt.vm +++ /dev/null @@ -1,219 +0,0 @@ - ------ - Aggregating PMD reports for Multi-Module-Projects - ------ - Andreas Dangel - ------ - 2021-09-03 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Aggregating PMD reports for Multi-Module-Projects - - For example, consider the following directory structure: - -+-----+ - -Project - |-- pom.xml - |-- Module1 - | `-- pom.xml - | `-- Module 2 - | `-- pom.xml - | `-- Module 3 - | `-- pom.xml - |-- Module4 - | `-- pom.xml - `-- Module5 - `-- pom.xml - -+-----+ - - Since 3.15.0 the <<>> has changed a little bit. It'll generate aggregated - reports at every level. - To get only an aggregated project at root level, you need to configure the pom like: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - aggregate - false - - aggregate-pmd - aggregate-cpd - - - - default - - pmd - cpd - - - - - - ... - - ... - -+-----+ - -* Using The <<>> Goals - - The {{{../pmd-mojo.html#aggregate}\}} parameter doesn't make sure, that the project is - compiled before executing PMD which might lead to wrong results. Therefore the report goals - <<>> and <<>> have been introduced. You could define these goals in the - \ element (using the \ tag) or \ element (using the \ tag) as shown - below. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - ... - - - - aggregate - - aggregate-pmd - aggregate-cpd - - site - - - ... - - - ... - - - ... - - - ... - -+-----+ - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - ... - - - - non-aggregate - - - ... - - - pmd - cpd - - - - aggregate - - - ... - - - aggregate-pmd - aggregate-cpd - - - ... - - - ... - - - ... - -+-----+ - -* Generate aggregate PMD without duplicate execution of phase test-compile - - * The standard goal <<>> invokes separate lifecyle <<>>. - - * In a CI environment you now might execute something like <<>>. - - * During <<>> build the standard reports will trigger <<>> again, - depending on your build this may take some time, because - stuff like <<>> or generating stubs from a WDSL will be invoked again, which may lead - to longer build times. - - * As of version 3.15.0 a new report is defined, <<>> - which will not trigger above phases a second time. - - * Note: This is only a problem for PMD report. CPD does not invoke a separate lifecycle. - - * Configure this in your <<>> section as follows: - -+-----+ - - ... - - true - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - - aggregate-pmd-no-fork - aggregate-cpd - - - - - - - ... - -+-----+ diff --git a/src/site/apt/examples/cpdCsharp.apt.vm b/src/site/apt/examples/cpdCsharp.apt.vm deleted file mode 100644 index 02a66391..00000000 --- a/src/site/apt/examples/cpdCsharp.apt.vm +++ /dev/null @@ -1,91 +0,0 @@ - ------ - Finding duplicated code in C# - ------ - Andreas Dangel - ------ - 2020-10-02 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Finding duplicated code in C# - - By default, the maven-pmd-plugin only supports the languages Java, JavaScript and JSP. - But {{{https://pmd.github.io/latest/pmd_userdocs_cpd.html#supported-languages}CPD supports many more languages}}, - e.g. C#. In order to enable C# in your build, you need to - configure several parts: - - * Add an additional plugin dependency for c# (pmd-cs module) - - * Select the language <<>>. - - * Configure the includes filter to consider <<<*.cs>>> (otherwise only java files will be analyzed) - - * Configure the source directory (by default, only <<>> is analyzed) - - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - cs - 10 - - **/*.cs - - - ${basedir}/src/main/cs - - true - - - - - cpd-check - - - - - - net.sourceforge.pmd - pmd-cs - ${pmdVersion} - - - - ... - - - -+-----+ - - In this example, the C# source files are located in <<>>. - - <> The version for <<>> needs to match the PMD version. - If you {{{./upgrading-PMD-at-runtime.html}upgrade PMD at runtime}}, you need to - change the version here as well. - diff --git a/src/site/apt/examples/differentRulesetForTests.apt.vm b/src/site/apt/examples/differentRulesetForTests.apt.vm deleted file mode 100644 index e5c028b6..00000000 --- a/src/site/apt/examples/differentRulesetForTests.apt.vm +++ /dev/null @@ -1,112 +0,0 @@ - ------ - Using a different ruleset for tests - ------ - Andreas Dangel - ------ - 2021-07-09 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Using a different ruleset for tests - - PMD shall be configured to scan test source code with a less strict - ruleset than production code. This can be achieved by configuring - multiple plugin - {{{https://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_executions_Tag}executions}} - with different configurations. - - <> There are different opinions whether one should lower - that quality just because it's "just test code". While test code doesn't run - in production, it's used to test production code, so you might consider - the test code then as your weakest link if you use less strict checks. - - Here's the complete plugin configuration for this scenario: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - false - - config/pmd/pmdMain.xml - - false - - - - pmd-main - verify - - check - - - - pmd-test - verify - - pmd - check - - - \${project.build.directory}/pmdTest/ - true - - ${basedir}/src/main/java - - - config/pmd/pmdTest.xml - - - - - cpd - verify - - cpd-check - - - - - ... - - - -+-----+ - - It uses the ruleset <<>> for the main code without tests. This is configured - directly at the plugin level. The ruleset <<>> is used for the test code only. - This is configured in the execution with id <<>>. - - This solution has one downside though: PMD is run three times: Twice for the main code, and once for - the test code. The reason is that "pmd:check" triggers automatically "pmd:pmd", but it uses only the - standard configuration (e.g. it ignores the lifecycle/execution id). - - The execution <<>> calls once "pmd:pmd" for the test code (which creates - <<>>), then calls "pmd:check" - which itself calls "pmd:pmd" and uses - the default configuration - and finally runs "pmd:check" actually, which uses the execution - configuration and uses <<>> to decide whether to fail the build. diff --git a/src/site/apt/examples/javascriptReport.apt.vm b/src/site/apt/examples/javascriptReport.apt.vm deleted file mode 100644 index 38830591..00000000 --- a/src/site/apt/examples/javascriptReport.apt.vm +++ /dev/null @@ -1,81 +0,0 @@ - ------ - Analyzing JavaScript Code - ------ - Andreas Dangel - ------ - 2017-11-11 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Analyzing JavaScript Code - - The PMD plugin analyzes Java by default. You can configure it to analyze JavaScript files instead as shown below. - - The example assumes that the JavaScript source code is stored in the subdirectory <<>> and - enables all rules from the "Best Practices", "Codestyle", and "Error Prone" categories. - - Note that you have to make sure that you configure <<>> and <<>>, so that - PMD finds the JavaScript files. - - See {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_ecmascript.html}JavaScript Rule Index}} for the list - of available rules. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - javascript - - /category/ecmascript/bestpractices.xml - /category/ecmascript/codestyle.xml - /category/ecmascript/errorprone.xml - - - **/*.js - - - ${basedir}/src/main/javascript - - - - - - pmd - - - - - - - ... - -+-----+ - - <> Configuring <<>> only works with Maven 3.3.9 and later. For older versions, - you'll need to use with the <<>> goal in order to add - the additional source directories, so that PMD finds the JavaScript files. diff --git a/src/site/apt/examples/jspReport.apt.vm b/src/site/apt/examples/jspReport.apt.vm deleted file mode 100644 index a75a44de..00000000 --- a/src/site/apt/examples/jspReport.apt.vm +++ /dev/null @@ -1,84 +0,0 @@ - ------ - Analyzing JSP Code - ------ - Thomas Williamson - ------ - 2017-11-11 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Analyzing JSP Code - - The PMD plugin analyzes Java by default. You can configure it to analyze Java Server Pages files instead as shown below. - - The example assumes that the JSP source code is stored in various subdirectories under the source directory - <<>> and enables all rules from the categories "Best Practices", "Codestyle", - "Design", "Error Prone" and "Security". - - Note that you have to make sure that you configure <<>> and <<>>, so that - PMD finds the JSP files. - - See {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_jsp.html}JSP Rule Index}} for a complete list - of available rules. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - jsp - - /category/jsp/bestpractices.xml - /category/jsp/codestyle.xml - /category/jsp/design.xml - /category/jsp/errorprone.xml - /category/jsp/security.xml - - - **/*.jsp - - - ${basedir}/src/main/webapp - - - - - - pmd - - - - - - - ... - -+-----+ - - <> Configuring <<>> only works with Maven 3.3.9 and later. For older versions, - you'll need to use with the <<>> goal in order to add - the additional source directories, so that PMD finds the JSP files. diff --git a/src/site/apt/examples/removeReport.apt.vm b/src/site/apt/examples/removeReport.apt.vm deleted file mode 100644 index ff1afa78..00000000 --- a/src/site/apt/examples/removeReport.apt.vm +++ /dev/null @@ -1,62 +0,0 @@ - ------ - Remove Report - ------ - Dennis Lundberg - ------ - 2021-09-03 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Remove Report - - You may want to generate only one of the reports, but not the other. Since version 3.15.0 separate - aggregate reports have been added, which would duplicate the reports. To select only the reports you want - you can use the <<<\>>> feature within your POM. Below is - the default configuration for the plugin. To disable one of the reports, - just copy the <<<\>>> element below to your POM and remove the - <<<\>>> you don't want to generate. - -+--------------------+ - - ... - - - - maven-pmd-plugin - ${project.version} - - - - pmd - cpd - aggregate-pmd - aggregate-pmd-no-fork - aggregate-cpd - - - - - - - ... - -+--------------------+ diff --git a/src/site/apt/examples/targetJdk.apt.vm b/src/site/apt/examples/targetJdk.apt.vm deleted file mode 100644 index bd4f20f2..00000000 --- a/src/site/apt/examples/targetJdk.apt.vm +++ /dev/null @@ -1,69 +0,0 @@ - ------ - Target JDK and Toolchains - ------ - Dennis Lundberg - Andreas Dangel - ------ - 2020-10-02 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Target JDK - - There is a configuration element in the PMD plugin that lets you set which - {{{../pmd-mojo.html#targetJdk}target JDK}} your Java code will be compiled for. - Often you want this to be in sync with the configuration for maven-compiler-plugin. - The best practice for this is to set up the wellknown property <<>> - and the rest will work automatically. Alternatively, you can set it manually: - -+--------------------+ - - ... - - - - maven-pmd-plugin - ${project.version} - - 1.6 - - - - - ... - -+--------------------+ - -Using Maven Toolchains - - Since version 3.14.0 of the PMD plugin, toolchains are supported. This helps if the build system is - running a different JDK than being used for compiling. PMD reads the class files for - {{{../pmd-mojo.html#typeResolution}type resolution}} and this fails with ClassFormatErrors - if the JDK version is incorrect. - - To set this up, refer to the {{{/guides/mini/guide-using-toolchains.html}Guide to Using Toolchains}}, which makes use - of the {{{/plugins/maven-toolchains-plugin/}Maven Toolchains Plugin}}. - - With the maven-toolchains-plugin you configure 1 default JDK toolchain for all related maven-plugins. - Since maven-pmd-plugin 3.14.0 when using with Maven 3.3.1+ it is also possible to give the plugin its own - toolchain, which can be useful in case of different JDK calls per execution block (e.g. the test sources require a - different JDK compared to the main sources). diff --git a/src/site/apt/examples/upgrading-PMD-at-runtime.apt.vm b/src/site/apt/examples/upgrading-PMD-at-runtime.apt.vm deleted file mode 100644 index f041645d..00000000 --- a/src/site/apt/examples/upgrading-PMD-at-runtime.apt.vm +++ /dev/null @@ -1,134 +0,0 @@ - ------ - Upgrading PMD at Runtime - ------ - Andreas Dangel - ------ - 2017-08-19 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Upgrading PMD at Runtime - - The Maven PMD plugin comes with a default PMD version: for <<>>, - <> is used by default. - - Given that the {{{https://pmd.github.io}newer PMD version}} is compatible, - you can override the PMD version, that the Maven plugin will use and benefit - from the latest bugfixes and enhancements: - -+-----+ - - - ...choose your version... - -... - - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - net.sourceforge.pmd - pmd-core - \${pmdVersion} - - - net.sourceforge.pmd - pmd-java - \${pmdVersion} - - - net.sourceforge.pmd - pmd-javascript - \${pmdVersion} - - - net.sourceforge.pmd - pmd-jsp - \${pmdVersion} - - - - - - -... - -+-----+ - -* Version relationship between maven-pmd-plugin and PMD - - Every maven-pmd-plugin version ships with a default PMD version. The default PMD version - is upgraded irregularly, e.g. when support for a newer Java version is required. - - Here's a historical overview about the default PMD version used: - -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| <> | <> | -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.28.0/}3.28.0}} | {{{https://docs.pmd-code.org/pmd-doc-7.17.0/}7.17.0}} | -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.27.0/}3.27.0}} | {{{https://docs.pmd-code.org/pmd-doc-7.14.0/}7.14.0}} | -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.26.0/}3.26.0}} | {{{https://docs.pmd-code.org/pmd-doc-7.7.0/}7.7.0}} | -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.24.0/}3.24.0}} | {{{https://docs.pmd-code.org/pmd-doc-7.3.0/}7.3.0}} | -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.22.0/}3.22.0}} | {{{https://docs.pmd-code.org/pmd-doc-7.0.0/}7.0.0}} | -*--------------------------------------------------------------------------------*-----------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.21.0/}3.21.0}} | {{{https://pmd.github.io/pmd-6.55.0/}6.55.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.20.0/}3.20.0}} | {{{https://pmd.github.io/pmd-6.53.0/}6.53.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.19.0/}3.19.0}} | {{{https://pmd.github.io/pmd-6.49.0/}6.49.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.18.0/}3.18.0}} | {{{https://pmd.github.io/pmd-6.48.0/}6.48.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.17.0/}3.17.0}} | {{{https://pmd.github.io/pmd-6.46.0/}6.46.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.16.0/}3.16.0}} | {{{https://pmd.github.io/pmd-6.42.0/}6.42.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.15.0/}3.15.0}} | {{{https://pmd.github.io/pmd-6.38.0/}6.38.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.14.0/}3.14.0}} | {{{https://pmd.github.io/pmd-6.29.0/}6.29.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.13.0/}3.13.0}} | {{{https://pmd.github.io/pmd-6.21.0/}6.21.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.12.0/}3.12.0}} | {{{https://pmd.github.io/pmd-6.13.0/}6.13.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.11.0/}3.11.0}} | {{{https://pmd.sourceforge.io/pmd-6.8.0/}6.8.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.10.0/}3.10.0}} | {{{https://pmd.sourceforge.io/pmd-6.4.0/}6.4.0}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.9.0/}3.9.0}} | {{{https://pmd.sourceforge.io/pmd-6.0.1/}6.0.1}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.8/}3.8}} | {{{https://pmd.sourceforge.io/pmd-5.6.1/}5.6.1}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.7/}3.7}} | {{{https://pmd.sourceforge.io/pmd-5.5.1/}5.5.1}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.6/}3.6}} | {{{https://pmd.sourceforge.io/pmd-5.3.5/}5.3.5}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* -| {{{https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.5/}3.5}} | {{{https://pmd.sourceforge.io/pmd-5.3.2/}5.3.2}} | -*--------------------------------------------------------------------------------*--------------------------------------------------* diff --git a/src/site/apt/examples/violation-exclusions.apt.vm b/src/site/apt/examples/violation-exclusions.apt.vm deleted file mode 100644 index 5d136748..00000000 --- a/src/site/apt/examples/violation-exclusions.apt.vm +++ /dev/null @@ -1,120 +0,0 @@ - ------ - Violation Exclusions - ------ - 2013-02-08 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Violation Exclusions - - It is possible to exclude some sources from PMD/CPD check to prevent failures. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - - check - - - exclude-pmd.properties - - - - - cpd-check - - - exclude-cpd.properties - - - - - - - ... - -+-----+ - - For cpd check, you can exclude classes to not verify. Classes can be specified in two ways: - - [[1]] Comma-separated: org.apache.maven.ClassA and org.apache.maven.ClassB contain duplicated code across classes. - - [[2]] Single class per line: org.apache.maven.ClassC and org.apache.maven.ClassD do not share duplicate code, - but have duplicated code internally. - - The properties file for cpd must have the following format: - -+-----+ -org.apache.maven.ClassA,org.apache.maven.ClassB -org.apache.maven.ClassC -org.apache.maven.ClassD -+-----+ - - For pmd check, you can exclude rules per classes. The properties file must have the following format: - -+-----+ -org.apache.maven.ClassA=UnusedPrivateField,EmptyCatchBlock -org.apache.maven.ClassB=UnusedPrivateField,UnusedFormalParameter,UnusedPrivateMethod -+-----+ - - - You can only exclude (checks for) classes through the exclusion files. - If you want more flexibility and exclude classes with a certain name, or whole packages, - for example because of generated code, you have to do this in the <<<>>> section of the plugin, - using the <<<>>> or <<<>>> elements. - To avoid confusion, don't write those to the plugin's configuration as a <<<>>> and <<<>>> plugin. - Instead, configure the plugin in the <<<>>> section of your POM, so executions of the build and site lifecycle pick it up. - -+-----+ - - ... - - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - **/*Bean.java - **/generated/*.java - - - target/generated-sources/stubs - - - - - - - ... - -+-----+ diff --git a/src/site/apt/examples/violationChecking.apt.vm b/src/site/apt/examples/violationChecking.apt.vm deleted file mode 100644 index a910e362..00000000 --- a/src/site/apt/examples/violationChecking.apt.vm +++ /dev/null @@ -1,59 +0,0 @@ - ------ - Violation Checking - ------ - 2006-06-23 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Violation Checking - - The <<>> and <<>> goals allow you to configure your build to fail if any errors are found - in the PMD or CPD reports respectively. In doing so you can enforce your own custom code quality rules. - - The rule violations may optionally be displayed on the build output using the <<>> setting. - - The following code fragment enables both the standard PMD check and the CPD check in a build, during the <<>> - phase. - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - - check - cpd-check - - - - - - - ... - -+-----+ diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index 1ec94a1c..00000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,145 +0,0 @@ - ------ - Introduction - ------ - Dennis Lundberg - ------ - 2017-11-11 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -${project.name} - - The PMD Plugin allows you to automatically run the {{{https://pmd.github.io/}PMD}} code analysis tool - on your project's source code and generate a site report with its results. It also supports the separate - Copy/Paste Detector tool (or CPD) distributed with PMD. - - This version of Maven PMD Plugin uses PMD ${pmdVersion} and requires Java ${javaVersion}. - See {{{./examples/upgrading-PMD-at-runtime.html}Upgrading PMD at Runtime}} for more information. - - The plugin accepts configuration parameters that can be used to customize the execution of the PMD tool. - - -* Goals Overview - - This plugin has the following goals: - - * {{{./pmd-mojo.html}pmd:pmd}} creates a PMD site report based on the rulesets and configuration set in the plugin. - It can also generate a pmd output file aside from the site report in any of the following formats: xml, csv or txt. - - * {{{./aggregate-pmd-mojo.html}pmd:aggregate-pmd}} creates a PMD site report in an <> project - based on the rulesets and configuration set in the plugin. It can also generate a pmd output file aside from - the site report in any of the following formats: xml, csv or txt. - - * {{{./aggregate-pmd-no-fork-mojo.html}pmd:aggregate-pmd-no-fork}} creates a PMD site report in an <> - project without forking the <<>> phase again. - - * {{{./cpd-mojo.html}pmd:cpd}} 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. - - * {{{./aggregate-cpd-mojo}pmd:aggregate-cpd}} creates a report for PMD's Copy/Paste Detector (CPD) tool - in an <> project. It can also generate a cpd results file in any of these formats: xml, csv or txt. - - * {{{./check-mojo.html}pmd:check}} fails the build if there were any PMD violations in the source code. - This goal invokes automatically <<>> prior to executing itself. - - * {{{./aggregate-pmd-check-mojo.html}pmd:aggregate-pmd-check}} fails the build in an <> project if there - were any PMD violations in the source code. - This goal invokes automatically <<>> prior to executing itself. - - * {{{./cpd-check-mojo.html}pmd:cpd-check}} fails the build if there were any CPD violations in the source code. - This goal invokes automatically <<>> prior to executing itself. - - * {{{./aggregate-cpd-check-mojo.html}pmd:aggregate-cpd-check}} fails the build in an <> project - if there were any CPD violations in the source code. - This goal invokes automatically <<>> prior to executing itself. - -* Usage - - General instructions on how to use the PMD Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. - - In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. - - If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Upgrading Notes - -** 3.22.0 - - * Starting with Maven PMD Plugin 3.22.0, the plugin requires PMD version 7.0.0 or higher. - PMD 7.0.0 switched to SLF4J and since Maven 3.1.0+ SLF4J is the default logging API. - Logs from PMD are now always shown and cannot be disabled at runtime after maven has started. - The property <<>> makes no sense anymore and is deprecated now. See - {{{https://maven.apache.org/maven-logging.html}Maven Logging}} for how to configure logging. - For disabling PMD logs, you'd need to start maven with << >>>. - - * The upgrade from PMD 6 to PMD 7.0.0 is a major version change. If you use the default ruleset - from Maven PMD Plugin, then everything should just work. But if you use a custom ruleset, you - most likely need to review your ruleset and migrate it to PMD 7. Rules might have been renamed or - replaced. See {{{https://docs.pmd-code.org/latest/pmd_release_notes_pmd7.html}Detailed Release Notes for PMD 7}} - and {{{https://docs.pmd-code.org/latest/pmd_userdocs_migrating_to_pmd7.html}Migration Guide for PMD 7}}. - - * If you currently override the dependency to PMD ({{{./examples/upgrading-PMD-at-runtime.html}Upgrading PMD at Runtime}}) - make sure to upgrade PMD as well to 7.0.0 or later when upgrading the Maven PMD Plugin. - -** 3.9.0 - - * Starting with PMD 6.0.0 and Maven PMD Plugin 3.9.0, the rules have been reorganized - into categories, e.g. <<>>. So when upgrading to - Maven PMD Plugin 3.9.0 you should review your plugin configuration and/or custom ruleset. - See {{{./examples/usingRuleSets.html}Using Rule Sets}} for more information. - - -* Examples - - To provide you with better understanding of some usages of the Maven PMD Plugin, you can take a look into the - following examples: - - * {{{./examples/upgrading-PMD-at-runtime.html}Upgrading PMD at Runtime}} - - * {{{./examples/multi-module-config.html}Multimodule Configuration}} - - * {{{./examples/aggregate.html}Aggregating PMD reports for Multi-Module-Projects}} - - * {{{./examples/removeReport.html}Remove Report}} - - * {{{./examples/targetJdk.html}Target JDK and Toolchains}} - - * {{{./examples/usingRuleSets.html}Using Rule Sets}} - - * {{{./examples/violationChecking.html}Violation Checking}} - - * {{{./examples/javascriptReport.html}Analyzing JavaScript Code}} - - * {{{./examples/jspReport.html}Analyzing Java Server Pages Code}} - - * {{{./examples/cpdCsharp.html}Finding duplicated code in C#}} - - * {{{./examples/differentRulesetForTests.html}Different ruleset for tests}} - - [] diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm deleted file mode 100644 index 99014e7d..00000000 --- a/src/site/apt/usage.apt.vm +++ /dev/null @@ -1,130 +0,0 @@ - ------ - Usage - ------ - Maria Odea Ching - ------ - 2017-11-11 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -Usage - - The PMD plugin generates PMD and CPD reports using the PMD code analysis tool. - - To include a report with default rule sets and configuration in your project site, set the following in the - <<<\>>> section of your POM: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - - ... - -+-----+ - - You can also explicitly execute the PMD plugin and generate the same report by setting the plugin in the - <<<\>>> section of your POM as shown below: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - - - ... - -+-----+ - - -Configuration - - The PMD and CPD reports share the same configuration. For example, the following tells Maven to run the PMD - and CPD report as part of the site report generation. - - The reports will link directly to the cross-referenced source if you enable this with the <<>> parameter. - See the {{{http://maven.apache.org/plugins/maven-jxr-plugin/}JXR plugin}} for more details. - - If your source uses a non-default encoding, you can use the <<>> parameter to tell Maven which - encoding to use when reading the java source. Note also the ability to exclude source which you want - to ignore. - - You can configure the minimum code size which trips the CPD. The default of <<<100>>> tokens corresponds - to approximately 5-10 lines of code. - - Since PMD parses the Java source, it needs to know which Java version to use. - The following is a possible configuration: - -+-----+ - - ... - - - - org.apache.maven.plugins - maven-pmd-plugin - ${project.version} - - true - utf-8 - 100 - 1.5 - - **/*Bean.java - **/generated/*.java - - - target/generated-sources/stubs - - - - - - pmd - cpd - - - - aggregate - false - - aggregate-pmd - aggregate-cpd - - - - - - - ... - -+-----+ diff --git a/src/site/markdown/examples/aggregate.md.vm b/src/site/markdown/examples/aggregate.md.vm new file mode 100644 index 00000000..5d15491a --- /dev/null +++ b/src/site/markdown/examples/aggregate.md.vm @@ -0,0 +1,196 @@ + + +# Aggregating PMD reports for Multi-Module-Projects + +For example, consider the following directory structure: + +```unknown + +Project + |-- pom.xml + |-- Module1 + | `-- pom.xml + | `-- Module 2 + | `-- pom.xml + | `-- Module 3 + | `-- pom.xml + |-- Module4 + | `-- pom.xml + `-- Module5 + `-- pom.xml +``` + +Since 3.15.0 the `aggregate` has changed a little bit. It'll generate aggregated reports at every level. To get only an aggregated project at root level, you need to configure the pom like: + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + aggregate + false + + aggregate-pmd + aggregate-cpd + + + + default + + pmd + cpd + + + + + + ... + + ... + +``` + +Using The `aggregate` Goals +--------------------------- + +The [<aggregate/>](../pmd-mojo.html#aggregate) parameter doesn't make sure, that the project is compiled before executing PMD which might lead to wrong results. Therefore the report goals `aggregate-pmd` and `aggregate-cpd` have been introduced. You could define these goals in the <build/> element (using the <execution/> tag) or <reporting/> element (using the <reportSet/> tag) as shown below. + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + ... + + + + aggregate + + aggregate-pmd + aggregate-cpd + + site + + + ... + + + ... + + + ... + + + ... + +``` + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + ... + + + + non-aggregate + + + ... + + + pmd + cpd + + + + aggregate + + + ... + + + aggregate-pmd + aggregate-cpd + + + ... + + + ... + + + ... + +``` + +Generate aggregate PMD without duplicate execution of phase test-compile +------------------------------------------------------------------------ + +- The standard goal `aggregate-pmd` invokes separate lifecyle `test-compile`. +- In a CI environment you now might execute something like `mvn clean deploy site site-deploy`. +- During `site` build the standard reports will trigger `test-compile` again, depending on your build this may take some time, because stuff like `enforcer` or generating stubs from a WDSL will be invoked again, which may lead to longer build times. +- As of version 3.15.0 a new report is defined, `aggregate-pmd-no-fork` which will not trigger above phases a second time. +- Note: This is only a problem for PMD report. CPD does not invoke a separate lifecycle. +- Configure this in your `reporting` section as follows: + + ```xml + + ... + + true + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + + aggregate-pmd-no-fork + aggregate-cpd + + + + + + + ... + + ``` diff --git a/src/site/markdown/examples/cpdCsharp.md.vm b/src/site/markdown/examples/cpdCsharp.md.vm new file mode 100644 index 00000000..077bae0e --- /dev/null +++ b/src/site/markdown/examples/cpdCsharp.md.vm @@ -0,0 +1,72 @@ + + +# Finding duplicated code in C\# + +By default, the maven-pmd-plugin only supports the languages Java, JavaScript and JSP. But [CPD supports many more languages](https://pmd.github.io/latest/pmd_userdocs_cpd.html#supported-languages), e.g. C#. In order to enable C# in your build, you need to configure several parts: + +- Add an additional plugin dependency for c# (pmd-cs module) +- Select the language `cs`. +- Configure the includes filter to consider `*.cs` (otherwise only java files will be analyzed) +- Configure the source directory (by default, only `src/main/java` is analyzed) + + ```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + cs + 10 + + **/*.cs + + + ${basedir}/src/main/cs + + true + + + + + cpd-check + + + + + + net.sourceforge.pmd + pmd-cs + ${pmdVersion} + + + + ... + + + + ``` + + In this example, the C# source files are located in `src/main/cs`. + + **Note:** The version for `net.sourceforge.pmd:pmd-cs` needs to match the PMD version. If you [upgrade PMD at runtime](./upgrading-PMD-at-runtime.html), you need to change the version here as well. diff --git a/src/site/markdown/examples/differentRulesetForTests.md.vm b/src/site/markdown/examples/differentRulesetForTests.md.vm new file mode 100644 index 00000000..222941e4 --- /dev/null +++ b/src/site/markdown/examples/differentRulesetForTests.md.vm @@ -0,0 +1,89 @@ + + +# Using a different ruleset for tests + +PMD shall be configured to scan test source code with a less strict ruleset than production code. This can be achieved by configuring multiple plugin [executions](https://maven.apache.org/guides/mini/guide-configuring-plugins.html#Using_the_executions_Tag) with different configurations. + +**Note:** There are different opinions whether one should lower that quality just because it's "just test code". While test code doesn't run in production, it's used to test production code, so you might consider the test code then as your weakest link if you use less strict checks. + +Here's the complete plugin configuration for this scenario: + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + false + + config/pmd/pmdMain.xml + + false + + + + pmd-main + verify + + check + + + + pmd-test + verify + + pmd + check + + + ${esc.d}{project.build.directory}/pmdTest/ + true + + ${basedir}/src/main/java + + + config/pmd/pmdTest.xml + + + + + cpd + verify + + cpd-check + + + + + ... + + + +``` + +It uses the ruleset `config/pmd/pmdMain.xml` for the main code without tests. This is configured directly at the plugin level. The ruleset `config/pmd/pmdTest.xml` is used for the test code only. This is configured in the execution with id `pmd-test`. + +This solution has one downside though: PMD is run three times: Twice for the main code, and once for the test code. The reason is that "pmd:check" triggers automatically "pmd:pmd", but it uses only the standard configuration (e.g. it ignores the lifecycle/execution id). + +The execution `pmd-test` calls once "pmd:pmd" for the test code (which creates `target/pmdTest/pmd.xml`), then calls "pmd:check" - which itself calls "pmd:pmd" and uses the default configuration - and finally runs "pmd:check" actually, which uses the execution configuration and uses `target/pmdTest/pmd.xml` to decide whether to fail the build. diff --git a/src/site/markdown/examples/javascriptReport.md.vm b/src/site/markdown/examples/javascriptReport.md.vm new file mode 100644 index 00000000..a93408fe --- /dev/null +++ b/src/site/markdown/examples/javascriptReport.md.vm @@ -0,0 +1,67 @@ + + +# Analyzing JavaScript Code + +The PMD plugin analyzes Java by default. You can configure it to analyze JavaScript files instead as shown below. + +The example assumes that the JavaScript source code is stored in the subdirectory `src/main/javascript` and enables all rules from the "Best Practices", "Codestyle", and "Error Prone" categories. + +Note that you have to make sure that you configure `compileSourceRoots` and `includes`, so that PMD finds the JavaScript files. + +See [JavaScript Rule Index](https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_ecmascript.html) for the list of available rules. + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + javascript + + /category/ecmascript/bestpractices.xml + /category/ecmascript/codestyle.xml + /category/ecmascript/errorprone.xml + + + **/*.js + + + ${basedir}/src/main/javascript + + + + + + pmd + + + + + + + ... + +``` + +**Note:** Configuring `compileSourceRoots` only works with Maven 3.3.9 and later. For older versions, you'll need to use _build-helper-maven-plugin_ with the `add-source` goal in order to add the additional source directories, so that PMD finds the JavaScript files. diff --git a/src/site/markdown/examples/jspReport.md.vm b/src/site/markdown/examples/jspReport.md.vm new file mode 100644 index 00000000..428f2b91 --- /dev/null +++ b/src/site/markdown/examples/jspReport.md.vm @@ -0,0 +1,69 @@ + + +# Analyzing JSP Code + +The PMD plugin analyzes Java by default. You can configure it to analyze Java Server Pages files instead as shown below. + +The example assumes that the JSP source code is stored in various subdirectories under the source directory `src/main/webapp` and enables all rules from the categories "Best Practices", "Codestyle", "Design", "Error Prone" and "Security". + +Note that you have to make sure that you configure `compileSourceRoots` and `includes`, so that PMD finds the JSP files. + +See [JSP Rule Index](https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_jsp.html) for a complete list of available rules. + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + jsp + + /category/jsp/bestpractices.xml + /category/jsp/codestyle.xml + /category/jsp/design.xml + /category/jsp/errorprone.xml + /category/jsp/security.xml + + + **/*.jsp + + + ${basedir}/src/main/webapp + + + + + + pmd + + + + + + + ... + +``` + +**Note:** Configuring `compileSourceRoots` only works with Maven 3.3.9 and later. For older versions, you'll need to use _build-helper-maven-plugin_ with the `add-source` goal in order to add the additional source directories, so that PMD finds the JSP files. diff --git a/src/site/apt/examples/multi-module-config.apt.vm b/src/site/markdown/examples/multi-module-config.md.vm similarity index 50% rename from src/site/apt/examples/multi-module-config.apt.vm rename to src/site/markdown/examples/multi-module-config.md.vm index 19e933c0..06166345 100644 --- a/src/site/apt/examples/multi-module-config.apt.vm +++ b/src/site/markdown/examples/multi-module-config.md.vm @@ -1,42 +1,31 @@ - ------ - Multimodule Configuration - ------ - ------ - 2017-11-11 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Multimodule Configuration - - If you have a multimodule project with many modules and you want to share the PMD ruleset configuration, - so that each module uses the same PMD rules, this is possible, but requires a little setup. - - The setup is very similar to the one described for Checkstyle, see - {{{https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html}Multimodule Configuration for Checkstyle}}. - - This example will use the same mysterious project called . This is what - the structure of that project looks like: - -+-----+ + + +# Multimodule Configuration + +If you have a multimodule project with many modules and you want to share the PMD ruleset configuration, so that each module uses the same PMD rules, this is possible, but requires a little setup. + +The setup is very similar to the one described for Checkstyle, see [Multimodule Configuration for Checkstyle](https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html). + +This example will use the same mysterious project called _whizbang_. This is what the structure of that project looks like: + +```unknown whizbang |-- pom.xml |-- core @@ -46,17 +35,14 @@ whizbang |-- jmx | `-- pom.xml `-- src -+-----+ +``` -* Create a subproject for the PMD rulesets +Create a subproject for the PMD rulesets +---------------------------------------- - We'll start by adding another sub project that will house our common - configuration for PMD. Let's call it . - In it we put the resources that we want to share between our whizbang modules. - In this example, we will add our custom PMD ruleset to be used by the PMD Plugin. - The same subproject can be used to house shared configurations for Checkstyle. +We'll start by adding another sub project that will house our common configuration for PMD. Let's call it _build-tools_. In it we put the resources that we want to share between our whizbang modules. In this example, we will add our custom PMD ruleset to be used by the PMD Plugin. The same subproject can be used to house shared configurations for Checkstyle. -+-----+ +```unknown whizbang |-- pom.xml |-- build-tools @@ -70,14 +56,13 @@ whizbang |-- gui |-- jmx `-- src -+-----+ +``` - <> put the resources into a subdirectory that you can ensure will be - unique and not conflict with anyone else. +**Tip:** put the resources into a subdirectory that you can ensure will be unique and not conflict with anyone else. - The <<>> file for should look like this: +The `pom.xml` file for _build-tools_ should look like this: -+-----+ +```xml 4.0.0 com.example.whizbang @@ -85,11 +70,11 @@ whizbang 1.0 Build Tools -+-----+ +``` - A sample <<>> could look like this: +A sample `pmd-ruleset.xml` could look like this: -+-----+ +```xml -+-----+ +``` - The ruleset references some built-in rules. For more information about rulesets, see - {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_userdocs_making_rulesets.html}Making Rulesets}} - and {{{./usingRuleSets.html}Using Rule Sets}}. +The ruleset references some built-in rules. For more information about rulesets, see [Making Rulesets](https://pmd.github.io/pmd-${pmdVersion}/pmd_userdocs_making_rulesets.html) and [Using Rule Sets](./usingRuleSets.html). -* Configure the other projects to use it +Configure the other projects to use it +-------------------------------------- - Now we can include the PMD configuration in the top level - <<>>. +Now we can include the PMD configuration in the top level `pom.xml`. - <> You have to specify a plugin dependency on <<>> in the - <<<\>>> element of your <<>>. It will not work inside the - <<<\>>> element, because <<<\>>> does not support - plugin dependencies. The rest of the configuration is done in the normal way - in the <<<\>>> element. +**Note:** You have to specify a plugin dependency on `build-tools` in the `` element of your `pom.xml`. It will not work inside the `` element, because `` does not support plugin dependencies. The rest of the configuration is done in the normal way in the `` element. -+-----+ +```xml 4.0.0 com.example.whizbang @@ -199,27 +178,22 @@ whizbang gui -+-----+ +``` - Once you are done with that, ensure that you do not include - the Maven PMD Plugin in your sub modules, as their definition and - configuration, will override the top level parent pom's definition. +Once you are done with that, ensure that you do not include the Maven PMD Plugin in your sub modules, as their definition and configuration, will override the top level parent pom's definition. - Based on the PMD Plugin configuration above, the values of - <<>> will be resolved from the classpath. - The JAR was included in the classpath when it was - declared as a dependency to the plugin. +Based on the PMD Plugin configuration above, the values of `rulesets` will be resolved from the classpath. The _build-tools_ JAR was included in the classpath when it was declared as a dependency to the plugin. - Lastly, kick off a build of the site. +Lastly, kick off a build of the site. -+-----+ +```shell mvn site -+-----+ +``` - Or run the check goal of the PMD plugin via verify: +Or run the check goal of the PMD plugin via verify: -+-----+ +```shell mvn verify -+-----+ +``` - Every sub project will now use the same PMD setup and configuration. +Every sub project will now use the same PMD setup and configuration. diff --git a/src/site/markdown/examples/removeReport.md.vm b/src/site/markdown/examples/removeReport.md.vm new file mode 100644 index 00000000..873dc43a --- /dev/null +++ b/src/site/markdown/examples/removeReport.md.vm @@ -0,0 +1,48 @@ + + +# Remove Report + +You may want to generate only one of the reports, but not the other. Since version 3.15.0 separate aggregate reports have been added, which would duplicate the reports. To select only the reports you want you can use the `` feature within your POM. Below is the default configuration for the plugin. To disable one of the reports, just copy the `` element below to your POM and remove the `` you don't want to generate. + +```xml + + ... + + + + maven-pmd-plugin + ${project.version} + + + + pmd + cpd + aggregate-pmd + aggregate-pmd-no-fork + aggregate-cpd + + + + + + + ... + +``` diff --git a/src/site/markdown/examples/targetJdk.md.vm b/src/site/markdown/examples/targetJdk.md.vm new file mode 100644 index 00000000..2e4a8bdf --- /dev/null +++ b/src/site/markdown/examples/targetJdk.md.vm @@ -0,0 +1,48 @@ + + +# Target JDK + +There is a configuration element in the PMD plugin that lets you set which [target JDK](../pmd-mojo.html#targetJdk) your Java code will be compiled for. Often you want this to be in sync with the configuration for maven-compiler-plugin. The best practice for this is to set up the wellknown property `maven.compiler.target` and the rest will work automatically. Alternatively, you can set it manually: + +```xml + + ... + + + + maven-pmd-plugin + ${project.version} + + 1.6 + + + + + ... + +``` + +# Using Maven Toolchains + +Since version 3.14.0 of the PMD plugin, toolchains are supported. This helps if the build system is running a different JDK than being used for compiling. PMD reads the class files for [type resolution](../pmd-mojo.html#typeResolution) and this fails with ClassFormatErrors if the JDK version is incorrect. + +To set this up, refer to the [Guide to Using Toolchains](/guides/mini/guide-using-toolchains.html), which makes use of the [Maven Toolchains Plugin](/plugins/maven-toolchains-plugin/). + +With the maven-toolchains-plugin you configure 1 default JDK toolchain for all related maven-plugins. Since maven-pmd-plugin 3.14.0 when using with Maven 3.3.1+ it is also possible to give the plugin its own toolchain, which can be useful in case of different JDK calls per execution block (e.g. the test sources require a different JDK compared to the main sources). diff --git a/src/site/markdown/examples/upgrading-PMD-at-runtime.md.vm b/src/site/markdown/examples/upgrading-PMD-at-runtime.md.vm new file mode 100644 index 00000000..71137983 --- /dev/null +++ b/src/site/markdown/examples/upgrading-PMD-at-runtime.md.vm @@ -0,0 +1,99 @@ + + +# Upgrading PMD at Runtime + +The Maven PMD plugin comes with a default PMD version: for `maven-pmd-plugin ${project.version}`, **PMD ${pmdVersion}** is used by default. + +Given that the [newer PMD version](https://pmd.github.io) is compatible, you can override the PMD version, that the Maven plugin will use and benefit from the latest bugfixes and enhancements: + +```xml + + + ...choose your version... + +... + + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + net.sourceforge.pmd + pmd-core + ${esc.d}{pmdVersion} + + + net.sourceforge.pmd + pmd-java + ${esc.d}{pmdVersion} + + + net.sourceforge.pmd + pmd-javascript + ${esc.d}{pmdVersion} + + + net.sourceforge.pmd + pmd-jsp + ${esc.d}{pmdVersion} + + + + + + +... + +``` + +Version relationship between maven-pmd-plugin and PMD +----------------------------------------------------- + +Every maven-pmd-plugin version ships with a default PMD version. The default PMD version is upgraded irregularly, e.g. when support for a newer Java version is required. + +Here's a historical overview about the default PMD version used: + +|maven-pmd-plugin|PMD| +|:---:|:---:| +|[3.28.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.28.0/)|[7.17.0](https://docs.pmd-code.org/pmd-doc-7.17.0/)| +|[3.27.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.27.0/)|[7.14.0](https://docs.pmd-code.org/pmd-doc-7.14.0/)| +|[3.26.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.26.0/)|[7.7.0](https://docs.pmd-code.org/pmd-doc-7.7.0/)| +|[3.24.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.24.0/)|[7.3.0](https://docs.pmd-code.org/pmd-doc-7.3.0/)| +|[3.22.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.22.0/)|[7.0.0](https://docs.pmd-code.org/pmd-doc-7.0.0/)| +|[3.21.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.21.0/)|[6.55.0](https://pmd.github.io/pmd-6.55.0/)| +|[3.20.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.20.0/)|[6.53.0](https://pmd.github.io/pmd-6.53.0/)| +|[3.19.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.19.0/)|[6.49.0](https://pmd.github.io/pmd-6.49.0/)| +|[3.18.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.18.0/)|[6.48.0](https://pmd.github.io/pmd-6.48.0/)| +|[3.17.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.17.0/)|[6.46.0](https://pmd.github.io/pmd-6.46.0/)| +|[3.16.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.16.0/)|[6.42.0](https://pmd.github.io/pmd-6.42.0/)| +|[3.15.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.15.0/)|[6.38.0](https://pmd.github.io/pmd-6.38.0/)| +|[3.14.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.14.0/)|[6.29.0](https://pmd.github.io/pmd-6.29.0/)| +|[3.13.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.13.0/)|[6.21.0](https://pmd.github.io/pmd-6.21.0/)| +|[3.12.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.12.0/)|[6.13.0](https://pmd.github.io/pmd-6.13.0/)| +|[3.11.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.11.0/)|[6.8.0](https://pmd.sourceforge.io/pmd-6.8.0/)| +|[3.10.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.10.0/)|[6.4.0](https://pmd.sourceforge.io/pmd-6.4.0/)| +|[3.9.0](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.9.0/)|[6.0.1](https://pmd.sourceforge.io/pmd-6.0.1/)| +|[3.8](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.8/)|[5.6.1](https://pmd.sourceforge.io/pmd-5.6.1/)| +|[3.7](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.7/)|[5.5.1](https://pmd.sourceforge.io/pmd-5.5.1/)| +|[3.6](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.6/)|[5.3.5](https://pmd.sourceforge.io/pmd-5.3.5/)| +|[3.5](https://maven.apache.org/plugins-archives/maven-pmd-plugin-3.5/)|[5.3.2](https://pmd.sourceforge.io/pmd-5.3.2/)| diff --git a/src/site/apt/examples/usingRuleSets.apt.vm b/src/site/markdown/examples/usingRuleSets.md.vm similarity index 54% rename from src/site/apt/examples/usingRuleSets.apt.vm rename to src/site/markdown/examples/usingRuleSets.md.vm index 70f8adb6..ac95cbc5 100644 --- a/src/site/apt/examples/usingRuleSets.apt.vm +++ b/src/site/markdown/examples/usingRuleSets.md.vm @@ -1,63 +1,41 @@ - ------ - Using Rule Sets - ------ - Maria Odea Ching - ------ - 2018-01-10 - ------ - - ~~ Licensed to the Apache Software Foundation (ASF) under one - ~~ or more contributor license agreements. See the NOTICE file - ~~ distributed with this work for additional information - ~~ regarding copyright ownership. The ASF licenses this file - ~~ to you under the Apache License, Version 2.0 (the - ~~ "License"); you may not use this file except in compliance - ~~ with the License. You may obtain a copy of the License at - ~~ - ~~ http://www.apache.org/licenses/LICENSE-2.0 - ~~ - ~~ Unless required by applicable law or agreed to in writing, - ~~ software distributed under the License is distributed on an - ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - ~~ KIND, either express or implied. See the License for the - ~~ specific language governing permissions and limitations - ~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Using Rule Sets - - The PMD plugin ships a default rule set, that has various rules enabled. The ruleset is available - as . See below for the rules, that are enabled with - the default rule set. - - There are many more rules available and bundled in the PMD code analysis tool: - - * {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_java.html}Java Rule Index}} - - * {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_ecmascript.html}JavaScript Rule Index}} - - * {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_jsp.html}JSP Rule Index}} - - To use other rule sets, you can configure it in the plugin as shown below. - The rule sets may reside in the classpath, filesystem or at a URL. For rule sets that are bundled - with the PMD tool, you do not need to specify the absolute path of the file. It will be resolved by - the plugin. But if the rule set is a custom rule set, you need to specify its absolute path. - - See {{{https://pmd.github.io/pmd-${pmdVersion}/pmd_userdocs_making_rulesets.html}Making Rulesets}} - if you want to create your own custom ruleset. - - <> Starting with PMD 5.0 and Maven PMD Plugin 3.0 the paths to the - bundled rule sets for the Java language were changed from - <<>> to <<>>. So when upgrading to - Maven PMD Plugin 3.0 you may need to alter your plugin configuration. - - <> Starting with PMD 6.0.0 and Maven PMD Plugin 3.9.0, the rules have been reorganized - into categories, e.g. <<>>. So when upgrading to - Maven PMD Plugin 3.9.0 you should review your plugin configuration and/or custom ruleset. - -+-----+ + + +# Using Rule Sets + +The PMD plugin ships a default rule set, that has various rules enabled. The ruleset is available as _/rulesets/java/maven-pmd-plugin-default.xml_. See below for the rules, that are enabled with the default rule set. + +There are many more rules available and bundled in the PMD code analysis tool: + +- [Java Rule Index](https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_java.html) +- [JavaScript Rule Index](https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_ecmascript.html) +- [JSP Rule Index](https://pmd.github.io/pmd-${pmdVersion}/pmd_rules_jsp.html) + +To use other rule sets, you can configure it in the plugin as shown below. The rule sets may reside in the classpath, filesystem or at a URL. For rule sets that are bundled with the PMD tool, you do not need to specify the absolute path of the file. It will be resolved by the plugin. But if the rule set is a custom rule set, you need to specify its absolute path. + +See [Making Rulesets](https://pmd.github.io/pmd-${pmdVersion}/pmd_userdocs_making_rulesets.html) if you want to create your own custom ruleset. + +**Note:** Starting with PMD 5.0 and Maven PMD Plugin 3.0 the paths to the bundled rule sets for the Java language were changed from `/rulesets/xyz.xml` to `/rulesets/java/xyz.xml`. So when upgrading to Maven PMD Plugin 3.0 you may need to alter your plugin configuration. + +**Note:** Starting with PMD 6.0.0 and Maven PMD Plugin 3.9.0, the rules have been reorganized into categories, e.g. `/category/java/bestpractices.xml`. So when upgrading to Maven PMD Plugin 3.9.0 you should review your plugin configuration and/or custom ruleset. + +```xml ... @@ -81,19 +59,15 @@ Using Rule Sets ... -+-----+ - +``` -The default ruleset +# The default ruleset - This is an excerpt of the ruleset <<>>. - It contains only rules for Java. - If you use a different language, you'll need to specify your own custom ruleset. +This is an excerpt of the ruleset `/rulesets/java/maven-pmd-plugin-default.xml`. It contains only rules for Java. If you use a different language, you'll need to specify your own custom ruleset. - The current version of the ruleset can be found in version control: - {{https://gitbox.apache.org/repos/asf?p=maven-pmd-plugin.git;a=blob_plain;f=src/main/resources/rulesets/java/maven-pmd-plugin-default.xml;hb=HEAD}} +The current version of the ruleset can be found in version control: [https://gitbox.apache.org/repos/asf?p=maven-pmd-plugin.git;a=blob\_plain;f=src/main/resources/rulesets/java/maven-pmd-plugin-default.xml;hb=HEAD](https://gitbox.apache.org/repos/asf?p=maven-pmd-plugin.git;a=blob_plain;f=src/main/resources/rulesets/java/maven-pmd-plugin-default.xml;hb=HEAD) -+-----+ +```xml @@ -141,4 +115,4 @@ The default ruleset -+-----+ +``` diff --git a/src/site/markdown/examples/violation-exclusions.md.vm b/src/site/markdown/examples/violation-exclusions.md.vm new file mode 100644 index 00000000..a1f0c380 --- /dev/null +++ b/src/site/markdown/examples/violation-exclusions.md.vm @@ -0,0 +1,105 @@ + + +# Violation Exclusions + +It is possible to exclude some sources from PMD/CPD check to prevent failures. + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + + check + + + exclude-pmd.properties + + + + + cpd-check + + + exclude-cpd.properties + + + + + + + ... + +``` + +For cpd check, you can exclude classes to not verify. Classes can be specified in two ways: + +1. Comma-separated: org.apache.maven.ClassA and org.apache.maven.ClassB contain duplicated code across classes. +1. Single class per line: org.apache.maven.ClassC and org.apache.maven.ClassD do not share duplicate code, but have duplicated code internally. + +The properties file for cpd must have the following format: + +```unknown +org.apache.maven.ClassA,org.apache.maven.ClassB +org.apache.maven.ClassC +org.apache.maven.ClassD +``` + +For pmd check, you can exclude rules per classes. The properties file must have the following format: + +```properties +org.apache.maven.ClassA=UnusedPrivateField,EmptyCatchBlock +org.apache.maven.ClassB=UnusedPrivateField,UnusedFormalParameter,UnusedPrivateMethod +``` + +You can only exclude (checks for) classes through the exclusion files. If you want more flexibility and exclude classes with a certain name, or whole packages, for example because of generated code, you have to do this in the `` section of the plugin, using the `` or `` elements. To avoid confusion, don't write those to the plugin's configuration as a `` and `` plugin. Instead, configure the plugin in the `` section of your POM, so executions of the build and site lifecycle pick it up. + +```xml + + ... + + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + **/*Bean.java + **/generated/*.java + + + target/generated-sources/stubs + + + + + + + ... + +``` diff --git a/src/site/markdown/examples/violationChecking.md.vm b/src/site/markdown/examples/violationChecking.md.vm new file mode 100644 index 00000000..43e37325 --- /dev/null +++ b/src/site/markdown/examples/violationChecking.md.vm @@ -0,0 +1,50 @@ + + +# Violation Checking + +The `pmd:check` and `pmd:cpd-check` goals allow you to configure your build to fail if any errors are found in the PMD or CPD reports respectively. In doing so you can enforce your own custom code quality rules. + +The rule violations may optionally be displayed on the build output using the `verbose` setting. + +The following code fragment enables both the standard PMD check and the CPD check in a build, during the `verify` phase. + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + + check + cpd-check + + + + + + + ... + +``` diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm new file mode 100644 index 00000000..872eaf32 --- /dev/null +++ b/src/site/markdown/index.md.vm @@ -0,0 +1,79 @@ + + +# ${project.name} + +The PMD Plugin allows you to automatically run the [PMD](https://pmd.github.io/) code analysis tool on your project's source code and generate a site report with its results. It also supports the separate Copy/Paste Detector tool (or CPD) distributed with PMD. + +This version of Maven PMD Plugin uses PMD ${pmdVersion} and requires Java ${javaVersion}. See [Upgrading PMD at Runtime](./examples/upgrading-PMD-at-runtime.html) for more information. + +The plugin accepts configuration parameters that can be used to customize the execution of the PMD tool. + +Goals Overview +-------------- + +This plugin has the following goals: + +- [pmd:pmd](./pmd-mojo.html) creates a PMD site report based on the rulesets and configuration set in the plugin. It can also generate a pmd output file aside from the site report in any of the following formats: xml, csv or txt. +- [pmd:aggregate-pmd](./aggregate-pmd-mojo.html) creates a PMD site report in an **aggregator** project based on the rulesets and configuration set in the plugin. It can also generate a pmd output file aside from the site report in any of the following formats: xml, csv or txt. +- [pmd:aggregate-pmd-no-fork](./aggregate-pmd-no-fork-mojo.html) creates a PMD site report in an **aggregator** project without forking the `test-compile` phase again. +- [pmd:cpd](./cpd-mojo.html) 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. +- [pmd:aggregate-cpd](./aggregate-cpd-mojo) creates a report for PMD's Copy/Paste Detector (CPD) tool in an **aggregator** project. It can also generate a cpd results file in any of these formats: xml, csv or txt. +- [pmd:check](./check-mojo.html) fails the build if there were any PMD violations in the source code. This goal invokes automatically `pmd:pmd` prior to executing itself. +- [pmd:aggregate-pmd-check](./aggregate-pmd-check-mojo.html) fails the build in an **aggregator** project if there were any PMD violations in the source code. This goal invokes automatically `pmd:aggregate-pmd` prior to executing itself. +- [pmd:cpd-check](./cpd-check-mojo.html) fails the build if there were any CPD violations in the source code. This goal invokes automatically `pmd:cpd` prior to executing itself. +- [pmd:aggregate-cpd-check](./aggregate-cpd-check-mojo.html) fails the build in an **aggregator** project if there were any CPD violations in the source code. This goal invokes automatically `pmd:aggregate-cpd` prior to executing itself. + +Usage +----- + +General instructions on how to use the PMD Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. + +In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). + +If you feel like the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html). + +Upgrading Notes +--------------- + +#[[### 3.22.0]]# + +- Starting with Maven PMD Plugin 3.22.0, the plugin requires PMD version 7.0.0 or higher. PMD 7.0.0 switched to SLF4J and since Maven 3.1.0+ SLF4J is the default logging API. Logs from PMD are now always shown and cannot be disabled at runtime after maven has started. The property `showPmdLog` makes no sense anymore and is deprecated now. See [Maven Logging](https://maven.apache.org/maven-logging.html) for how to configure logging. For disabling PMD logs, you'd need to start maven with `MAVEN_OPTS=-Dorg.slf4j.simpleLogger.log.net.sourceforge.pmd=off mvn `. +- The upgrade from PMD 6 to PMD 7.0.0 is a major version change. If you use the default ruleset from Maven PMD Plugin, then everything should just work. But if you use a custom ruleset, you most likely need to review your ruleset and migrate it to PMD 7. Rules might have been renamed or replaced. See [Detailed Release Notes for PMD 7](https://docs.pmd-code.org/latest/pmd_release_notes_pmd7.html) and [Migration Guide for PMD 7](https://docs.pmd-code.org/latest/pmd_userdocs_migrating_to_pmd7.html). +- If you currently override the dependency to PMD ([Upgrading PMD at Runtime](./examples/upgrading-PMD-at-runtime.html)) make sure to upgrade PMD as well to 7.0.0 or later when upgrading the Maven PMD Plugin. +#[[### 3.9.0]]# + +- Starting with PMD 6.0.0 and Maven PMD Plugin 3.9.0, the rules have been reorganized into categories, e.g. `/category/java/bestpractices.xml`. So when upgrading to Maven PMD Plugin 3.9.0 you should review your plugin configuration and/or custom ruleset. See [Using Rule Sets](./examples/usingRuleSets.html) for more information. + +Examples +-------- + +To provide you with better understanding of some usages of the Maven PMD Plugin, you can take a look into the following examples: + +- [Upgrading PMD at Runtime](./examples/upgrading-PMD-at-runtime.html) +- [Multimodule Configuration](./examples/multi-module-config.html) +- [Aggregating PMD reports for Multi-Module-Projects](./examples/aggregate.html) +- [Remove Report](./examples/removeReport.html) +- [Target JDK and Toolchains](./examples/targetJdk.html) +- [Using Rule Sets](./examples/usingRuleSets.html) +- [Violation Checking](./examples/violationChecking.html) +- [Analyzing JavaScript Code](./examples/javascriptReport.html) +- [Analyzing Java Server Pages Code](./examples/jspReport.html) +- [Finding duplicated code in C#](./examples/cpdCsharp.html) +- [Different ruleset for tests](./examples/differentRulesetForTests.html) diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm new file mode 100644 index 00000000..3c1ec018 --- /dev/null +++ b/src/site/markdown/usage.md.vm @@ -0,0 +1,115 @@ + + +# Usage + +The PMD plugin generates PMD and CPD reports using the PMD code analysis tool. + +To include a report with default rule sets and configuration in your project site, set the following in the `` section of your POM: + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + + ... + +``` + +You can also explicitly execute the PMD plugin and generate the same report by setting the plugin in the `` section of your POM as shown below: + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + + + ... + +``` + +# Configuration + +The PMD and CPD reports share the same configuration. For example, the following tells Maven to run the PMD and CPD report as part of the site report generation. + +The reports will link directly to the cross-referenced source if you enable this with the `linkXRef` parameter. See the [JXR plugin](http://maven.apache.org/plugins/maven-jxr-plugin/) for more details. + +If your source uses a non-default encoding, you can use the `inputEncoding` parameter to tell Maven which encoding to use when reading the java source. Note also the ability to exclude source which you want to ignore. + +You can configure the minimum code size which trips the CPD. The default of `100` tokens corresponds to approximately 5-10 lines of code. + +Since PMD parses the Java source, it needs to know which Java version to use. The following is a possible configuration: + +```xml + + ... + + + + org.apache.maven.plugins + maven-pmd-plugin + ${project.version} + + true + utf-8 + 100 + 1.5 + + **/*Bean.java + **/generated/*.java + + + target/generated-sources/stubs + + + + + + pmd + cpd + + + + aggregate + false + + aggregate-pmd + aggregate-cpd + + + + + + + ... + +```