There are three ways to extend coding rules:
- Adding XPath rules directly in the Sonar web interface.
- Extending an existing Sonar plugin. For example Checkstyle and PMD plugins accept definition of custom checks.
- Embedding and executing a code analyzer. For example the Checkstyle plugin configures and executes the library Checkstyle.
To implement a new coding rule, we recommend to start with XPath at it is the most simple way. If it cannot be achieved with XPath rules (either because the language plugin does not support XPath yet or because the rule is highly complex and cannot be defined with an XPath expression), then write your own Sonar plugin.
Adding New Rules Using XPath Expressions
The rules have to be written in XPath to navigate the Abstract Syntax Tree (AST). For each language, an SSLR Toolkit is provided to navigate the AST. This SSLR Toolkit is a standalone application that displays the AST for a provided piece of code source. So that you quickly get the nodes names and attributes to write your XPath expression from your code sample. The proper SSLR Toolkit can be downloaded from the language plugin page. So, finally, knowing the XPath language is the only prerequisite. A lot of tutorials on XPath can be found online (see http://www.w3schools.com/xpath/ for example).
While parsing the source code, Sonar builds an Abstract Syntax Tree (AST).
The XPath language provides a way to write coding rules by navigating this AST.
To create a new rule:
- Login as an administrator
- Go to Configuration > Quality Profile
- Select one of the quality profiles whose language you want to add a new rule
- Look for the XPath rule template:
- Copy this template to create a new rule:
Write your XPath rule (it should comply to XPath 1.0):
Do not use document.write:
Always use curly braces for if/else statements:
- Once written, activate those rules and run a Sonar analysis.
- Violations on those XPath rules are now logged:
Extending Sonar Plugins
The following languages can be extended with new rules:
- C: see how to extend C rules
- C#: see how to extend FxCop and Gendarme rules
- Cobol: see how to extend Cobol rules
- PHP: see how to extend PHP CodeSniffer and PHPMD rules
Executing a Code Analyzer
A code analyzer plugin executes the following steps:
- Register definitions of coding rules, when the server is started.
- Optionally define some templates of quality profiles, when the server is started.
- Analyze source code and inject results in database
1. Registering coding rules
This step relates to the extension point org.sonar.api.rules.RuleRepository. A RuleRepository defines a set of coding rules. It usually loads data from a XML file:
The XML file is available in the plugin classloader and looks like :
2. Defining quality profiles
This step relates to the extension point org.sonar.api.profiles.ProfileDefinition. Profiles provided by plugins are registered at server startup and can't be edited by users:
3. Analyzing source code
This step relates to the extension point org.sonar.api.batch.Sensor.