Extending the code analysis

Note: Defining rules in extensions/rules folder in SonarQube server is no longer supported by this plugin

Extending rules in supported code analysers

If you're using a patched or not-yet-supported version of an integrated code checker (like Cppcheck), you probably want to see those new checks in SonarQube, too. To do this, you have 2 different approachs availalbe.

Using a xml definition

1. Define those rules using the XML format described further below in a temporary file.
2. Paste the content of file into the relevant configuration property in the SonarQube server. For example for cppcheck.
3. Restart the SonarQube server (This is the drawback of this method).
4. Make sure the newly added rules are visible in the quality profile; enable them
5. Run the analysis

Properties

Property	Description
sonar.cxx.cppcheck.customRules	Cppcheck Custom Rules
sonar.cxx.valgrind.customRules	Valgrind Custom Rules
sonar.cxx.pclint.customRules	PClint Custom Rules
sonar.cxx.rats.customRules	RATS Custom Rules
sonar.cxx.vera.customRules	Vera++ Custom Rules
sonar.cxx.other.rules	Unsupported Code Checker Custom Rules, see below

The format of the rules file

The format of rules file is expected to be the following (RulesDefinitionXmlLoader):

V0.9.3 and later:

<rules>
   <rule>
     <!-- required fields -->
     <key>the-rule-key</key>
     <name>The purpose of the rule</name>
     <description>
       <![CDATA[The description]]>
     </description>

     <!-- optional fields -->
     <internalKey>Checker/TreeWalker/LocalVariableName</internalKey>
     <severity>BLOCKER</severity>
     <cardinality>MULTIPLE</cardinality>
     <status>BETA</status>
     <param>
       <key>the-param-key</key>
       <tag>style</tag>
       <tag>security</tag>
       <description>
         <![CDATA[the param-description]]>
       </description>
       <defaultValue>42</defaultValue>
     </param>
     <param>
       <key>another-param</key>
     </param>

     <!-- deprecated fields -->
     <configKey>Checker/TreeWalker/LocalVariableName</configKey>
     <priority>BLOCKER</priority>
   </rule>
 </rules>

Deprecated but still supported:

<rules>
  <rule key="RULE_ID">
    <name><![CDATA[ ... put here the human readable name of this rule ... ]]></name>
    <configKey><![CDATA[RULE_ID@$(EXTERNALSENSORCLASS)]]></configKey>
    <category name=" ... category type ... " />
    <description><![CDATA[ ... put here the human readable description of this rule ... ]]></description>
  </rule>
</rules>

Where the fields have the following semantics:

