Documentation

Table of Contents

  1. Generalities about the SonarQube platform
  2. Installation, configuration and conventions
    1. Create your account on the SonarQube server
      1. Sign in
      2. Create a token
    2. Install sonar-scanner on your local machine
      1. Download
      2. Inria's trusted SSL Certificate
      3. Configure the sonar-scanner properties file (optional)
    3. Run sonar-scanner on your code
      1. Configure the project properties file
      2. Run sonar-scanner
    4. Explore the results
      1. Log in using your login/password
      2. Navigate through the analysis elements
      3. Permissions on projects, become administrator
      4. Visibility of your project
      5. Manage issues (Quality Profile)
  3. Carry on
    1. Install tools if needed (may already exist on your system)
      1. Install Debian packages
      2. Additional analysis tools installation for C/C++ code (optional)
    2. Execute analysis
      1. cppcheck
      2. Clang SA
      3. RATS
      4. Vera++
      5. Gcov
      6. Valgrind
      7. Python tools
    3. Adding information about your project
      1. Insert your project information (links) in the project properties file
  4. SonarQube terminology

This document explains how to use the SonarQube@Inria platform.

The goal of this user guide is mainly to:

To know more about SonarQube usage please refer to the official documentation of SonarQube.

Generalities about the SonarQube platform

SonarQube is mainly a web server providing some dashboards that help assessing the quality of programs. Many things can be reported: size of source code, detection of duplication, issues based on static and dynamic analyzers, coverage data, etc.

There exists different versions released: one is open source, free but with limited features and some others are charged, see Plans & Pricing. SonarCloud is a freely available instance of SonarQube for open source projects. However it is charged for private projects.

After some experiments with the open source Community Edition version we have concluded that it meets requirements for most Inria usage. We host an instance on a virtual machine managed by the DSI and the SED of Inria. The url of the service is : https://sonarqube.inria.fr/sonarqube. This is a Community Edition LTS. Here is the list of plugins installed: Installed Plugins. To get more plugins installed please contact the support team. Languages that can be analyzed are: C, C++, C#, Java, JavaScript, TypeScript, Flex, Fortran, Python, PHP, Web & XML.

Without being logged only public projects are displayed. Any user is able to explore metrics and source code of public projects. This platform allows people with an Inria account to analyze their project. People with no Inria account will be able to join existing projects. Once logged users can:

Somme rules to maintain the platform in a good health and to minimize the administrators work.

Installation, configuration and conventions

The workflow to use SonarQube and get quality measurement on a source code is the following:

  1. Analyze the source code on your computer. Tools such as clang static analyzer, cppcheck, gcovr, valgrind, pylint, pytest, etc may be used to produce reports. Then sonar-scanner will do its own analysis and collect reports of other tools.
  2. The same sonar-scanner will publish the results on the web server, the authentication can be done with a secret user's token.

We now present how to authenticate, generate the secret token and install the sonar-scanner program. Static and dynamic analysis of C/C++ and Python programs will be covered in the next section.

Create your account on the SonarQube server

Sign in

Create a token

This token will be useful to authenticate to the instance replacing authentication with the login/password pair. It will be used with sonar-scanner to publish results on a project. Notice the token is per user, not per project. It is not meant to be shared between users. Of course to automatize analysis in a CI (continuous integration) process one token will be used on some machines shared by administrators of the CI. Try to be serious and keep it safe.

Install sonar-scanner on your local machine

The sonar-scanner program allows you to:

NB: the following installation steps are valid for a Linux Debian operating system. Please find the appropriate equivalent steps for your OS if different and visit the sonar-scanner main page.

Download

You may add sonar-scanner-VERSION/bin in your PATH environment

wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-4.4.0.2170-linux.zip
unzip sonar-scanner-cli-4.4.0.2170-linux.zip
export PATH=$PWD/sonar-scanner-4.4.0.2170-linux/bin:$PATH

And voilĂ !

The connection with the server will be established with https protocol to submit results so that a certificate must be set.

Tip for Mac OS: prefer the brew package

Inria's trusted SSL Certificate

Download the file digicertca.crt or ask the support to get it. Then the certificate must be added to the keystore of the java environment used by sonar-scanner

# we consider sonar-scanner installed in SONAR_ROOT
keytool -import -alias inria -storepass "changeit" -keystore $SONAR_ROOT/jre/lib/security/cacerts -file digicertca.crt

