From 04b0859fb29e17498a3e15c644c79dba7090a314 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Mon, 21 May 2018 05:49:02 +0200 Subject: [PATCH] Merge Understanding rulesets into Making rulesets --- docs/_data/sidebars/pmd_sidebar.yml | 5 +- docs/pages/pmd/userdocs/installation.md | 42 +++-- docs/pages/pmd/userdocs/making_rulesets.md | 175 ++++++++---------- .../pmd/userdocs/understanding_rulesets.md | 77 -------- 4 files changed, 102 insertions(+), 197 deletions(-) delete mode 100644 docs/pages/pmd/userdocs/understanding_rulesets.md diff --git a/docs/_data/sidebars/pmd_sidebar.yml b/docs/_data/sidebars/pmd_sidebar.yml index 25f88076b2..f44664c3ec 100644 --- a/docs/_data/sidebars/pmd_sidebar.yml +++ b/docs/_data/sidebars/pmd_sidebar.yml @@ -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 diff --git a/docs/pages/pmd/userdocs/installation.md b/docs/pages/pmd/userdocs/installation.md index 7393cf94a1..5ee273f1ac 100644 --- a/docs/pages/pmd/userdocs/installation.md +++ b/docs/pages/pmd/userdocs/installation.md @@ -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.

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 to the sources to analyse. This can be a file name, a directory or a jar or zip file containing the +* `-d `: path to the sources to analyse. This can be a file name, a directory, or a jar or zip file containing the sources. -* `-f `: 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 `: 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//`, 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 `: 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 `: 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: +
    @@ -82,13 +94,7 @@ Sample usage with the `text` format: .../src/main/java/com/me/RuleSetWriter.java:66 Avoid empty catch blocks
- - - -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. + ## Running CPD via command line diff --git a/docs/pages/pmd/userdocs/making_rulesets.md b/docs/pages/pmd/userdocs/making_rulesets.md index 1b9345a833..10053b1522 100644 --- a/docs/pages/pmd/userdocs/making_rulesets.md +++ b/docs/pages/pmd/userdocs/making_rulesets.md @@ -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 +author: Tom Copeland , Clément Fournier --- -# 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 - - - This ruleset checks my code for bad stuff - - -```` -## Add some rule references to it - -After you add these references it’ll look something like this: - -```xml - - - - - This ruleset checks my code for bad stuff - - - - - - - - - - - 2 - - - - - - - - - - - - - - - -``` - ->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 - - - All codestyle rules, but with just the braces rules I like + + + My custom rules + + + + + + +``` + +### Referencing a single rule + + + +To use the built-in rules PMD provides, you need to add some *references* to them. Here's a +basic rule reference: + +```xml + +``` + +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.
+ 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." + +{% 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 - ``` -## 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 @@ -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"> My ruleset + .*/some/package/.* .*/some/other/package/FunkyClassNamePrefix.* .*/some/package/ButNotThisClass.* - ... + + + ``` - -## 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 - - - - - - -``` - -## 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/)! diff --git a/docs/pages/pmd/userdocs/understanding_rulesets.md b/docs/pages/pmd/userdocs/understanding_rulesets.md deleted file mode 100644 index 3ad69f546a..0000000000 --- a/docs/pages/pmd/userdocs/understanding_rulesets.md +++ /dev/null @@ -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 - - - - - - My custom rules - - - - - - -``` - -### 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 - -``` - -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.
- 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." - -{% 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)