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

Define those rules using the XML format described further below in a temporary file.
Paste the content of file into the relevant configuration property in the SonarQube server. For example for cppcheck.
Restart the SonarQube server (This is the drawback of this method).
Make sure the newly added rules are visible in the quality profile; enable them
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>

     <!-- optional fields -->
     <description>
       <![CDATA[The description]]>
     </description>
     <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>

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.

Locate the relevant custom rule for the code checker you want to extend.
Press create and fill in the details
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:

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
Run your checker and create a report

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly