sonar.cxx.includeDirectories

Comma-separated list of directories where the cxx plugin preprocessor looks for include files.

• Hint: Since the cxx plugin only reads macros from the include files in order to parse the code syntactically in a correct way, it is often better to provide the missing macros instead of reading in all include files. Reading many include files (e.g. STL, Boost, MFC, ATL, ...) often slows down the analysis considerably. The recommendation is to include only include files for your own code.

General include directory hints

• the location of your configuration file sonar-project.properties defines the project base directory
• directories can be specified absolute or relative
• relative directories defined in configuration file are always relative to the project base directory
• Use always slashes (/) in the configuration file sonar-project.properties as path separator.

  Hint: It is also possible to use backslashes but you have to escape it with another backslash (\ => \\) which is hard to read.

The following preprocessor commands are using the sonar.cxx.includeDirectories parameter:

#include <filename> // (1)
#include "filename" // (2)
__has_include( <filename> ) // (3)
__has_include( "filename" ) // (4)

(1) and (3):

Searches for the file in implementation-defined manner. For the cxx plugin this means that the directories defined in sonar.cxx.includeDirectories are searched from left to right. The intent of this syntax is to search for the files under control of the implementation. Typical implementations search only standard include directories. The standard C++ library and the standard C library are implicitly included in these standard include directories.

Hint: the cxx plugin doesn't know any standard include paths. If they should be used, configure them manually using this parameter.

(2) and (4):

Searches for the file in implementation-defined manner. The intent of this syntax is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides and, only if the file is not found, search the standard include directories as with (1). For the cxx plugin this means:

1. In the same directory as the file that contains the #include statement.
2. In the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files (Microsoft specific extension).
3. Search the standard include directories as defined with sonar.cxx.includeDirectories.

Microsoft Windows sample with 'C:\MyProject\sonar-project.properties':

sonar.cxx.includeDirectories=C:/3rdParty/include,MyInclude
# directory 1: C:\3rdParty\include
# directory 2: C:\MyProject\MyInclude

Automatically extract include directories from the build system

The cxx plugin can also automatically extract include directories and macros from MSBuild .LOG files or JSON Compilation Databases. More information can be found at the respective parameter sonar.cxx.msbuild.reportPaths or sonar.cxx.jsonCompilationDatabase.