Configure the sonar-scanner properties file (optional)

If SonarQube@Inria is the only instance you will use then you should certainly tell your sonar-scanner program to publish exclusively on this web server.

Run sonar-scanner on your code

Configure the project properties file

Property Name Definition Mandatory Examples
sonar.host.url url of the server yes https://sonarqube.inria.fr/sonarqube
sonar.login user's token yes bb3797ac5a0d24b1cb9693274ff3fe93a1cd26a8
sonar.projectKey project's key/name yes team:project:dev, team:project:release:2.0
sonar.projectName project's name no same as key
sonar.projectVersion see Leak Period no 1.0, 2.2, etc
sonar.sources paths to sources yes ., ./build
sonar.language language of sources no c, c++, py, etc

Example template of sonar-project.properties

# url of the SonarQube server
sonar.host.url=https://sonarqube.inria.fr/sonarqube
# login/password mechanism required to transmit the analysis to the sonarqube server (password must be left empty with the token usage)
sonar.login=bb3797ac5a0d24b1cb9693274ff3fe93a1cd26a8
# must be unique in a given SonarQube instance
sonar.projectKey=tadaam:hwloc:github:v1.11
# used to compare metrics with v1.10 for example
sonar.projectVersion=1.11
# Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.
sonar.sources=.
# Source code language
sonar.language=c

Run sonar-scanner

cd CODE_SRC; sonar-scanner

You should get at the end

INFO: EXECUTION SUCCESS

Some properties can also be directly given to sonar-scanner

sonar-scanner -X -Dsonar.host.url=https://sonarqube.inria.fr/sonarqube -Dsonar.login=THE_TOKEN_YOU_GET

-X flag is used to get DEBUG information.

Explore the results

Log in using your login/password

Navigate through the analysis elements

You can explore:

Permissions on projects, become administrator

By default, you don't have access to the source of the private codes (obvious). The way to control who can see the source code, have access to issues, etc, is to be administrator of the project. By default it is the user who performs and submits the first analysis of a project who becomes its administrator. To get permission grants on a project, ask to one existing administrators or send an email to the support with the following information : project name (key) and the permissions granted for each user. Permissions list is the following: Browse, See Source Code, Administer Issues, Administer, Execute Analysis. Example

Visibility of your project

By default new projects visibility is set to Private such that anyone is not able to see your project and authenticate users only see general metrics and not the source code. To make your project public you have to be administrator of the project and go to the Administration panel of your project, select Permissions and select the "Public" button. Once public your code source and issues will be visible from anyone.

Manage issues (Quality Profile)

The Quality Profile (QP) in SonarQube is used to manage rules that will be considered when uploading the reports sent by sonar-scanner. It is possible to activate/deactivate issues in a specific QP and associate this QP to some projects.

By default the QP used is "Sonar Way", a default configuration given by SonarQube. All existing rules are not activated. We have created an "Inria" QP with the maximum number of rules activated and it is used by default for C, C++ and Python projects.

The administrators of a project can change the QP associated with their project. On the other hand they are not allowed to create new QPs. To get a new QP, users will have to send an email to the support with the following information

Then these users will be able to manage issues that are activated or not and can associate projects they administer with this new QP.

Carry on

We detail here how to use existing tools to analyze C/C++ and Python projects. The goal here is neither to rewrite the documentation about analysis tools nor to replace SonarQube plugins ones. We will give useful pointers and some usage examples. It is not meant to be exhaustive. Please refer to the appropriate existing documentation to go further. Notice that we aim at analyzing mainly C/C++ and Python source code (our use cases) so that we focus on analysis tools that are compatible with the SonarQube plugins. To get more information about plugins please read

We sum up here some analysis tools that can be used with the associated languages

Tool Analysis Type Languages
cppcheck static C/C++
clang-sa static C/C++
RATS static C/C++
vera++ static C/C++
GCOV dynamic C/C++
Valgrind dynamic C/C++
Pylint static Python
pytest(-cov) dynamic Python

Install tools if needed (may already exist on your system)

We give installation instructions for analysis tools that are considered in the next section.

Install Debian packages

