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

Merge Understanding rulesets into Making rulesets

Browse Source
This commit is contained in:
Clément Fournier
2018-05-21 05:49:02 +02:00
parent 891df94c49
commit 04b0859fb2
4 changed files with 102 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/_data/sidebars/pmd_sidebar.yml
View File

@ -18,7 +18,7 @@ entries:
- title: About
output: web, pdf
folderitems:
- title: Introduction
- title: Home
url: /index.html
output: web, pdf
type: homepage
@ -34,9 +34,6 @@ entries:
- title: Installation and basic CLI usage
url: /pmd_userdocs_installation.html
output: web, pdf
- title: Understanding rulesets
url: /pmd_userdocs_understanding_rulesets.html
output: web, pdf
- title: Making rulesets
url: /pmd_userdocs_making_rulesets.html
output: web, pdf

42
docs/pages/pmd/userdocs/installation.md
View File

@ -35,24 +35,36 @@ Unzip it into any directory, optionally add the `bin` subdirectory in your `PATH
the arguments are specific to the utility used.<br/><br/>
On Windows, each utility has its own startup script, e.g. `pmd.bat`, `cpd.bat`." %}
The PMD command (`pmd.bat` or `run.sh pmd`) requires three options:
The PMD command (`pmd.bat` or `run.sh pmd`) requires two options:
* `-d <path>`: path to the sources to analyse. This can be a file name, a directory or a jar or zip file containing the
* `-d <path>`: path to the sources to analyse. This can be a file name, a directory, or a jar or zip file containing the
sources.
* `-f <format>`: report format. PMD supports many report formats out of the box, you may want to start with the basic
`text`
format or `xml` format.
* `-R <path>`: the ruleset file you want to use. PMD uses xml configuration files, called *rulesets*, which specify
which rules to check for in your sources. PMD provides standard rulesets for each language it supports, grouping the
rules by theme. Instead of a path, you can reference those standard rulesets with the lightweight syntax
`rulesets/<lang>/<name.xml>`, e .g. `rulesets/java/codesize.xml`.
which rules to execute on your sources. You can also run a single rule by referencing it using its *category* and
name (more details [here](pmd_userdocs_making_rulesets.html#referencing-rules)). For example, you can check for unnecessary
modifiers on Java sources with `-R category/java/codestyle.xml/UnnecessaryModifier`.
{% include note.html
content="At the moment most of the formerly provided rulesets are deprecated, though you can still use them. PMD
will soon propose updated rulesets to use as default configurations." %}
content="At the moment the formerly provided rulesets (eg `rulesets/java/basic.xml`) are deprecated,
though you can still use them. PMD will soon include standard rulesets as default configurations,
but you're strongly encouraged to [create your own ruleset](pmd_userdocs_making_rulesets.html) from
the start." %}
Additionnally, the following options, are specified most of the time even though they're not required:
* `-f <format>`: report format. PMD supports many report formats out of the box, you may want to start with the basic
`text` format or `xml` format.
* `-auxclasspath <classpath>`: class path containing the compiled class files of the analysed Java sources, if any.
Setting this up correctly allows PMD to do much deeper analysis using reflection. Some rules, such as [MissingOverride](http://localhost:4005/pmd_rules_java_bestpractices.html#missingoverride),
require it to function properly.
{%include tip.html content="A full CLI reference, including report formats, is available under [PMD CLI Reference](pmd_userdocs_cli_reference.html)" %}
Sample usage with the `text` format:
### Sample usage
The following shows a sample run of with the `text` format:
<div class="text-left">
<ul class="nav nav-tabs" role="tablist">
@ -82,13 +94,7 @@ Sample usage with the `text` format:
.../src/main/java/com/me/RuleSetWriter.java:66 Avoid empty catch blocks</code></pre></figure>
</div>
</div>
</div>
Also, the PMD binary distribution includes the ruleset files
inside the jar file - even though the "rulesets/java/unusedcode.xml" parameter
above looks like a filesystem reference, it's really being used by a getResourceAsStream() call
to load it out of the PMD jar file.
</div>
## Running CPD via command line

175
docs/pages/pmd/userdocs/making_rulesets.md
View File

@ -1,97 +1,96 @@
---
title: PMD Making Rulesets
tags: [customizing, rulesets]
title: Making rulesets
keywords: [rulesets, reference, rule, exclude, include, pattern, filter]
tags: [customizing, essentials, userdocs]
summary: Making Custom Rulesets for PMD
last_updated: November 2017
summary: "A ruleset is an XML configuration file, which describes a collection of rules to be executed
in a PMD run. PMD includes built-in rulesets to run quick analyses with a default configuration, but
users are encouraged to make their own rulesets from the start, because they allow for so much
configurability. This page walk you through the creation of a ruleset and the multiple configuration
features offered by rulesets."
last_updated: May 2018 (6.4.0)
permalink: pmd_userdocs_making_rulesets.html
author: Tom Copeland <tomcopeland@users.sourceforge.net>
author: Tom Copeland <tomcopeland@users.sourceforge.net>, Clément Fournier <clement.fournier76@gmail.com>
---
# How to make a new rule set
## Creating a ruleset
Say you want to pick specific rules from various rule sets and customize them. You can do this by making your own rule set.
The first step is to create a new empty ruleset. You can use the following template:
## Create a new ruleset.xml file
Use one of the current rulesets as an example. Copy and paste it into your new file, delete all the old rules from it, and change the name and description. Like this:
```xml
``` xml
<?xml version="1.0"?>
<ruleset name="Custom ruleset"
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
<description>
This ruleset checks my code for bad stuff
</description>
</ruleset>
````
## Add some rule references to it
After you add these references it’ll look something like this:
```xml
<?xml version="1.0"?>
<ruleset name="Custom ruleset"
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
<description>
This ruleset checks my code for bad stuff
</description>
<!-- Here's some rules we'll specify one at a time -->
<rule ref="category/java/bestpractices.xml/UnusedLocalVariable"/>
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
<rule ref="category/java/codestyle.xml/DuplicateImports"/>
<rule ref="category/java/errorprone.xml/UnnecessaryConversionTemporary"/>
<!-- We want to customize this rule a bit, change the message and raise the priority -->
<rule ref="category/java/errorprone.xml/EmptyCatchBlock"
message="Must handle exceptions">
<priority>2</priority>
</rule>
<!-- Now we'll customize a rule's property value -->
<rule ref="category/java/design.xml/CyclomaticComplexity">
<properties>
<property name="classReportLevel" value="40"/>
<property name="methodReportLevel" value="5"/>
</properties>
</rule>
<!-- We want everything from category Code Style except WhileLoopsMustUseBraces -->
<rule ref="category/java/codestyle.xml">
<exclude name="WhileLoopsMustUseBraces"/>
</rule>
</ruleset>
```
>Notice that you can customize individual referenced rules. Everything but the class of the rule can be overridden in your custom ruleset.
## Excluding rules from a ruleset
You can also make a custom ruleset by referencing a complete category and exclude certain rules, like this:
```xml
<?xml version="1.0"?>
<ruleset name="myruleset"
<ruleset name="Custom Rules"
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
<description>All codestyle rules, but with just the braces rules I like</description>
<description>
My custom rules
</description>
<!-- Your rules will come here -->
</ruleset>
```
### Referencing a single rule
<!-- TODO this could be better explained, eg first explain how a ruleset reference works, then rule reference, then go on showing single rule & bulk addition, then include/exclude patterns -->
To use the built-in rules PMD provides, you need to add some *references* to them. Here's a
basic rule reference:
```xml
<rule ref="category/java/errorprone.xml/EmptyCatchBlock" />
```
Adding that element into the `ruleset` element adds the rule [EmptyCatchBlock](pmd_rules_java_errorprone.html#emptycatchblock)
to your ruleset. This is a Java rule, so it will be executed on every Java file PMD encounters in
its search space.
How to read the `ref` attribute?
* `category/java/errorprone.xml` is a reference to the Java category `errorprone`. Since PMD 6.0.0,
all PMD built-in rules are sorted in one of eight categories, which are consistent across languages:
1. **Best Practices**: These are rules which enforce generally accepted best practices.<br/>
2. **Code Style**: These rules enforce a specific coding style.<br/>
3. **Design**: Rules that help you discover design issues.<br/>
4. **Documentation**: These rules are related to code documentation.<br/>
5. **Error Prone**: Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors.<br/>
6. **Multithreading**: These are rules that flag issues when dealing with multiple threads of execution.<br/>
7. **Performance**: Rules that flag suboptimal code.<br/>
8. **Security**: Rules that flag potential security flaws."
{% include tip.html content="You can discover the available rules by language and category [from this page](tag_rule_references.html)" %}
* `EmptyCatchBlock` is simply the name of the rule. If there were no rule with that name within the specified
category, then PMD would fail before starting the analysis.
#### [Configuring individual rules](pmd_userdocs_configuring_rules.html)
### Bulk-adding rules
You can also reference rules in bulk by referencing a complete category or ruleset, possibly excluding certain rules, like in the following:
```xml
<rule ref="category/java/codestyle.xml">
<exclude name="WhileLoopsMustUseBraces"/>
<exclude name="IfElseStmtsMustUseBraces"/>
</rule>
</ruleset>
```
## Excluding files from a ruleset
Here, the `ref` attribute references a whole category. You can also use a file system path or classpath relative path. In any case, the path must address an accessible ruleset XML file.
You can also exclude certain files from being processed by a ruleset using exclude patterns, with an optional overriding include pattern. A file will be excluded from processing when there is a matching exclude pattern, but no matching include pattern. Path separators in the source file path are normalized to be the ‘/’ character, so the same ruleset can be used on multiple platforms transparently. Additionally, this exclude/include technique works regardless of how PMD is used (e.g. command line, IDE, Ant), making it easier to keep application of your PMD rules consistent throughout your environment. Here is an example:
{% include note.html content="Path separators in the source file path are normalized to be the `/` character within PMD, so the same ruleset can be used on multiple platforms transparently." %}
### Filtering the processed files
You can exclude some files from being processed by a ruleset using **exclude patterns**, with an optional overridding **include pattern**. A file will be excluded from processing *when there is a matching exclude pattern, but no matching include pattern*. This exclude/include technique works regardless of how PMD is used (e.g. command line, IDE, Ant), making it easier to keep application of your PMD rules consistent throughout your environment. Here is an example:
```xml
<?xml version="1.0"?>
@ -100,32 +99,12 @@ You can also exclude certain files from being processed by a ruleset using exclu
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
<description>My ruleset</description>
<exclude-pattern>.*/some/package/.*</exclude-pattern>
<exclude-pattern>.*/some/other/package/FunkyClassNamePrefix.*</exclude-pattern>
<include-pattern>.*/some/package/ButNotThisClass.*</include-pattern>
<rule>...
<!-- Rules here ... -->
</ruleset>
```
## Reference it in your Ant task
You can specify the full path to your custom ruleset name alongside of the built-in PMD rulesets - like this:
```xml
<pmd rulesetfiles="/home/tom/data/pmd/pmd/rulesets/java/design.xml,rulesets/java/unusedcode.xml">
<formatter type="xml" toFile="foo.xml"/>
<fileset dir="/home/tom/data/pmd/pmd/src">
<include name="**/*.java"/>
</fileset>
</pmd>
```
## To see it in your IDE
You'll need to point the IDE plugin to the location of your custom ruleset.
## Send us feedback
If you have suggestions on clarifying this document, please post them to [the forum](http://sourceforge.net/p/pmd/discussion/188192). Thanks!
Finally, for many more details on building custom rulesets, pick up [PMD Applied](http://pmdapplied.com/)!

77
docs/pages/pmd/userdocs/understanding_rulesets.md
View File

@ -1,77 +0,0 @@
---
title: Understanding Rulesets
tags: [essentials, userdocs]
permalink: pmd_userdocs_understanding_rulesets.html
summary: "Learn how to specify which rules you want to run, and how, by creating your own rulesets."
last_updated: May 2018 (6.4.0)
---
## What's a ruleset?
A *ruleset* is a configuration file, which describes a collection of PMD *rules* to be executed
in a PMD run. PMD includes built-in rulesets to run quick analyses with a default configuration, but
users are encouraged to make their own rulesets from the start, because they allow for so much
configurability.
Rulesets are written in XML. The following sections walk you through the creation of a ruleset.
## Creating a custom ruleset
The first step is to create a new empty ruleset. You can use the following template:
``` xml
<?xml version="1.0"?>
<ruleset name="Custom Rules"
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
<description>
My custom rules
</description>
<!-- Your rules will come here -->
</ruleset>
```
### Referencing rules
To use the built-in rules PMD provides, you need to add some *references* to them. Here's a
basic rule reference:
```xml
<rule ref="category/java/errorprone.xml/EmptyCatchBlock" />
```
Adding that element into the `ruleset` element adds the rule [EmptyCatchBlock](pmd_rules_java_errorprone.html#emptycatchblock)
to your ruleset. This is a Java rule, so it will be executed on every Java file PMD encounters in
its search space.
How to read the `ref` attribute?
* `category/java/errorprone.xml` is a reference to the Java category `errorprone`. Since PMD 6.0.0,
all PMD built-in rules are sorted in one of eight categories, which are consistent across languages:
1. **Best Practices**: These are rules which enforce generally accepted best practices.<br/>
2. **Code Style**: These rules enforce a specific coding style.<br/>
3. **Design**: Rules that help you discover design issues.<br/>
4. **Documentation**: These rules are related to code documentation.<br/>
5. **Error Prone**: Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors.<br/>
6. **Multithreading**: These are rules that flag issues when dealing with multiple threads of execution.<br/>
7. **Performance**: Rules that flag suboptimal code.<br/>
8. **Security**: Rules that flag potential security flaws."
{% include tip.html content="You can discover the available rules by language and category [from this page](tag_rule_references.html)" %}
* `EmptyCatchBlock` is simply the name of the rule. If there were no rule with that name within the specified
category, then PMD would fail before starting the analysis.
### Configuring individual rules
Main documentation page: [Configuring rules](pmd_userdocs_configuring_rules.html)