Setting Up Include Paths and Macros for C/C++ Indexer
CDT allows for comfortable environment with code highlighting, navigation, content assist and static analysis. However, most C/C++ projects have to be configured to enjoy those features. Most real life C/C++ projects heavily depend on code outside of the project itself, such as system headers or third party libraries. CDT indexer needs to process those to provide accurate index. Failure to set up these important settings assuredly will cause the assist tools misbehave.
CDT will try to discover include paths and preprocessor symbols automatically for supported tool chains. This process is known as Scanner Discovery or Autodiscovery. This discovery of symbols is twofold. One way, CDT will try to detect built-in compiler symbols and include paths running the compiler with special options and parse the output. Another method that CDT employs is to analyze build output of the regular build with Build Output Parser. Often, include paths are supplied to the compiler with -I options, and macros with -D options. That relies on verbose build output of your build where all these options are actually printed by make.
Scanner Discovery uses Language Settings Providers to find include paths and preprocessor symbols. Language Settings Providers can be configured on project properties page "Preprocessor Include Paths, Macros, etc.", Providers tab for a configuration and on preference page C/C++ Preferences: Scanner Discovery for shared providers.
If information retrieved by auto-discovery is insufficient or the project deviates from a standard one supported by CDT a user can inspect discovered entries and enter additional include paths and macros manually on the property page "Preprocessor Include Paths, Macros, etc.", Entries tab.
There are other ways to make C/C++ indexer aware of include paths or macros. One way is to set up them in MBS via "Paths and Symbols" project properties. See Including paths and symbols in Managed Build System. These entries are supplied to the indexer with MBS Language Settings Provider.
Scanner Discovery
General
Scanner Discovery (sometimes called Autodiscovery) is a method of finding include paths and predefined preprocessor macros which the compiler uses during compilation of the code.
Even a simplest C/C++ program just printing "Hello World" needs to include system headers. Consider:
#include <stdio.h>
#include <stdlib.h>
int main(void) {
puts("!!!Hello World!!!");
return EXIT_SUCCESS;
}
Indexer needs to be able to find headers stdio.h and stdlib.h and parse them to provide accurate index. In this example, the headers define prototype of function puts and macro EXIT_SUCCESS.
CDT will try to discover include paths and preprocessor symbols automatically for supported tool chains. There are 2 main ways to discover those:
- Built-in Settings. CDT will try to detect built-in compiler symbols and include paths running the compiler with special options and parse the output of this special run. Most compilers provide such an option to print built-in include paths and symbols. Built-in settings are implied and do not get passed to compiler during regular compilation.
- Build Output Parser (BOP). Another method that CDT employs is to analyze build output of the regular build with Build Output Parser. Often, include paths are supplied to the compiler with -I options, and macros with -D options and BOP will try to find those in the output. That method relies on verbose build output of your build where all these options are actually printed by make.
CDT uses Language Settings Providers to discover the settings (starting with version CDT 8.1). Typically Language settings Providers are specialized. One will provide built-in compiler settings and another one settings detected by Build output Parser. There is also an extension point defined in CDT to allow third party Eclipse plugins to contribute custom Language Settings Providers.
The setting entries found by Scanner Discovery can be inspected in project properties on "Preprocessor Include Paths, Macros etc." page. Each Language Settings Provider can be expanded to show the entries it discovered.
If information retrieved by auto-discovery is insufficient or the project deviates from a standard one supported by CDT a user can enter additional include paths and macros manually under "User Settings Entries".
Project Explorer View
The Project Explorer View provides a means to view some of the settings. The discovered include paths are shown under the project when "Includes" node is expanded.
Also, a "Wrench" overlay icon is shown for those file/folders where distinct entries are discovered which differ from those of parent folder. Wrench is not shown on project level.
In the example below, Hello.cpp was compiled with added -DHELLO compiler option. After BOP discovery "Wrench" overlay is shown for this file.
Console View
The output of built-in compiler specs detectors can be inspected to troubleshoot problems running the command. To do so, enable checkbox "Allocate console in the Console View".
When checkbox "Allocate console in the Console View" is enabled, output of each run of the provider will be directed to a special console in the Console View.
C/C++ Project properties: Preprocessor Include Paths, Macros, etc.
Include paths and preprocessor macros for C/C++ indexer and other Language Settings are supplied by Language Settings Providers using Scanner Discovery mechanism.
The entries can be inspected and set up on project properties page "Preprocessor Include Paths, Macros, etc." - Entries tab.
Language Settings Providers can be set up and configured for the selected configuration on project properties page "Preprocessor Include Paths, Macros, etc." - Providers tab.
C/C++ Project properties: Preprocessor Include Paths, Macros, etc. - Entries tab
Include paths and preprocessor macros for C/C++ indexer can be inspected and set up on the project property page "Preprocessor Include Paths, Macros, etc.", "Entries" tab. This tab presents Language Settings Providers employed by Scanner Discovery to provide include paths, macros and other Language Settings.
Note that the entries could be set also on an individual resource, such as file or folder. Open file or folder properties to inspect resource-specific entries. The entries on a folder or a project will apply to all subfolders and C/C++ files under it - unless overridden on a lower level.
"Entries" tab shows a list of Language Settings Providers for each language. A provider node can be expanded to show include paths and macros defined by the provider. A user can add custom entries here under "User Setting Entries" provider.
Entries tab controls
| Group | Description |
|---|---|
| Configuration | Click here for a description |
| Manage Configurations... | Click here for a description |
| Languages | Lists all of the languages defined by the tool chain. Select a language to see the list of applicable providers. |
| Setting Entries | Lists all of the providers for the selected language and entries supplied by them. Expand a provider node to see the entries. |
| Show built-in values | Disable checkbox "Show built-in values" to filter out built-in setting entries in the view. Built-in compiler entries need to be provided to C/C++ indexer but not to the compiler during the build. |
| Add... | Add an entry to the provider. Enabled only when the provider supports the operation. |
| Edit... | Edit the selected settings entry. Enabled only when the provider supports the operation. |
| Delete | Delete the selected settings entry. Enabled only when the provider supports the operation. |
| Move Up | Moves the selected entry higher in the list. Enabled only when the provider supports the operation. |
| Move Down | Moves the selected entry lower in the list. Enabled only when the provider supports the operation. |
Adding and Editing entries
Use Add... and Edit... buttons to add or modify the entries. Both buttons open similar dialog described here.
Add/Edit entries dialog
| Group | Description |
|---|---|
| Kind of Setting Entry |  A dropbox to select desired kind of setting entry. This dropbox is not available in "Edit" mode. |
| Kind of path |  A dropbox to select desired kind of path. This dropbox is shown for path entries only. |
| Path | Enter path value of the
entry. This field is shown for path entries only. |
| Open folder button | Use folder button to
navigate folder structure to select existing path. The
provided dialog varies depending on the kind of path selected
in the corresponding dropbox. This button is shown for path entries only. |
| Variables | Select one of the build or
environment variables provided by CDT to embed into "Path"
field. This button is enabled only for File System Paths. |
| Treat as built-in | Enable this checkbox to mark the entry as built-in. Built-in compiler entries need to be provided to C/C++ indexer but not to the compiler during the build. |
| Contains system headers | Enable if the include path
is a system directory which contains system headers. This checkbox is shown for Include Directories only. |
| Framework folder | Mac OS has a unique way of
specifying include directories for Frameworks. Enable if the
included directory is Mac Framework directory. This checkbox is shown for Include Directories only. |
| Name | Shown for Preprocessor Macro only. Specify the macro name here. |
| Value | Shown for Preprocessor Macro only. Specify the macro name here. |
C/C++ Project properties: Preprocessor Include Paths, Macros, etc. - Providers tab
Include paths and preprocessor macros for C/C++ indexer and other Language Settings are supplied by Language Settings Providers as part of Scanner Discovery. Language Settings Providers can be set up and configured for the selected configuration in the "Providers" tab.
"Providers" tab is only shown in properties of a project, not in properties of a file or a folder.
Providers tab controls
| Group | Description |
|---|---|
| Configuration | Click here for a description |
| Manage Configurations... | Click here for a description |
| Language | Lists all of the providers available for the current configuration. |
| Setting Providers List | Select the providers to assign to the configuration. |
| Clear Entries | Clears all entries of the
selected provider. This operation takes effect after pressing
"Apply" or "OK". Normally this will trigger a rerun if the
provider supplies built-in compiler settings. Build output
parsers will regain language settings after build while
parsing new build output. This operation might be unavailable if the provider does not have any language settings. Some providers may not have the capability to clear. On this property page, this operation is applicable only to non-shared providers. |
| Reset | Resets options of the
selected provider to default values. This operation also
clears the provider entries. The button can be enabled if some
options in "Language Settings Provider Options" panel were
changed. In this dialog, this operation is applicable only to non-shared providers. |
| Move Up | Moves the selected provider higher in the list. |
| Move Down | Moves the selected provider lower in the list. |
A user can define some options for configuration providers (or "non-shared") on this property page. Note that providers can be either shared or defined per configuration. Options of global (or "shared") providers can be configured on C/C++ Preferences: Scanner Discovery.
There are 2 specific options that are added for non-shared providers defined per configuration. They are described in the table below.
Discovery tab
| Group | Description |
|---|---|
| Use global provider shared between projects | Providers can be global or belong to a configuration. Global providers share their entries between all configurations which refer to them. |
| Store entries in project settings folder | Providers can persist their entries in workspace or under project folder. Storing entries under project when approprate can make sharing with the other team members easier. |
The rest of the options is described in C/C++ Preferences: Scanner Discovery, under Language Settings Providers Options.
Scanner Discovery Preferences
General
Use the Discovery Tab on 
Build
preference panel to define global scanner discovery options.
In the Discovery tab you can see a list of Language Settings Providers. Language Settings Providers supply Language Settings such as include paths and preprocessor macros for the indexer and other components of CDT.
A user can define some properties for global (or "shared") providers on this preference. Note that providers can be either shared or defined per configuration. Properties for non-shared providers can be defined in Project properties: Preprocessor Include Paths, Macros, etc.
Discovery tab
| Group | Description |
|---|---|
| Language Settings Providers | Lists the available language settings providers. |
| Clear Entries | Click to clear all entries of the selected provider. This operation takes effect after pressing "Apply" or "OK". Normally this will trigger a rerun if the provider supplies built-in compiler settings. Build output parsers will regain language settings after build while parsing new build output. This operation might be unavailable if the provider does not have any language settings. Some providers may not have the capability to clear. |
| Reset | Click to reset options of the selected provider to default values. This operation also clears the provider entries. The button can be enabled if some options in "Language Settings Provider Options" panel were changed. |
Kinds of Language Settings Providers
| Provider | Description |
|---|---|
| Build Output Parser Provider | Build Output Parser
Provider parses output of build looking for include paths and
macros passed to the compiler via compiler options. Include
files, macro files passed the the compiler and some other
compiler options are normally also recognized. For gcc, include paths commonly passed with "-I" option and macros with "-D" option. The language settings found by BOP are available after the build is finished. |
| Built-in Compiler Settings Provider | Built-in Compiler Settings Provider launches the compiler with special options that instruct the compiler to print built-in settings such as include paths to internal system headers and the list of internally predefined macros. This provider is usually shared between projects in workspace and runs in background once. When it is finished the language settings are available to all the projects between which it is shared. |
| Managed Build Language Settings Provider | MBS Provider supplies language settings provided by Managed Build System. |
| User Language Settings Provider | A user has an opportunity to enter language settings manually using this provider. User Language Settings Provider should be normally the first in the list so these settings override settings supplied by other providers. |
| Contributed PathEntry Containers | This provider is here for backward compatibility support of PathEntry Containers from older versions of CDT. Using this method is not recommended. |
| Contributed ScannerInfo Entries | This provider is here for backward compatibility support of ScannerInfo Entries from older versions of CDT. Using this method is not recommended. |
Language Settings Providers Options
Language settings providers can have options that affect the behavior of a provider. These options are presented in "Language Settings Provider Options" panel.
Build Output Parser Options
Build Output Parser Options
| Provider | Options |
|---|---|
| Compiler command pattern | The pattern which is used
to recognize compiler command in build output. Note that the pattern is Java regular expression pattern, it is NOT globing pattern used to expand file name in command line. |
| Container to keep discovered entries | The discovered entries can be associated with the project, enclosing folder or the file itself. |
| Use heuristics to resolve paths | The provider will try to find the best match for the discovered path in the project or workspace trying several heuristics. If disabled, the discovered paths will stay as they appear in build output. |
Built-in Compiler Settings Provider Options
Builtin Compiler Settings Provider Options
| Provider | Options |
|---|---|
| Command to get compiler specs | The command to make the
compiler print built-in settings. Following variables are
recognized:
|
| Browse | Use this button to locate the compiler on the file system. The result is put into "Command to get compiler specs" input field. |
| Allocate console in the Console View | Enable to troubleshoot problems running the command. When enabled, output of each run of the provider will be directed to a special console in the Console View. See also Scanner Discovery - Console View. |
To see the entries a provider discovered, go to project properties (or the properties of the resource of interest), see Project properties: Preprocessor Include Paths, Macros, etc.
A hint: After compiler upgrade re-discover changed settings with "Clear Entries" of the appropriate provider.
References
The material provided in this article is also available with Eclipse Kepler C/C++ Development User Guide in Scanner Discovery section.