sudo apt install -y git subversion mercurial
sudo apt install -y build-essential gfortran clang python2.7 python-pip
sudo apt install -y gcovr lcov cppcheck vera++ valgrind libexpat1-dev
pip install --upgrade pip
sudo pip install pytest pytest-cov coverage==3.7.1 scan-build

Additional analysis tools installation for C/C++ code (optional)

  1. RATS

    version_rats=2.4
    wget https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/rough-auditing-tool-for-security/rats-${version_rats}.tgz
    tar -xzvf rats-${version_rats}.tgz
    cd rats-${version_rats}
    ./configure && make && sudo make install
    
  2. Gcov

    Gcov is distributed directly with GCC (for example with the Debian package build-essential)

    sudo apt install -y gcovr lcov
    

    There are at least two ways to produce an xml output which is compatible with SonarQube:

  3. Dr. Memory

    version_drmemory=1.11.0-2
    echo 'export version_drmemory=1.11.0-2' >> ~/.bashrc
    sudo apt install -y g++-multilib
    wget https://github.com/DynamoRIO/drmemory/releases/download/release_1.11.0/DrMemory-Linux-${version_drmemory}.tar.gz
    tar xvf DrMemory-Linux-${version_drmemory}.tar.gz
    cd DrMemory-Linux-${version_drmemory}/bin
    export PATH=$PWD:$PATH
    echo 'export PATH=/home/ci/DrMemory-Linux-${version_drmemory}/bin:$PATH' >> ~/.bashrc
    

Execute analysis

Here are usage example of some analysis tools. Once again to see a complete list of possibilities, users should refer to the existing documentations

cppcheck

Cppcheck is an analysis tool for C/C++ code. Unlike C/C++ compilers and many other analysis tools, it doesn't detect syntax errors. Instead, Cppcheck detects the types of bugs that the compilers normally fail to detect. The goal is no false positives.

Manual

Run cppcheck generating a sonarqube compatible output. Note that the result is dumped in the error output.

cd CODE_SRC
export CPPCHECK_INCLUDES="-Iinclude"
export SOURCES_TO_ANALYZE="src tests utils"
export SOURCES_TO_EXCLUDE="-isrc/beta"
export DEFINITIONS=`grep "^#define" config.log | sed -e "s#\#define #-D#g" | sed -e "s# #=#g" | xargs`
cppcheck -v -f --language=c++ --platform=unix64 --enable=all --xml --xml-version=2 --suppress=missingIncludeSystem ${DEFINITIONS} ${CPPCHECK_INCLUDES} ${SOURCES_TO_EXCLUDE} ${SOURCES_TO_ANALYZE} 2> cppcheck.xml

Parameters:

Add the cppcheck output file inside the sonar-project.properties file of your project

sonar.cxx.cppcheck.reportPath=cppcheck.xml

For C project (and not C++) you should replace sonar.cxx by sonar.c.

During the sonar-scanner analysis, you should observe something like the following

INFO: Sensor CxxCppCheckSensor (wrapped)
INFO: Searching reports by relative path with basedir '/home/ci/hpclib/scan/scan_build/starpu-1.2.0' and search prop 'sonar.cxx.cppcheck.reportPath'
INFO: Scanner found '1' report files
INFO: Parser will parse '1' report files
INFO: Processing report '/home/ci/hpclib/scan/scan_build/starpu-1.2.0/starpu-cppcheck.xml'
INFO: Added report '/home/ci/hpclib/scan/scan_build/starpu-1.2.0/starpu-cppcheck.xml' (parsed by: CppcheckParserV2)
INFO: CppCheck Errors processed = 15760

Clang SA

The Clang Static Analyzer is a source code analysis tool that finds bugs in C, C++, and Objective-C programs.

You should have the Python program scan-build installed, use it before your make command

scan-build -plist --intercept-first --analyze-headers -o analyzer_reports make

Add the path to reports in sonar-project.properties

