Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 04b0859

Browse files
oowekyalaoowekyala
committed
Merge Understanding rulesets into Making rulesets
1 parent 891df94 commit 04b0859

File tree

4 files changed

+91
-186
lines changed

4 files changed

+91
-186
lines changed

‎docs/_data/sidebars/pmd_sidebar.yml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ entries:
1818
- title: About
1919
output: web, pdf
2020
folderitems:
21-
- title: Introduction
21+
- title: Home
2222
url: /index.html
2323
output: web, pdf
2424
type: homepage
@@ -34,9 +34,6 @@ entries:
3434
- title: Installation and basic CLI usage
3535
url: /pmd_userdocs_installation.html
3636
output: web, pdf
37-
- title: Understanding rulesets
38-
url: /pmd_userdocs_understanding_rulesets.html
39-
output: web, pdf
4037
- title: Making rulesets
4138
url: /pmd_userdocs_making_rulesets.html
4239
output: web, pdf

‎docs/pages/pmd/userdocs/installation.md‎

Lines changed: 24 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -35,24 +35,36 @@ Unzip it into any directory, optionally add the `bin` subdirectory in your `PATH
3535
the arguments are specific to the utility used.<br/><br/>
3636
On Windows, each utility has its own startup script, e.g. `pmd.bat`, `cpd.bat`." %}
3737

38-
The PMD command (`pmd.bat` or `run.sh pmd`) requires three options:
38+
The PMD command (`pmd.bat` or `run.sh pmd`) requires two options:
3939

40-
* `-d <path>`: path to the sources to analyse. This can be a file name, a directory or a jar or zip file containing the
40+
* `-d <path>`: path to the sources to analyse. This can be a file name, a directory, or a jar or zip file containing the
4141
sources.
42-
* `-f <format>`: report format. PMD supports many report formats out of the box, you may want to start with the basic
43-
`text`
44-
format or `xml` format.
4542
* `-R <path>`: the ruleset file you want to use. PMD uses xml configuration files, called *rulesets*, which specify
46-
which rules to check for in your sources. PMD provides standard rulesets for each language it supports, grouping the
47-
rules by theme. Instead of a path, you can reference those standard rulesets with the lightweight syntax
48-
`rulesets/<lang>/<name.xml>`, e .g. `rulesets/java/codesize.xml`.
43+
which rules to execute on your sources. You can also run a single rule by referencing it using its *category* and
44+
name (more details [here](pmd_userdocs_making_rulesets.html#referencing-rules)). For example, you can check for unnecessary
45+
modifiers on Java sources with `-R category/java/codestyle.xml/UnnecessaryModifier`.
4946

5047
{% include note.html
51-
content="At the moment most of the formerly provided rulesets are deprecated, though you can still use them. PMD
52-
will soon propose updated rulesets to use as default configurations." %}
48+
content="At the moment the formerly provided rulesets (eg `rulesets/java/basic.xml`) are deprecated,
49+
though you can still use them. PMD will soon include standard rulesets as default configurations,
50+
but you're strongly encouraged to [create your own ruleset](pmd_userdocs_making_rulesets.html) from
51+
the start." %}
5352

53+
Additionnally, the following options, are specified most of the time even though they're not required:
54+
* `-f <format>`: report format. PMD supports many report formats out of the box, you may want to start with the basic
55+
`text` format or `xml` format.
56+
* `-auxclasspath <classpath>`: class path containing the compiled class files of the analysed Java sources, if any.
57+
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),
58+
require it to function properly.
59+
60+
{%include tip.html content="A full CLI reference, including report formats, is available under [PMD CLI Reference](pmd_userdocs_cli_reference.html)" %}
61+
62+
63+
64+
### Sample usage
65+
66+
The following shows a sample run of with the `text` format:
5467

55-
Sample usage with the `text` format:
5668

5769
<div class="text-left">
5870
<ul class="nav nav-tabs" role="tablist">
@@ -82,13 +94,7 @@ Sample usage with the `text` format:
8294
.../src/main/java/com/me/RuleSetWriter.java:66 Avoid empty catch blocks</code></pre></figure>
8395
</div>
8496
</div>
85-
</div>
86-
87-
88-
Also, the PMD binary distribution includes the ruleset files
89-
inside the jar file - even though the "rulesets/java/unusedcode.xml" parameter
90-
above looks like a filesystem reference, it's really being used by a getResourceAsStream() call
91-
to load it out of the PMD jar file.
97+
</div>
9298

9399

94100
## Running CPD via command line

‎docs/pages/pmd/userdocs/making_rulesets.md‎

Lines changed: 66 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,96 @@
11
---
2-
title: PMD Making Rulesets
3-
tags: [customizing, rulesets]
2+
title: Making rulesets
3+
keywords: [rulesets, reference, rule, exclude, include, pattern, filter]
4+
tags: [customizing, essentials, userdocs]
45
summary: Making Custom Rulesets for PMD
56
last_updated: November 2017
7+
summary: "A ruleset is an XML configuration file, which describes a collection of rules to be executed
8+
in a PMD run. PMD includes built-in rulesets to run quick analyses with a default configuration, but
9+
users are encouraged to make their own rulesets from the start, because they allow for so much
10+
configurability. This page walk you through the creation of a ruleset and the multiple configuration
11+
features offered by rulesets."
12+
last_updated: May 2018 (6.4.0)
613
permalink: pmd_userdocs_making_rulesets.html
7-
author: Tom Copeland <[email protected]>
14+
author: Tom Copeland <[email protected]>, Clément Fournier <[email protected]>
815
---
916

10-
# How to make a new rule set
17+
## Creating a ruleset
1118

12-
Say you want to pick specific rules from various rule sets and customize them. You can do this by making your own rule set.
19+
The first step is to create a new empty ruleset. You can use the following template:
1320

14-
## Create a new ruleset.xml file
21+
``` xml
22+
<?xml version="1.0"?>
1523

