This article is out of date for Understand 6.
Version of Document: V1.0 Author: Stephane Raynaud, Emenda USA ([[email protected]](mailto:[email protected]))
Tested with Version 4.0 of SciTools Understand ( Build 867 )
1. Objectives
This document presents a basic integration of SciTools Understand CodeCheck and SonarQube. The integration requires two scripts that you must get from Emenda USA by emailing [email protected] (create_sonarqube-cxx-external-rules.pl and create_sonarqube-cxx-report-from-scitools-analyis.pl).
The integration allows you to display all the code violations found by SciTools Understand CodeCheck as SonarQube Issues and automatically update those.
You will be able to automate the process of updating the issues, by using a command line script. The script follows the following steps:
- Run an Understand Analysis (optional) from the command line.
- Run CodeCheck from the command line.
- Convert CodeCheck violations to SonarQube CXX Issues from the command line.
- The Violations will be picked up when running sonar-scanner automatically.
Interested? let’s get to work!
2. Pre-Requisites
Before we start, you will need:
- An Installation of SonarQube 5.6.3 (Later version are not supported because of incompatibilities with the Community C++ plugin)
- C++ Community Plugin (version 0.9.6)
- You will need admin access to the SonarQube
- You will need to restart your SonarQube Server
Hint: Installing the C++ Plugin.
- Download sonar-cxx-plugin-0.9.6.jar from Release V0.9.6 · SonarOpenCommunity/sonar-cxx · GitHub ( bottom of page )
- Copy it into SONARQUBE_HOME/extensions/plugins
- Restart the SonarQube server
- Navigate to the Update Center (/updatecenter). The Update Center should list “C++ ( Community )” on the tab “Installed Plugins”:
- By default, the “admin” login is admin/admin…
3. Setting up in SciTools.
In a first step, we are going to
- create a UDB file
- export the Checks from SciTools to create an XML file that is loaded in SonarQube CXX plugin as Rules.
We are basically teaching SonarQube about SciTools Checks.
This must be done only once.
3.1. Building Your Project SciTools Database
Before you do anything, you will need to create a udb database later used for your analysis. The only requirement is that the database must be using a named root for portability and this root must be the root of the project, i.e., the place where one can fine the “sonar-project.properties” file.
Hint: Using a Named Root for Portability in SciTools Understand
a) Open your project settings in SciTools Understand (Project->Configure Project)
(Alternatively, you can do this when you create the projects and add files to it)
Note: It is always a good idea to use named root when creating udb files. It provides better portability between developers (they don’t all have their source code at the same place). Named Root lets you define an “environment variable” that defines the ROOT of your project.
b) Select Files
c) On the right of the window, click “Portability”
d) Select “NamedRoot”
e) Lastly, add a “Named Root” using the “Edit Named Roots…” button on the bottom left. In my example, I define a LIBFREENECT2_ROOT for the root of my project, and it points to C:\Users\steph_000\Desktop\DEMOS\SonarQube\demo_project\libfreenect2-master.
This is the only restriction on the udb file.
3.2. Exporting ALL the SciTools Checks
Now we need to “teach” SonarQube about the SciTools Checks. But before we can do this, we need to extract a list of checks from SciTools.
To do this, Open CodeCheck in your udb file.
Select All the checks available (Yes!!! All of them!!!) - This is not the checks you will use in your analysis. We want SonarQube to learn about all the Checks .
On the Top Right Corner, Select “Export Selected Checks to Text File”. Let’s name this file ALL.txt.
WARNING: DO NOT USE “Export Configuration to a File”.
It’s easy to get the two confused!!!
If you open the exported file, it should look like this:
CodeCheck Checks
SciTools’ Recommended Checks"Commented Out" Code
Description: Sections of code should not be “commented out”.
SciTools’ Recommended Checks\Definitions in Header Files
Description: Objects and Functions should not be defined in Header Files.
SciTools’ Recommended Checks\Files too long
Description: Program files should not have more than the specified number of lines
SciTools’ Recommended Checks\Floating-point expressions shall not be directly or indirectly tested for equality or inequality.
Description: (Required) Floating-point expressions shall not be directly or indirectly tested for equality or inequality.
4. Translating SciTools Information into something SonarQube can read.
We are now ready to use the script “create_sonarqube-cxx-external-rules.pl” provided by Emenda USA.
Hint: Use the perl installation from SciTools
SciTools comes with a perl installation, so why use anything else? The command to run a perl command is uperl. On my plaform is was located in \bin\pc-win64.
It is a good idead to add it to your path!
Now Run the following command:
uperl create_sonarqube-cxx-external-rules.pl .\ALL.txt .\ALL.xml .\ALL.xml.key
- ALL.txt is the file you exported earlier from SciTools
- The ALL.xml and ALL.xml.key files that will be created.
- ALL.xml will be imported in SonarQube later, and ALL.xml.key will be used at a later stage.
I processed 640 rules
<rules>
<rule>
<key>SCITOOLS_0</key>\>
<name><![CDATA[SciTools Check: SciTools' Recommended Checks\"Commented Out" Code]]></name>
<description><![CDATA[SciTools Check (0): Description: Sections of code should not be "commented out".]]></description>
<descriptionFormat>HTML</descriptionFormat>
<severity>BLOCKER</severity>
<cardinality>SINGLE</cardinality>
<status>BETA</status>
<type>BUG</type>
</rule>
<rule>
<key>SCITOOLS_1</key>
<name><![CDATA[SciTools Check: SciTools' Recommended Checks\Definitions in Header Files]]></name>
<description><![CDATA[SciTools Check (1): Description: Objects and Functions should not be defined in Header Files.]]></description>
<descriptionFormat>HTML</descriptionFormat>
<severity>BLOCKER</severity>
<cardinality>SINGLE</cardinality>
<status>BETA</status>
<type>BUG</type>
</rule>
Hint: Limitation of Script
You will notice that the ALL.xml declares all the Checks with a severity of BLOCKER, a status of BETA and a type of BUG. You may modify the script “create_sonarqube-cxx-external-rules.pl” to change how they are declared and/or edit the output XML manually. The possible values are respectively “INFO, MINOR, MAJOR (default), CRITICAL, BLOCKER” for severity, “BETA, READY (default), DEPRECATED.” For status and “CODE_SMELL (default), BUG and VULNERABILITY” for type.
ALL.xml.key should look like something like this:
SCITOOLS_0%5CSciTools' Recommended Checks\"Commented Out" Code
SCITOOLS_1%5CSciTools' Recommended Checks\Definitions in Header Files
SCITOOLS_2%5CSciTools' Recommended Checks\Files too long
SCITOOLS_3%5CSciTools' Recommended Checks\Floating-point expressions shall not be directly or indirectly tested for equality or inequality.
SCITOOLS_4%5CSciTools' Recommended Checks\Functions Too Long
SCITOOLS_5%5CSciTools' Recommended Checks\Functions shall not be declared implicitly
SCITOOLS_6%5CSciTools' Recommended Checks\Goto Statements
SCITOOLS_7%5CSciTools' Recommended Checks\Macros shall not be #define'd or #undef'd within a block
SCITOOLS_8%5CSciTools' Recommended Checks\Magic Numbers
SCITOOLS_9%5CSciTools' Recommended Checks\Nested Comments
SCITOOLS_10%5CSciTools' Recommended Checks\Overly Complex Functions
SCITOOLS_11%5CSciTools' Recommended Checks\Trigraphs shall not be used
5. Installation of Rules in SonarQube
The next step is to import that xml file into the SonarQube installation. To do so, go to
http://<SONARQUBE>/ settings?category=c%2B%2B+%28community%29&subcategory=%282%29+code+analysis (alternatively, go to http://<SONARQUBE>/
then click Administration (you must be log as an admin) (Top), then C++ Community (Left), The Code Analysis (Kind of on Top))
Your browser should look like this: