In the simplest case, the source code is read in with the programming language sensor of the cxx plugin and transferred via the SonarScanner to SonarQube for analysis.

A programming language sensor takes over the task of splitting the source code into tokens and generating an abstract syntax tree (AST) with the help of a grammer. On the basis of the AST, software metrics and issues are then generated.

In SonarQube, each file extension must be uniquely assigned to one programming language. When operating several C/C++ plugins in parallel, this must be taken into account during configuration (sonar.cxx.file.suffixes).

Hint: Only programming language sensor can read in a source file!

The reading in of source files (indexing) is a prerequisite for the subsequent reading in and visualisation of reports of external tools.

Configuring your project

The SonarScanner is the scanner to use when there is no specific scanner for your build system. Create a configuration file in your project's root directory called sonar-project.properties:

# must be unique in a given instance
sonar.projectKey=my:project

# defaults to project key
#sonar.projectName=My project
# defaults to 'not provided'
#sonar.projectVersion=1.0
 
# Path is relative to the sonar-project.properties file. Defaults to .
#sonar.sources=.
 
# Encoding of the source code. Default is default system encoding
#sonar.sourceEncoding=UTF-8

# mandatory: files to be handled by the _cxx plugin_
sonar.cxx.file.suffixes=.h,.cpp

Running SonarScanner from the zip file

Download the SonarScanner from the website and unpack it (read also prerequisites). Update the global settings to point to your SonarQube Server by editing $install_directory/conf/sonar-scanner.properties:

#----- Default SonarQube server
#sonar.host.url=http://localhost:9000

