sonar.cxx.jsonCompilationDatabase

Overview

The cxx plugin supports reading the JSON Compilation Database Format Specification to automatically extract the required macros (sonar.cxx.defines) and include directories (sonar.cxx.includeDirectories).

Hint: The cxx plugin does not create the JSON Compilation Database itself. This must be created beforehand via an external tool.

A compilation database is a JSON file, which consist of an array of “command objects”, where each command object specifies one way a translation unit is compiled in the project.

Each command object contains the translation unit’s main file, the working directory of the compile run and the actual compile command.

The cxx plugin evaluates the following directory and preprocessor command line parameters:

parameter	description
-D	defines a macro to be used by the preprocessor
-I	Add the directory dir to the list of directories to be searched for header files during preprocessing.
-iquote	Add the directory dir to the list of directories to be searched for header files during preprocessing. Directories specified with -iquote apply only to the quote form of the #include directive. The cxx plugin handles it in the same way as -I.
-isystem	Add the directory dir to the list of directories to be searched for header files during preprocessing. The cxx plugin adds all -isystem dirs after the list of -I dirs.
-idirafter	Add the directory dir to the list of directories to be searched for header files during preprocessing. The cxx plugin adds all -idirafter dirs after the list of -isystem dirs.

Supported versions

• Link to the tool page: http://clang.llvm.org/docs/JSONCompilationDatabase.html
• The JSON Compilation Database Format is available since Clang release 3.8.0.

Create JSON Compilation Database

Currently CMake (since 2.8.5) supports generation of compilation databases for Unix Makefile builds (Ninja builds in the works) with the option CMAKE_EXPORT_COMPILE_COMMANDS.

Example of a JSON Compilation Database

In below example hello.cpp is compiled with -DHELLO and world.cpp is compiled with -DWORLD. This specifies that HELLO macro is only defined by cxx plugin when analyzing hello.cpp file. Similarly WORLD is defined only for world.cpp.

[
  {
    "file" : "hello.cpp"
    "directory": "/home/user/build",
    "command": "/usr/bin/gcc -DHELLO -o hello hello.cpp"
  },
  {
    "file" : "world.cpp"
    "directory": "/home/user/build",
    "command": "/usr/bin/gcc -DWORLD -o world world.cpp"
  }
]

For global definitions the command object __global__ is available. Here global macros (defines) and include directories (includes) can be defined, which are then used by all files. The JSON Compilation Database can be optimized by moving shared definitions to __global__.

[
  {
    "file": "__global__",
    "defines": {
      "__ARM_ARCH": "7",
      "__UINT16_TYPE__": "short unsigned int",
      ...
    },
    "includes" : [
      "/opt/vendor/vendor-sdk/sysroots/x86_64-vendorsdk-linux/usr/lib/arm-vendor-linux-gnueabi/gcc/arm-vendor-linux-gnueabi/4.9.2/include",
      ...
    ]
  },
  {
    "file" : "hello.cpp"
    "directory": "/home/user/build",
    "command": "/usr/bin/gcc -DHELLO -o hello hello.cpp",
    "defines": {
      "__ARM_ARCH": "7",
      "__UINT16_TYPE__": "short unsigned int",
      "__STDC_HOSTED__": "1",
      "__GNUC__" : "4"
      "__SIZEOF_SHORT__": "2",
      "__INT_MAX__": "2147483647",
      ...
      "HELLO" : ""
    },
    "includes" : [
      "/opt/vendor/vendor-sdk/sysroots/x86_64-vendorsdk-linux/usr/lib/arm-vendor-linux-gnueabi/gcc/arm-vendor-linux-gnueabi/4.9.2/include",
      "/opt/vendor/vendor-sdk/sysroots/x86_64-vendorsdk-linux/usr/lib/arm-vendor-linux-gnueabi/gcc/arm-vendor-linux-gnueabi/4.9.2/include-fixed",
      "/opt/vendor/vendor-sdk/sysroots/cortexa8hf-vfp-neon-vendor-linux-gnueabi/usr/include/c++/4.9.2",
      "/opt/vendor/vendor-sdk/sysroots/cortexa8hf-vfp-neon-vendor-linux-gnueabi/usr/include/c++/4.9.2/arm-vendor-linux-gnueabi",
      ...
    ]
  }
]

Configure cxx plugin

1. The cxx plugin does not create the JSON Compilation Database itself. This must be created beforehand via an external tool.
2. First check if the file extensions read in by the cxx plugin are set (sonar.cxx.file.suffixes).
3. Set the analysis parameter sonar.cxx.jsonCompilationDatabase in the configuration file sonar-project.properties of your project. You have to define a single file with absolute or relative path (see Report Paths for more hints).
4. Narrowing the Focus gives more hints how to include and exclude files. At least sonar.sources must match the contents of the database.
5. Execute the SonarScanner to transfer the project with the report to the SonarQube Server.

If the includes and macros come from multiple sources, they are processed in the following order:

1. Definitions assigned to a file.
2. Global definitions.
3. Definitions from sonar-project.properties.
4. Predefined Macros

sonar.cxx.includeDirectoris=1,2,3 // searching files in directories from left to right
sonar.cxx.defines=1,2,3,4         // first macro definition found is used, search from left to right

Sample for sonar-project.properties:

sonar.cxx.jsonCompilationDatabase=compile_commands.json