sonar.cxx.clangsa.reportPath=analyzer_reports/*/*.plist

For C project (and not C++) you should replace sonar.cxx by sonar.c.

During the sonar-scanner analysis, you should observe something like the following

INFO: Sensor c ClangTidySensor [c] (done) | time=2ms
INFO: Sensor c ClangSASensor [c]
INFO: Searching reports by relative path with basedir '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat' and search prop 'sonar.c.clangsa.reportPath'
INFO: Scanner found '5' report files
INFO: Parser will parse '5' report files
INFO: Processing report '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat/build/analyzer_reports/scan-build-2018-02-01-12-37-21-377840-Ouvcnk/report-HU5PQ8.plist'
INFO: Processing report '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat/build/analyzer_reports/scan-build-2018-02-01-12-37-21-377840-Ouvcnk/report-LHW7sT.plist'
INFO: Processing report '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat/build/analyzer_reports/scan-build-2018-02-01-12-37-21-377840-Ouvcnk/report-S6r5Ym.plist'
INFO: Processing report '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat/build/analyzer_reports/scan-build-2018-02-01-12-37-21-377840-Ouvcnk/report-VtZcxV.plist'
INFO: Processing report '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat/build/analyzer_reports/scan-build-2018-02-01-12-37-21-377840-Ouvcnk/report-rdY0BL.plist'
INFO: C-CLANGSA processed = 1

RATS

Rough Auditing Tool for Security, see https://security.web.cern.ch/security/recommendations/en/codetools/rats.shtml

export SOURCES_TO_ANALYZE="src"
rats -w 3 --xml ${SOURCES_TO_ANALYZE} > rats.xml

-w 3 stands for the warning level (<1,2,3>)

Add the rats output file inside the sonar-project.properties file of your project

sonar.cxx.rats.reportPath=rats.xml

For C project (and not C++) you should replace sonar.cxx by sonar.c.

During the sonar-scanner analysis, you should observe something like the following

INFO: Sensor CxxRatsSensor (wrapped)
INFO: Searching reports by relative path with basedir '/home/ci/hpclib/scan/scan_build/starpu-1.2.0' and search prop 'sonar.cxx.rats.reportPath'
INFO: Scanner found '1' report files
INFO: Parser will parse '1' report files
INFO: Processing report '/home/ci/hpclib/scan/scan_build/starpu-1.2.0/starpu-rats.xml'
INFO: RATS issues processed = 894

Vera++

Vera++ is a programmable tool for verification, analysis and transformation of C++ source code, see https://bitbucket.org/verateam/vera/wiki/Home.

This program raises mainly stylistic issues which improve the clarity and the readability of C/C++ codes, cf. https://bitbucket.org/verateam/vera/wiki/Rules. Use it or not use it is a matter of preference. It is just good to know that it exists.

# download sources of the sonar-cxx plugin: a script inside the
# project allows to convert vera++ output to an xml report
cd ~
git clone https://github.com/SonarOpenCommunity/sonar-cxx.git
# process the analysis
export SOURCES_TO_ANALYZE="src"
bash -c 'find ${SOURCES_TO_ANALYZE} -regex ".*\.c\|.*\.h" | vera++ - -showrules -nodup |& ~/sonar-cxx/sonar-cxx-plugin/src/tools/vera++Report2checkstyleReport.perl > vera.xml'

Add the vera++ output file inside the sonar-project.properties file of your project

sonar.cxx.vera.reportPath=vera.xml

For C project (and not C++) you should replace sonar.cxx by sonar.c.

During the sonar-scanner analysis, you should observe something like the following

INFO: Sensor CxxVeraxxSensor
INFO: Searching reports by relative path with basedir '/home/ci/hpclib/scan/scan_build/hwloc-1.11.6' and search prop 'sonar.cxx.vera.reportPath'
INFO: Scanner found '1' report files
INFO: Parser will parse '1' report files
INFO: Processing report '/home/ci/hpclib/scan/scan_build/hwloc-1.11.6/vera.xml'
INFO: Vera++ rule violations processed = 12411

Gcov

gcov is a tool you can use in conjunction with GCC to test code coverage in your programs.

First you need to add the flag –coverage to the GCC compiler flags (we recommend some others) and to the linker flags

make clean
export CFLAGS="-O0 -g -fPIC --coverage -Wall"
export LDFLAGS="--coverage"
$PWD/configure
make V=1

Execute your tests

make check

Some .gcno and .gcda files should be created in the different build directories.

It is now time to collect the data and generate the report file

  1. using gcovr

    # gcov files are created by default at the level of object
    # files. To help sonarqube to retrieve the good paths it may
    # be needed to move gcov files at the same level as sources
    mv tests/ports/.libs/*.gcno tests/ports/
    mv src/.libs/*.gcno src/
    mv src/.libs/*.gcda src/
    # collect the data and generate the report
    gcovr -r . --xml > gcov.xml
    
  2. using lcov

    # gcov files are created by default at the level of object
    # files. To help sonarqube to retrieve the good paths it may
    # be needed to move gcov files at the same level as sources
    mv tests/ports/.libs/*.gcno tests/ports/
    mv src/.libs/*.gcno src/
    mv src/.libs/*.gcda src/
    # collect the coverage data
    lcov --directory . --capture --output-file project.lcov
    # generate the classical html lcov page that can be published
    # on the web
    genhtml -o coverage project.lcov
    # convert the lcov report to an xml format convertible with
    # SonarQube. The python script lcov_cobertura.py, see
    # https://github.com/eriwen/lcov-to-cobertura-xml, is required
    lcov_cobertura.py project.lcov --output gcov.xml
    

Add the gcov output file inside the sonar-project.properties file of your project

sonar.cxx.coverage.reportPath=gcov.xml

For C project (and not C++) you should replace sonar.cxx by sonar.c.

During the sonar-scanner analysis, you should observe the following

DEBUG: Parsing coverage reports
DEBUG: Normalized report includes to '[/home/ci/hpclib/scan/scan_build/hwloc-1.11.6/hwloc-coverage.xml]'
INFO: Scanner found '1' report files
INFO: Parser will parse '1' report files
DEBUG: Parsing 'Cobertura' format
INFO: Added report '/home/ci/hpclib/scan/scan_build/hwloc-1.11.6/hwloc-coverage.xml' (parsed by: CoberturaParser) to the coverage data
DEBUG: cached measures for '/home/ci/hpclib/scan/scan_build/hwloc-1.11.6/hwloc-coverage.xml' : current cache content data = '0'
DEBUG: Saving '64' coverage measures for file '/home/ci/hpclib_fp/scan/scan_build/hwloc-1.11.6/tests/hwloc_groups.c'
...

Valgrind

Valgrind is an instrumentation framework for building dynamic analysis tools. There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. See http://valgrind.org/.

The case of MPI applications: to avoid many false positive try using the suppression files that are distributed with MPI, for example for OpenMPI

export OPENMPI_DIR=path/to/mpi
$OPENMPI_DIR/bin/mpirun "-np" "4" valgrind --xml=yes --xml-file=valgrind.xml --suppressions=$OPENMPI_DIR/share/openmpi/openmpi-valgrind.supp ./myapp args_to_myapp

Python tools

We give here an example of analysis integration on the papriK Python project.

  1. Python tests and coverage

    # choose either xml or html coverage report
    py.test --junit-xml=./utest.xml --cov-report xml --cov-report term-missing --cov-config .coveragerc --cov paprik/ paprik paprik/tests
    py.test --junit-xml=./utest.xml --cov-report html --cov-report term-missing --cov-config .coveragerc --cov paprik/ paprik paprik/tests
    
  2. SonarQube config file

    The sonar-project.properties file

    sonar.links.homepage=https://gitlab.inria.fr/monc/paprik
    sonar.links.ci=https://gitlab.inria.fr/monc/paprik/pipelines
    sonar.links.scm=https://gitlab.inria.fr/monc/paprik.git
    sonar.projectKey=monc:paprik:gitlab:master
    sonar.projectVersion=1.0
    sonar.language=py
    sonar.sources=./paprik/
    sonar.sourceEncoding=UTF-8
    #sonar.python.pylint=/usr/bin/pylint
    #sonar.python.pylint.reportPath=paprik_pylint.txt
    sonar.python.xunit.reportPath=utest.xml
    sonar.python.coverage.reportPath=coverage.xml
    

Adding information about your project

Insert your project information (links) in the project properties file

# links that will be displayed by icons within the sonarqube dashboard
sonar.links.homepage=THE_MAIN_ENTRY_OF_THE_CODE
sonar.links.scm=THE_SCM_PROJECT_LINK
sonar.links.ci=THE_CI_PROJECT_CI
sonar.links.issue=THE_PROJECT_BUG_TRACKER

SonarQube terminology

Most of the following lines are extracted from the online documentations (https://www.sonarqube.com, https://docs.sonarqube.org/latest/user-guide/metric-definitions/)

links

social