Java 11 or Java 17 must be used for the cxx plugin, install JDK 11 or later (e.g http://jdk.java.net/archive/). Set the JAVA_EXEC environment variable to the Java version to be used before you start the scanner.

For easier access, you can add $install_directory/bin to the path environment variable. Verify your installation by opening a new shell and executing the command sonar-scanner -h (sonar-scanner.bat -h on Microsoft Windows).

Test with the demo project

In the directory 'Hello World' you will find an sample project that can be used for initial tests. Copy the data into a local directory and run the following command from the project base directory to launch analysis and pass your authentication token:

sonar-scanner -Dsonar.login=myAuthenticationToken

If everything has worked, you should see an output like the one below:

...
17:00:53.401 INFO: Analysis total time: 3.886 s
17:00:53.404 INFO: ------------------------------------------------------------------------
17:00:53.404 INFO: EXECUTION SUCCESS
17:00:53.404 INFO: ------------------------------------------------------------------------
17:00:53.404 INFO: Total time: 5.416s
17:00:53.470 INFO: Final Memory: 23M/481M
17:00:53.471 INFO: ------------------------------------------------------------------------

• To get more information, the debug information can be switched on.
• If scanning is failing, check items listed under Troubleshooting Configuration.
• In the case of incomplete scans, Detect and fix parsing errors gives advice on how to fix this.
• Narrowing the Focus describes several options for configuring exactly what will be analyzed.

The listing below shows an example of the contents of a scanner .LOG file and describes the specific steps. In order to get all required information, the debug information should be switched on during scanning.

In the first section you get information about the used scanner and the properties used by the scanner. Here you can also find the Java version and the version of the SonarQube Server.

01 INFO: SonarScanner 4.5.0.2216
02 INFO: Java 11.0.2 Oracle Corporation (64-bit)
03 INFO: Scanner configuration file: /tmp/sonar-scanner-4.5.0.2216/conf/sonar-scanner.properties
04 INFO: Project root configuration file: /home/projects/cppcheck_sample/sonar-project.properties
05 INFO: Analyzing on SonarQube server 8.7.0

Under Plugins all available plugins are listed including their version number. Here you should also find the cxx plugin (C++ (Community) plugin).

07 DEBUG: Plugins:
08 DEBUG:   * C++ (Community) 2.0.0.1234 (cxx)

The Project key defines the key to be used for the project on the SonarQube Server. Especially important is base dir: all relative paths are resolved relative to this directory.

10 INFO: Project key: cppcheck_sample
11 INFO: Base dir: /home/projects/cppcheck_sample
12 INFO: Working dir: /home/projects/cppcheck_sample/.scannerwork
13 DEBUG: Project global encoding: UTF-8, default locale: en_US

The programming languages available on the SonarQube Server are listed under Available languages. The entries under Declared extensions list the file extensions assigned to a programming language. Each file extension must be uniquely assigned to one programming language.

15 DEBUG: Available languages:
16 DEBUG:   * CXX => "cxx"
17 DEBUG: Declared extensions of language CXX were converted to sonar.lang.patterns.cxx : **/*.cxx,**/*.cpp,**/*.cc,**/*.c,**/*.hxx,**/*.hpp,**/*.hh,**/*.h

The first step in the analysis of a project is always the Indexing files. Here the files are assigned to a programming language on the basis of the file extensions. Files that are not listed here are not displayed in the SonarQube UI. A description of how the files are filtered can be found at Narrowing the Focus.

19 INFO: Indexing files...
20 INFO: Project configuration:
21 DEBUG: 'src/component1.hh' indexed with language 'cxx'
22 DEBUG: 'src/component1.cc' indexed with language 'cxx'
23 DEBUG: 'src/main.cc' indexed with language 'cxx'
24 INFO: 3 files indexed

The step Run sensors on project first checks which sensors should be run. Sensors that are not configured are ignored. Finally a list of sensors follows which are called one after the other during the following steps.

28 INFO: ------------- Run sensors on project
29 DEBUG: 'CXX Bullseye coverage report import' skipped because one of the required properties is missing
30 ...
31 DEBUG: Sensors : CXX -> CXX Cppcheck report import -> Zero Coverage Sensor

Each call to a sensor always starts with Sensor Name and always ends with Sensor Name (done). The cxx plugin has the name 'CXX'. In the example you can see first the metric settings. Under global include directories the directories are listed, which are used by the preprocessor to search include files. global macros shows the macros used by the preprocessor. If there are different values for a unit, the values are shown separately. Then each processed unit is listed with process unit. If an error occurs, it always applies to the previously listed unit.

32 INFO: Sensor CXX [cxx]
33 DEBUG: sonar.cxx.metric.api.file.suffixes: [.hxx, .hpp, .hh, .h]
34 DEBUG: 'Complex Functions' metric threshold (cyclomatic complexity): 10
35 DEBUG: 'Big Functions' metric threshold (LOC): 20
36 DEBUG: global include directories: [/home/projects/cppcheck_sample/src]
37 DEBUG: global macros: [{__STDC__:1}, {__TIME__:"??:??:??"}, {__STDC_HOSTED__:1}, {__FILE__:"file"}, {__DATE__:"??? ?? ????"}, {__has_include:1}, {__cplusplus:201103L}, {__LINE__:1}]
38 DEBUG: process unit '/home/projects/cppcheck_sample/src/component1.hh'
39 DEBUG: 'Public API' metric for 'component1.hh': total=3, undocumented=3
40 DEBUG: process unit '/home/projects/cppcheck_sample/src/component1.cc'
41 DEBUG: process unit '/home/projects/cppcheck_sample/src/main.cc'
42 INFO: Sensor CXX [cxx] (done) | time=808ms

If the analysis and reading of the reports was successful, there is an EXECUTION SUCCESS at the end .of the .LOG file. More information about importing report files can be found under Scan Report Files.

44 INFO Analysis total time: 11.435 s
45 INFO: ------------------------------------------------------------------------
46 INFO: EXECUTION SUCCESS
47 INFO: ------------------------------------------------------------------------
48 INFO: Total time: 13.426s
49 INFO: Final Memory: 7M/27M
50 INFO: ------------------------------------------------------------------------