CXX Custom Rules

The cxx plugin makes it possible to add custom rules written in Java. In general, there are three ways to add coding rules to SonarQube:

• Writing a SonarQube plugin in Java that uses SonarQube APIs to add new rules
• Adding XPath rules directly through the SonarQube web interface. The cxx plugin provides an own CXX XPath extension.
• Importing generic issue reports generated by an independently run tool

The Java API will be more fully-featured than what's available for XPath, and is generally preferable. However, this comes with the overhead of maintaining a SonarQube plugin (including keeping it up-to-date as APIs change, upgrading the plugin after releasing a new version).

Importing generic issue reports is a good solution when there's a very specific need for a subset of projects on your SonarQube instance. They are the most flexible option but lack some features (such as being able to control their execution by inclusion in a quality profile).

Writing a SonarQube plugin in Java that uses SonarQube APIs to add new rules

Writing custom rules for CXX is a six-step process:

• Create a new SonarQube custom rules plugin (use https://github.com/SonarOpenCommunity/cxx-custom-checks-example-plugin as template).
  • As a first step, the pom.xml file must be adapted. The version numbers must match the versions of the cxx plugin (cxx plugin pom.xml) for which custom rules are written.
  • Under Advanced build properties you will find further instructions for setting the metadata.
  • sonar-plugin-api describes changes to the API.
• Put a dependency on the API of the cxx plugin. The cxx plugin must be built locally with Maven so that it is available in the local Maven Repository and can be used as a dependency in the custom plugin.
• Create as many custom rules as required. The rules must be derived from CustomCxxRulesDefinition.
• Generate the SonarQube custom rules plugin (jar file).
• Place this jar file in the SONARQUBE_HOME/extensions/plugins directory.
• Restart SonarQube Server.

The description Plugin Basics is a good starting point for writing your own extensions. In addition, Adding Coding Rules gives further useful hints.

The existing CXX rules can be used as a template for the new rules: https://github.com/SonarOpenCommunity/sonar-cxx/tree/master/cxx-checks/src/main/java/org/sonar/cxx/checks

Sample:

public final class MyCustomRulesPlugin implements Plugin {

  @Override
  public void define(Context context) {
    context.addExtension(
      MyCustomRulesDefinition.class
    );
  }
}

public class MyCustomRulesDefinition extends CustomCxxRulesDefinition {

  @Override
  public String repositoryName() {
    return "MyCustomCxxRepository";
  }

  @Override
  public String repositoryKey() {
    return "mycustomcxxrepo";
  }

  @SuppressWarnings("rawtypes")
  @Override
  public Class[] checkClasses() {
    return new Class[]{
      UsingNamespaceCheck.class
    };
  }
}

@Rule(
  key = "UsingNamespace",
  priority = Priority.BLOCKER,
  name = "Using namespace directives are not allowed",
  tags = {Tag.CONVENTION})
@SqaleConstantRemediation("5min")
@ActivatedByDefault
public class UsingNamespaceCheck extends SquidCheck<Grammar> {

  @Override
  public void init() {
    subscribeTo(CxxGrammarImpl.usingDirective);
  }

  @Override
  public void visitNode(AstNode node) {
    getContext().createLineViolation(this, "Using namespace are not allowed.", node);
  }
}

Example Plugin

You can use https://github.com/SonarOpenCommunity/cxx-custom-checks-example-plugin as a base for your rules.