Tag/Attribute	MySql	Semantic
key [RULE_ID]	varchar(200)	Id of the rule, should match the ID in the external reports. Note: Only alphabetic characters, digits and underscores are permitted for declaring the key. First sign should not be a digit.
name	varchar(200)	Can be really anything, in the quality profile in SonarQube its the first name that is displayed per rule
configKey	varchar(500)	This key is used later by the sensor to configure the code analyzer ([Extending+Coding+Rules] (http://docs.codehaus.org/display/SONAR/Extending+Coding+Rules))
category name		Can be anything, examples include Maintainability Style Usability etc
description	mediumtext	In the quality profile in SonarQube UI, the description will be show after expanding each rule

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rules>
  <rule key="Te0001DataContextCannotBeSet">
    <name><![CDATA[Te0001DataContextCannotBeSet]]></name>
    <configKey>
      <![CDATA[Te0001DataContextCannotBeSet@PC_LINT]]>
    </configKey>
    <category name="Maintainability" />
    <description>
      <![CDATA[ Data Context Should no be set, please use another approach ]]>
    </description>
  </rule>
</rules>

It is also possible to add hyperlinks to the description, use <a> tags.

<description>
  <![CDATA[<a href="http://example.com/xyz.html">Link</a>]]>
</description>

SQALE characteristics (>= V0.9.4)

Starting with the version 0.9.4 it is also possible to define SQALE characteristics for other rules. To define the SQALE characteristics an extra XML file has to be defined and assigned to sonar.cxx.other.sqales. Assign the XML file on server side to the configuration property on the page 'C++ settings / (2) Code analysis' and restart the server to enable it (same as with rule definitions). The XML file must fit the XML schema for SQALE characteristics. For more complex examples have a look to the folder SQALE.

Example:

<sqale>
  <chc>
    <key>PORTABILITY</key>
    <name>Portability</name>
    <chc>
      <key>COMPILER_RELATED_PORTABILITY</key>
      <name>Compiler related portability</name>
      <chc>
        <rule-repo>other</rule-repo>
        <rule-key>key</rule-key>
        <prop>
          <key>remediationFunction</key>
          <txt>linear_offset</txt>
        </prop>
        <prop>
          <key>remediationFactor</key>
          <val>5</val>
          <txt>mn</txt>
        </prop>
        <prop>
          <key>offset</key>
          <val>10</val>
          <txt>mn</txt>
        </prop>
      </chc>
    </chc>
  </chc>
</sqale>

Example of Levels 1 and 2 of a SQALE Quality Model:

Characteristic	Subcharacteristic
Reusability	Extractability
Reusability	Conciseness
Reusability	Stability
Portability	Language related portability
Portability	Time zone related portability
Portability	Hardware related portability
Portability	External application related portability
Portability	Compiler related portability
Portability	OS related portability
Maintainability	Understandability
Maintainability	Readability
Security	OS related security
Security	User related security
Security	Statement related security
Efficiency	ROM related efficiency
Efficiency	RAM related efficiency
Efficiency	CPU related efficiency
Changeability	Architecture related changeability
Changeability	Logic related changeability
Changeability	Data related changeability
Reliability	Fault tolerance
Reliability	Architecture related reliability
Reliability	Resource related reliability
Reliability	Synchronization related reliability
Reliability	Statement related reliability
Reliability	Logic related reliability
Reliability	Data related reliability
Testability	Integration Testing testability
Testability	Unit Testing testability

Using Template Rules

This method allows the creation of rules on the fly, no need to for server restart. To do this follow these steps.

1. Locate the relevant custom rule for the code checker you want to extend.
2. Press create and fill in the details
3. Enable the rule and run a new analysis

These rules can be created using the rest api, see https://github.com/jmecsoftware/QualityProfileEditorPlugin as an example

Usage of unsupported code checkers

If you're using a code checker which is not supported by the plugin, this feature is for you. It allows to feed violations into SonarQube in a code checker agnostic way. To do this follow the steps below:

1. Create a XML file describing the rules and place it in code analysis settings of the plugin in the SonarQube server under the property sonar.cxx.other.rules Use the format described above. You can import multiple custom rules by clicking the Add value and save the settings

2. Run your checker and create a report

3. Transform the report such that it conform to the following RNG schema:

   <element name="results" xmlns="http://relaxng.org/ns/structure/1.0">
     <zeroOrMore>
       <element name="error">
         <attribute name="file"/>
         <attribute name="msg"/>
         <attribute name="id"/>
         <attribute name="line">
           <data type="integer" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" />
         </attribute>
         <text/>
       </element>
     </zeroOrMore>
   </element>

Where the fields have the following semantics:

Tag/Attribute	Semantic
file	Source file, relative to project path
line	Line number where the violation occurres
id	The ID of the violated SonarQube rule
msg	Description of the violation

4. Set the property **sonar.cxx.other.reportPath** to point to the location of transformed report (relative to project root) and run one analysis.

Resources

Below you find a list of code analyzers which have already been integrated using this feature and according resources. The setups have been proven to work in one particular environment; you may need to adapt it to make work in yours.

Tool	Usage
cpplint	Create the rules profile using the profile creator script: python cpplint_createrules.py cpplint.py This will generate the following files: cpplint.xml: that should be copied to web ui as per above and server restarted after save cpplint_mod.py: that should be used to check the code After this you can run the cpplint_mod.py against any source file like this: python cpplint_mod.py source.cpp 2> report.txt The output file report.txt needs to be converted to the XML format described above. For convenience a Perl script is available here and can be run as follows: perl cpplintReport2checkstyleReport.perl report.txt splint-result-0.xml
Intel Inspector XE 2013	Copy the Intel Inspector rules to sonar web ui, as per above and restart server. Modify the used SonarQube quality profile to accommodate the newly added rules Run your test/application using the Intel Inspector and generate a CSV report Convert the report with: python intelInspectorReport_2_cppcheckReport.py in.csv out.xml The out.xml can be then used during the analysis to feed the Intel Inspector results into SonarQube.

Writing your own rules using SSLR, aka custom cxx-rules

You can write custom rules based in SSLR and in Cxx Api, to do this you need to create your own plugin and create a dependency in you pom.xml to the Cxx Plugin version you are using. And extend your checks with CustomCxxRulesDefinition

    <dependency>
      <groupId>org.codehaus.sonar-plugins.cxx</groupId>
      <artifactId>sonar-cxx-plugin</artifactId>
      <type>sonar-plugin</type>
      <version>0.9.5-SNAPSHOT</version>
      <scope>provided</scope>
    </dependency>

Example of a rule

public class MyCustomRulesDefinition extends CustomCxxRulesDefinition {

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

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

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

Installation and usage

Follows a normal procedure for any Sonar plugin, drop in extensions/plugins in you Sonar server and restart. After this enable the rules and run a new analysis.

Sample code

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