Description / Features
This plugin adds basic support of C++ language into Sonar.
Current feature list:
- Basic size metrics:
- Files (number of)
- Lines of comments
- Lines of code
- Lines of commented out code
- Static code checking via Cppcheck, RATS and Vera++
- Dynamic checking for memory management problems via Valgrind
- Cyclomatic (McCabe) complexity metrics including:
- Projects complexity
- Average function/method complexity
- Average file complexity
- Complexity distributions
- Code coverage metrics including:
- Line coverage
- Branch coverage
- An aggregated coverage measure
- (>0.2 SNAPSHOT) IT line coverage
- (>0.2 SNAPSHOT) IT branch coverage
- Unit test execution metrics including:
- Successfully executed tests
- Failed tests
- Skipped tests
- Execution time
- Recognition of code duplication
- Basic highlighting mode for C++ in Sonar UI
The Cxx-Plugin has an obligatory dependency on Java (of course... the plugin itself and all runners are Java programs).
Moreover, there are optional dependencies on:
- Various external code analyzers:
- Cppcheck. Detects a wide range of problems ranging from performance issues and resource leakage to undefined behaviour. Binary packets are available on/for various platforms. Using the latest release pays off in general; compile from source if in doubt.
- RATS. Detects (potential) security problems in code, sensible for code bases with increased security requirements. Use binary packages or compile from source.
- Vera++. Focuses on code style issues. There's a binary package for Windows, users of other platforms are likely to compile themselves.
- Valgrind (memcheck). Detects various memory management problems at runtime. Basically Linux only; just use the packages from your distribution.
- CppNcss. Provides cyclomatic (McCabe) complexity measures. This is a Java program distributed as a zip archive. Just unpack and make sure the "bin" directory is in PATH.
- GCC, gcov, gcovr and Python for coverage determination. Install Python and place the script somewhere on the PATH.
- Copy the jar-archive into <sonar home>
- Restart the Sonar web server
Cxx plugin uses the following properties during analysis. See here for the ways how to pass them to the plugin.
|sonar.cxx.suffixes.sources||System- and/or project-wide||cxx,cpp,cc,c||.C,.h|
Comma separated list of file name extension to be considered as C++ source files during analysis.
|sonar.cxx.suffixes.headers||System- and/or project-wide||hxx,hpp,hh,h||Comma separated list of file name extension to be considered as C++ source files during analysis.|
Ant pattern describing the path to Cppcheck reports, relative to projects root.
|sonar.cxx.cppncss.reportPath||Project-wide||cppncss-reports/cppncss-result-*.xml||cppncss-report-*.xml||Ant pattern describing the path to CppNcss reports, relative to projects root.|
|sonar.cxx.gcovr.reportPath (<0.2)||Project-wide||gcovr-reports/gcovr-result-*.xml||gcovr-report-*.xml||Ant pattern describing the path to gcovr reports, relative to projects root.|
|sonar.cxx.rats.reportPath||Project-wide||rats-reports/rats-result-*.xml||rats-report-*.xml||Ant pattern describing the path to RATS reports, relative to projects root.|
|sonar.cxx.valgrind.reportPath||Project-wide||valgrind-reports/valgrind-result-*.xml||valgrind-report-*.xml||Ant pattern describing the path to Valgrind reports, relative to projects root.|
|sonar.cxx.vera.reportPath||Project-wide||vera++-reports/vera++-result-*.xml||vera-report-*.xml||Ant pattern describing the path to Vera++ reports, relative to projects root.|
|sonar.cxx.xunit.reportPath||Project-wide||xunit-reports/xunit-result-*.xml||xunit-report-*.xml||Ant pattern describing the path to unit test execution reports, relative to projects root.|
|sonar.cxx.externalrules.reportPath||Project-wide||externalrules-result/externalrules-result-*.xml||externalrules-result-*.xml||Ant pattern describing the path to unit test execution reports, relative to projects root.|
A name of a built in XSLT-file or an URL to an external one. Available builtins:
|sonar.cxx.coverage.reportPath (>=0.2)||Project-wide||coverage-reports/coverage-*.xml||coverage-*.xml||Ant pattern describing the path of unit test coverage reports, relative to projects root.|
|sonar.cxx.coverage.itReportPath (>=0.2)||Project-wide||coverage-reports/it-coverage-*.xml||it-coverage-*.xml||Ant pattern describing the path of integration test coverage reports, relative to projects root.|
|sonar.cxx.coverage.itReportPath (>=0.2)||Project-wide||coverage-reports/overall-coverage-*.xml||overall-coverage-*.xml||Ant pattern describing the path of integration test coverage reports, relative to projects root.|
Note: Report paths are always relative to projects path.
You can analyze your projects using the usual means (see this page for all available). All runners should work. See below for details how to do it for maven-, ant-, and all-the-other-projects.
Doing sonar analysis on maven projects is quite simple and usually a matter of:
- Getting and installing the cxx-maven-plugin (usage).
- Setting the language-property and the source directory in your pom:
- Make sure sonar-server is running
For details see the first sample project.
Project using miscellaneous build systems
Outside of the maven world the process of integration of a sonar analysis into your project is usually less straightforward but also more flexible. The rough pattern should remain the same independent of the environment:
- Run the analyzers which are of interest for you and store the results in a file somewhere underneath the root directory of your project. Its usually convenient to put this into the build system; a shell script may be a good choice, too.
Use the sonar-runner to trigger the Cxx plugin which parses the result files and feeds the data into sonar. The sonar runner requires some data to proceed which is usually provided via the "sonar-project.properties"-file in the projects root directory.
There may be a Step '0' too: "use your build system to make a build suitable for running the Step 1". This may be the case for collecting coverage statistics when using gcc+gcov, for example.
For details how to invoke the tools and tie it all together see the second sample project.
External report generation
Here is a quick guide how to generate the reports using external tools
Make sure to pass all include directories as otherwise the analysis will be incomplete. Caveat: cppcheck writes the output to the standard error.
You may also use -D and -M options to tell cppncss about preprocessor macros.
Cobertura and Bullseye (http://www.bullseye.com/) XML formats are supported for > 0.2 versions. Previous versions support only Cobertura, and sonar.cxx.gcovr.reportPath needs to be set.
Gcov / gcovr
- Make sure to compile and link with the --coverage-flag. Disable optimizations and switch on debugging.
- Execute your application / your tests. This will generate .gcda-files.
- Collect the coverage information and generate the report using gcovr:
Bullseye coverage tool is now supported, the command 'covxml' can be used to create the XML report. Once xml reports is available it can be imported using the properties sonar.cxx.coverage.reportPath and sonar.cxx.coverage.itReportPath.
Notes about coverage display in sonar:
Sonar <3.2 provides metrics for line coverage and branch coverage. Bullseye users have function and branch/decision coverage instead, the cxx plugin coverts the second directly into branch coverage however line coverage is far more complex and cannot be correlated directly into function coverage.
Line coverage imported from a bullseye report means than function coverage + line branch coverage ( this second occurs since sonar will not display branch coverage if there isn't a line it associated with it). This means also that overall coverage will be affect in sonar and cannot be compared directly to bullseye results. The following pictures illustrate this for a small example project.
Just tell valgrind to generate XML output. The 'tool' option isn't necessary as 'memcheck' is the default one. Make sure the binaries contain debug info.
The generation of vera++ reports is somewhat more tricky. We find all the files we want to be analysed, pipe this list into vera++ and pipe its output into a Perl script which finally generates the required XML.
Import of violations
As of version 0.2, any static analysis tool can be reused with the plugin using the property sonar.cxx.externalrules.reportPath. The following table describes the format of the report
|Xml Description - RNG-Schema||Example|
<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>
|file||source file, relative to project path|
|line||line of the violation|
|id||id of the rule, mapped a rule in sonar. See "Enable the rules in Sonar server" below|
|msg||description of the violation|
Enable the rules in Sonar server
To reuse reports from other tools the C++ quality profile in sonar needs to be inline with the reported violations in the external report.
- Some analyzers (RATS, most notably) may have issues and crash occasionally.
- Valgrind is only available on a subset of UNIX platforms.
Following items are in the queue (more or less...):
- Integrate compiler warnings
- Implement the dependency analysis (package tangle index metric)
Reimplement the complexity analyzer sensor based on the AST traversal and get rid of the cppncss dependency
Reimplement the tokenizer used by the CPD engine based on the built-in parsing infrastructure and remove the PMD-dependency