16-
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:
24+
<ruleset name="Custom Rules"
25+
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
26+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
27+
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
1728

18-
```xml
19-
<?xml version="1.0"?>
20-
<ruleset name="Custom ruleset"
21-
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
22-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
23-
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
2429
<description>
25-
This ruleset checks my code for bad stuff
30+
My custom rules
2631
</description>
32+
33+
34+
<!-- Your rules will come here -->
35+
2736
</ruleset>
28-
````
37+
```
2938

30-
## Add some rule references to it
39+
### Referencing a single rule
3140

32-
After you add these references it’ll look something like this:
41+
<!-- 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 -->
3342

34-
```xml
35-
<?xml version="1.0"?>
36-
<ruleset name="Custom ruleset"
37-
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
38-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
39-
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
43+
To use the built-in rules PMD provides, you need to add some *references* to them. Here's a
44+
basic rule reference:
4045

41-
<description>
42-
This ruleset checks my code for bad stuff
43-
</description>
44-
45-
<!-- Here's some rules we'll specify one at a time -->
46-
<rule ref="category/java/bestpractices.xml/UnusedLocalVariable"/>
47-
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
48-
<rule ref="category/java/codestyle.xml/DuplicateImports"/>
49-
<rule ref="category/java/errorprone.xml/UnnecessaryConversionTemporary"/>
50-
51-
<!-- We want to customize this rule a bit, change the message and raise the priority -->
52-
<rule ref="category/java/errorprone.xml/EmptyCatchBlock"
53-
message="Must handle exceptions">
54-
<priority>2</priority>
55-
</rule>
56-
57-
<!-- Now we'll customize a rule's property value -->
58-
<rule ref="category/java/design.xml/CyclomaticComplexity">
59-
<properties>
60-
<property name="classReportLevel" value="40"/>
61-
<property name="methodReportLevel" value="5"/>
62-
</properties>
63-
</rule>
64-
65-
<!-- We want everything from category Code Style except WhileLoopsMustUseBraces -->
66-
<rule ref="category/java/codestyle.xml">
67-
<exclude name="WhileLoopsMustUseBraces"/>
68-
</rule>
69-
</ruleset>
46+
```xml
47+
<rule ref="category/java/errorprone.xml/EmptyCatchBlock" />
7048
```
7149

72-
>Notice that you can customize individual referenced rules. Everything but the class of the rule can be overridden in your custom ruleset.
50+
Adding that element into the `ruleset` element adds the rule [EmptyCatchBlock](pmd_rules_java_errorprone.html#emptycatchblock)
51+
to your ruleset. This is a Java rule, so it will be executed on every Java file PMD encounters in
52+
its search space.
53+
54+
How to read the `ref` attribute?
55+
56+
* `category/java/errorprone.xml` is a reference to the Java category `errorprone`. Since PMD 6.0.0,
57+
all PMD built-in rules are sorted in one of eight categories, which are consistent across languages:
58+
59+
1. **Best Practices**: These are rules which enforce generally accepted best practices.<br/>
60+
2. **Code Style**: These rules enforce a specific coding style.<br/>
61+
3. **Design**: Rules that help you discover design issues.<br/>
62+
4. **Documentation**: These rules are related to code documentation.<br/>
63+
5. **Error Prone**: Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors.<br/>
64+
6. **Multithreading**: These are rules that flag issues when dealing with multiple threads of execution.<br/>
65+
7. **Performance**: Rules that flag suboptimal code.<br/>
66+
8. **Security**: Rules that flag potential security flaws."
67+
68+
{% include tip.html content="You can discover the available rules by language and category [from this page](tag_rule_references.html)" %}
69+
7370

74-
## Excluding rules from a ruleset
71+
* `EmptyCatchBlock` is simply the name of the rule. If there were no rule with that name within the specified
72+
category, then PMD would fail before starting the analysis.
7573

76-
You can also make a custom ruleset by referencing a complete category and exclude certain rules, like this:
74+
#### [Configuring individual rules](pmd_userdocs_configuring_rules.html)
75+
76+
### Bulk-adding rules
77+
78+
You can also reference rules in bulk by referencing a complete category or ruleset, possibly excluding certain rules, like in the following:
7779

7880
```xml
79-
<?xml version="1.0"?>
80-
<ruleset name="myruleset"
81-
xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
82-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
83-
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
84-
<description>All codestyle rules, but with just the braces rules I like</description>
8581
<rule ref="category/java/codestyle.xml">
8682
<exclude name="WhileLoopsMustUseBraces"/>
8783
<exclude name="IfElseStmtsMustUseBraces"/>
8884
</rule>
89-
</ruleset>
9085
```
9186

92-
## Excluding files from a ruleset
87+
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.
88+
89+
{% 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." %}
9390

94-
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:
91+
### Filtering the processed files
92+
93+
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:
9594

9695
```xml
9796
<?xml version="1.0"?>
@@ -100,32 +99,12 @@ You can also exclude certain files from being processed by a ruleset using exclu
10099
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
101100
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd">
102101
<description>My ruleset</description>
102+
103103
<exclude-pattern>.*/some/package/.*</exclude-pattern>
104104
<exclude-pattern>.*/some/other/package/FunkyClassNamePrefix.*</exclude-pattern>
105105
<include-pattern>.*/some/package/ButNotThisClass.*</include-pattern>
106-
<rule>...
107-
</ruleset>
108-
```
109-
110-
## Reference it in your Ant task
111106

112-
You can specify the full path to your custom ruleset name alongside of the built-in PMD rulesets - like this:
107+
<!-- Rules here ... -->
113108

114-
```xml
115-
<pmd rulesetfiles="/home/tom/data/pmd/pmd/rulesets/java/design.xml,rulesets/java/unusedcode.xml">
116-
<formatter type="xml" toFile="foo.xml"/>
117-
<fileset dir="/home/tom/data/pmd/pmd/src">
118-
<include name="**/*.java"/>
119-
</fileset>
120-
</pmd>
109+
</ruleset>
121110
```
122-
123-
## To see it in your IDE
124-
125-
You'll need to point the IDE plugin to the location of your custom ruleset.
126-
127-
## Send us feedback
128-
129-
If you have suggestions on clarifying this document, please post them to [the forum](http://sourceforge.net/p/pmd/discussion/188192). Thanks!
130-
131-
Finally, for many more details on building custom rulesets, pick up [PMD Applied](http://pmdapplied.com/)!

‎docs/pages/pmd/userdocs/understanding_rulesets.md‎

Lines changed: 0 additions & 77 deletions
This file was deleted.

0 commit comments

Comments
 (0)