forked from phoedos/pmd
Rewrite understanding_rulesets.md, needs merging with making_rulesets.md
This commit is contained in:
Clément Fournier
@ -27,12 +27,13 @@ Unzip it into any directory, optionally add the `bin` subdirectory in your `PATH
|
||||
|
||||
## Running PMD via command line
|
||||
|
||||
{% include callout.html type="primary" content="PMD comes with several command line utilities, like CPD, the rule
|
||||
designer or PMD itself.
|
||||
On Unix, you can run any of them using the script `run.sh`, located inside the `bin/` directory of the PMD distribution
|
||||
. The first argument is the name of the utility you want to execute ('pmd', 'designer', ...), e.g. PMD is launched via
|
||||
`run.sh pmd`. The rest of 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`." %}
|
||||
{% include callout.html type="primary"
|
||||
content="PMD comes with several command line utilities, like CPD, the rule designer or PMD itself.
|
||||
On Unix, you can run any of them using the script `run.sh`, located inside the `bin/`
|
||||
directory of the PMD distribution. The first argument is the name of the utility you want
|
||||
to execute ('pmd', 'designer', ...), e.g. PMD is launched via `run.sh pmd`. The rest of
|
||||
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:
|
||||
|
||||
|
||||
@ -6,52 +6,20 @@ summary: Rules belong to categories and rulesets are custom collections of rules
|
||||
last_updated: November 2017
|
||||
---
|
||||
|
||||
## Rule Categories
|
||||
|
||||
Since PMD 6.0.0, all provided built-in rules are sorted into one of eight categories:
|
||||
## What's a ruleset?
|
||||
|
||||
1. **Best Practices**: These are rules which enforce generally accepted best practices.
|
||||
2. **Code Style**: These rules enforce a specific coding style.
|
||||
3. **Design**: Rules that help you discover design issues.
|
||||
4. **Documentation**: These rules are related to code documentation.
|
||||
5. **Error Prone**: Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors.
|
||||
6. **Multithreading**: These are rules that flag issues when dealing with multiple threads of execution.
|
||||
7. **Performance**: Rules that flag suboptimal code.
|
||||
8. **Security**: Rules that flag potential security flaws.
|
||||
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.
|
||||
|
||||
These categories help you to find rules and figure out the relevance and impact for your project.
|
||||
|
||||
You can find the available rules under "Rule Reference" in the menu. Each languages has its own rule
|
||||
index, e.g. [Java Rules](pmd_rules_java.html) or [JavaScript Rules](pmd_rules_ecmascript.html).
|
||||
|
||||
{% include note.html content="Not all supported languages provide rules in all categories yet. " %}
|
||||
Rulesets are written in XML. The following sections walk you through the creation of a ruleset.
|
||||
|
||||
|
||||
## Rulesets
|
||||
## Creating a custom ruleset
|
||||
|
||||
There are two major use cases:
|
||||
|
||||
1. When defining a new rule, the rule needs to be defined in a ruleset. PMD's built-in rules
|
||||
are defined in special rulesets which form the eight categories mentioned above.
|
||||
From these rulesets the rule reference documentation is generated,
|
||||
see [Java Rules](pmd_rules_java.html) for an example.
|
||||
|
||||
Similar rules are grouped together into the same category, like [Java Best Practices](pmd_rules_java_bestpractices.html)
|
||||
which contains rules which enforce generally accepted best practices. Each category uses its own
|
||||
ruleset file.
|
||||
|
||||
2. When executing PMD, you need to tell, which rules should be executed. You could directly point to the
|
||||
built-in rulesets, but then you might be overwhelmed by the found violations. As described
|
||||
in [Best Practices](pmd_userdocs_best_practices.html), it's better to define an own custom ruleset.
|
||||
|
||||
With an own custom ruleset, you can:
|
||||
|
||||
* Select the rules, that should be executed
|
||||
* Adjust the rule properties to exactly meet your needs
|
||||
|
||||
## Create a custom ruleset
|
||||
|
||||
You start by creating a new XML file with the following contents:
|
||||
The first step is to create a new XML file. You can use the following template:
|
||||
|
||||
``` xml
|
||||
<?xml version="1.0"?>
|
||||
@ -60,36 +28,51 @@ You start by creating a new XML file with the following contents:
|
||||
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>
|
||||
Custom rules
|
||||
My custom rules
|
||||
</description>
|
||||
|
||||
|
||||
<!-- Your rules will come here -->
|
||||
|
||||
</ruleset>
|
||||
```
|
||||
|
||||
Now start to add rule by **referencing** them. Let's say, you want to start with finding
|
||||
[Empty Catch Blocks](pmd_rules_java_errorprone.html#emptycatchblock). Then you'd add the following
|
||||
rule reference inside the `ruleset` elements:
|
||||
### 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" />
|
||||
```
|
||||
|
||||
## Adjusting rule properties
|
||||
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.
|
||||
|
||||
If you want to be less strict with empty catch blocks, you could define that an exception variable name
|
||||
of `ignored` will not raise a violation. Therefore you would reference the rule **and** define
|
||||
the appropriate property value:
|
||||
How to read the `ref` attribute?
|
||||
|
||||
```xml
|
||||
<rule ref="category/java/errorprone.xml/EmptyCatchBlock">
|
||||
<properties>
|
||||
<property name="allowExceptionNameRegex">
|
||||
<value>^ignored$</value>
|
||||
</property>
|
||||
</properties>
|
||||
</rule>
|
||||
```
|
||||
* `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)" %}
|
||||
|
||||
|
||||
{% include note.html content="More information about rulesets can be found on [Making Rulesets](pmd_userdocs_making_rulesets.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
|
||||
|
||||
Many rules give you some freedom of configuration by letting you use **rule properties**.
|
||||
Configuring rules this way [is described on this page](pmd_userdocs_using_properties.html).
|
||||
|
||||
Reference in New Issue
Block a user