Inria SonarQubeTM portalThis document explains how to use the SonarQubeTM platform.
The goal of this user guide is mainly to:
To know more about SonarQubeTM usage please refer to the official documentation of SonarQubeTM.
SonarQubeTM 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. SonarCloudTM is a freely available instance of SonarQubeTM 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.
Warning: this service is not meant to host risky confidential data (see intranet).
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#, CSS, CXX, Flex, Go, Groovy, HTML, JSP, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Scala, Shell, TypeScript, VB.NET, XML, YAML.
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:
Here some rules to maintain the platform in a good health and to minimize the administrators work.
The workflow to use SonarQubeTM and get quality measurement on a source code is the following:
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.
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.
The sonar-scanner program allows you to:
sonar-project.properties file later.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.
You may add sonar-scanner-VERSION/bin in your PATH environment
wget https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-4.7.0.2747-linux.zip
unzip sonar-scanner-cli-4.7.0.2747-linux.zip
export PATH=$PWD/sonar-scanner-4.7.0.2747-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
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
If SonarQubeTM is the only instance you will use then you should certainly tell your sonar-scanner program to publish exclusively on this web server.
$SONAR_ROOT/conf by setting the url as follows:#sonar.host.url=http://localhost:9000
sonar.host.url=https://sonarqube.inria.fr/sonarqube
cd CODE_SRC; touch sonar-project.properties
| 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.projectKey: identified the project on SonarQubeTM (must be unique on the instance). We ask users to respect a format in order to avoid projects being lost or overwritten. The key must begins as follows "name of the inria team:name of the project", e.g. tadaam:hwloc.
In case of multi-teams projects, the following rule must be applied :
sonar.projectName: please don't set it, the name will be the sonar.projectKey
Example template of sonar-project.properties
# url of the SonarQube<sup>TM</sup> server
sonar.host.url=https://sonarqube.inria.fr/sonarqube
# login/password mechanism required to transmit the analysis to the SonarQube<sup>TM</sup> server (password must be left empty with the token usage)
sonar.login=bb3797ac5a0d24b1cb9693274ff3fe93a1cd26a8
# must be unique in a given SonarQube<sup>TM</sup> instance
sonar.projectKey=sedbso:heat
# the current git ref (e.g. branch) being analyzed
sonar.branch.name=develop
# to add a link to the homepage
sonar.links.homepage=https://gitlab.inria.fr/sed-bso/heat
# to add a link to the homepage
sonar.links.scm=https://gitlab.inria.fr/sed-bso/heat.git
# small description of the project
sonar.projectDescription=Solve the heat propagation equation
# used to compare metrics with v1.0 for example
sonar.projectVersion=2.0
# to get git blame information such as the commit author line by line
sonar.scm.disabled=false
sonar.scm.provider=git
sonar.sourceEncoding=UTF-8
# Path is relative to the sonar-project.properties file. Replace "\" by "/" on Windows.
sonar.sources=.
# exclude some files from being analyzed
sonar.exclusions=build/CMakeFiles/**,cmake_modules/**,doc/**,formation/**,tools/**,**/*.html,**/*.xml,**/*.css
# clarify what is c and c++ files
sonar.cxx.file.suffixes=.h,.c # https://github.com/SonarOpenCommunity/sonar-cxx/wiki/sonar.cxx.file.suffixes
sonar.cxx.errorRecoveryEnabled=true
sonar.cxx.includeDirectories=/usr/lib/gcc/x86_64-linux-gnu/9/include,/usr/local/include,/usr/include/x86_64-linux-gnu,/usr/include,/usr/lib/x86_64-linux-gnu/openmpi/include,include,.
sonar.cxx.gcc.encoding=UTF-8
sonar.cxx.gcc.regex=(?<file>.*):(?<line>[0-9]+):[0-9]+:\\\x20warning:\\\x20(?<message>.*)\\\x20\\\[(?<id>.*)\\\]
sonar.cxx.gcc.reportPaths=build/heat-build.log
sonar.cxx.clangsa.reportPaths=build/analyzer_reports/*/*.plist
sonar.cxx.clangtidy.reportPaths=clang-tidy-report
sonar.cxx.cobertura.reportPaths=heat-coverage.xml
sonar.cxx.cppcheck.reportPaths=heat-cppcheck.xml
sonar.cxx.rats.reportPaths=heat-rats.xml
sonar.cxx.vera.reportPaths=heat-vera.xml
sonar.cxx.valgrind.reportPaths=heat-valgrind.xml
sonar.cxx.xunit.reportPaths=report.xml
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.
You can explore:
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
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.
The Quality Profile (QP) in SonarQubeTM 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 SonarQubeTM. 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.
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.
For instance a specific pattern may be checked for license header. The default SonarQubeTM pattern can be changed to your regular expression (set isRegularExpression to true), e.g.
/\*\*.+\* @file.+\* @copyright Copyright \(c\) [0-9]{4}, Inria.+\* @author Inria SED Bordeaux
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 SonarQubeTM 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 SonarQubeTM 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 |
We give installation instructions for analysis tools that are considered in the next section.
sudo apt install -y git subversion mercurial
sudo apt install -y build-essential gfortran clang python3 python3-pip
sudo apt install -y gcovr lcov cppcheck vera++ valgrind libexpat1-dev
pip install --upgrade pip
sudo pip install pytest pytest-cov coverage scan-build
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
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 SonarQubeTM:
wget https://github.com/eriwen/lcov-to-cobertura-xml/archive/1.6.tar.gz
tar xvf 1.6.tar.gz
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
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 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.
Run cppcheck generating a SonarQubeTM 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:
cppcheck
--errorlist to get the listAdd the cppcheck output file inside the sonar-project.properties
file of your project
sonar.cxx.cppcheck.reportPaths=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.reportPaths'
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
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.reportPaths=analyzer_reports/*/*.plist
During the sonar-scanner analysis, you should observe something like the following
INFO: Sensor CXX Clang-Tidy report import [cxx] (done) | time=2ms
INFO: Sensor CXX Clang Static Analyzer report import [cxx] (done)
INFO: Searching reports by relative path with basedir '/home/gitlab-runner/builds/7cb15692/0/sed-bso/heat' and search prop 'sonar.cxx.clangsa.reportPaths'
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
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.reportPaths=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.reportPaths'
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++ 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.reportPaths=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.reportPaths'
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 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
using gcovr
# gcov files are created by default at the level of object
# files. To help SonarQube<sup>TM</sup> 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
using lcov
# gcov files are created by default at the level of object
# files. To help SonarQube<sup>TM</sup> 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<sup>TM</sup>. 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.cobertura.reportPaths=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 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/.
first you need to enable debug information with the flag -g and add also -fno-inline for C++ apps.
make clean
export CFLAGS="-O0 -g -fPIC --coverage -Wall -fno-inline"
$PWD/configure
make V=1
call valgrind as usual and dump the result using the xml format
valgrind --xml=yes --xml-file=valgrind.xml ./myapp args_to_myapp
add the valgrind output file inside the
sonar-project.properties file of your project
sonar.cxx.valgrind.reportPaths=valgrind.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 CxxValgrindSensor
INFO: Searching reports by relative path with basedir '/home/ci/tests/c_examples/leak_test' and search prop 'sonar.cxx.valgrind.reportPaths'
INFO: Scanner found '1' report files
INFO: Parser will parse '1' report files
INFO: Processing report '/home/ci/tests/c_examples/leak_test/valgrind.xml'
INFO: Valgrind errors processed = 1
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
We give here an example of analysis integration on the papriK Python project.
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
SonarQubeTM 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.sources=./paprik/
sonar.sourceEncoding=UTF-8
sonar.python.xunit.reportPaths=utest.xml
sonar.python.coverage.reportPaths=coverage.xml
# links that will be displayed by icons within the SonarQube<sup>TM</sup> 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
Most of the following lines are extracted from the online documentations (https://www.sonarqube.com, https://docs.sonarqube.org/latest/user-guide/metric-definitions/)