Skip to end of metadata
Go to start of metadata

This page explains how to create RPG custom rules as a custom SonarQube plugin.

Plugin Example

To get started a sample plugin can be browsed or downloaded.

Prerequisites

Creating a Maven Project

You should first create a Maven project: re-using the pom.xml from the RPG example is a good start.

The following dependencies need to be defined in the pom.xml:

  • sonar-plugin-api to get access to SonarQube APIs
  • sonar-rpg-plugin to use the APIs of the RPG plugin

Writing a Custom Rule

Each rule needs to be defined in a class which:

  • Implements com.sonarsource.rpg.api.checks.Check. Instead of implementing this interface directly, the class can also extend VisitorBasedCheck which make it easier to target some specific parts of the analyzed source code.
  • Has a org.sonar.check.Rule annotation to define the key of the rule.

Navigating the Syntax Tree

The analyzed source code is represented as a tree structure. The top-most tree is an instance of ModuleTree which has references to other trees. Some of the trees represent a group of RPG calculations (for example, an IF group is represented as a tree which references the calculations which are executed when the condition is true), some others represent expressions such as a + b.

The instance of CheckContext which is passed to the checks gives a reference to the ModuleTree of the analyzed source code. The whole tree structure can be navigated from that object.

Most often, it's easier to extend VisitorBasedCheck and to override one or more methods which name starts with visit, e.g. visitIfGroup. That way, it's possible to define what should be executed when visiting some specific kinds of trees.

Creating Issues

CheckContext provides methods to create issues either at file level or at line level.

Testing the Rule

It's possible to write unit tests for custom rules using com.sonarsource.rpg.api.test.RpgCheckVerifier. This utility class executes a custom rule against a given RPG test file. The RPG test file should contain comments defining on which lines issues should be expected:

  • if the line ends with "// Noncompliant", RpgCheckVerifier expects an issue on that line.
  • if the line ends with "// Noncompliant {{my message}}", RpgCheckVerifier expects an issue on that line and checks that the issue message is "my message".

The example project contains an example test class and the associated RPG file.

Rules Definition

One class should extend com.sonarsource.rpg.api.CustomRulesDefinition : it should list the classes of the custom rules and use the SonarQube API to define the metadata of these rules: name, HTML description, default severity...

Plugin Class

The entry point of the custom plugin is a class which lists SonarQube extensions. This list should contain the class created at the previous step.

Packaging the Custom Plugin

To package your custom plugin, the pom.xml should use org.sonarsource.sonar-packaging-maven-plugin, as described in the documentation explaining how to build a plugin.

Moreover, in the configuration for sonar-packaging-maven-pluginbasePlugin should be set to "rpg".

Building the Maven project will then produce a JAR file which can be deployed to a SonarQube server.

 

 

  • No labels