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 
#include 

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:

  1. 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.
  2. 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.

prop entries

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.

project explorer

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".

specs detector options

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.

sd 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.

sd console view

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.

include directory

Add/Edit entries dialog

Group Description
Kind of Setting Entry include directory
A dropbox to select desired kind of setting entry. This dropbox is not available in "Edit" mode.
Kind of path project 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.

preprocessor includes

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.

preprocessor includes

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

settings

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

settings

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:
  • ${COMMAND} - compiler command from the toolchain, such as "gcc".
  • ${INPUTS} - indicates normally an empty specs file required by the compiler. In no such file exists the file gets created temporarily in Eclipse workspace plugin area.
  • ${EXT} - an extension for the language to discover built-in settings. A provider can be associated with multiple languages and it will run the command for each language.
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.

About the Author

Andrew Gvozdev