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|CXX-Custom-XPath-Rules]] 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.
  • the HTML description(s) must be created in /org/sonar/l10n/cxx/rules/{repositoryKey}
• 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

C++ sample to verify:

using namespace std;

void foo()
{
}

Resulting AST:

Custom Rule Plugin 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 "Custom CXX";
  }

  @Override
  public String repositoryKey() {
    // The html descriptions for the rules of repository must be stored in the path '/org/sonar/l10n/cxx/rules/mycxx'.
    // If the return value of 'repositoryKey' is changed, the storage location in 'resources' must also be adjusted.
    return "mycxx";
  }

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

// In case you are adding a .html description in resources, the .html file name should match the rule key.
// In this sample the name must be 'UsingNamespace.html'.
@Rule(
  key = "UsingNamespace",
   priority = Priority.BLOCKER,
   name = "Using namespace directives are not allowed",
   tags = {Tag.CONVENTION}
// second possibility to add a rule description:
//,description = "Using namespace directives are not allowed."
)
@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);
  }
}