Jump to: navigation, search

CDT/ScannerDiscovery61/API

Scanner Discovery project

The project is hosted currently on GitHub. Please, refer there https://github.com/angvoz/SD80/ for the most recent API and code. Use branch [sd80] for bleeding edge code with more advanced UI and [sd80.Patch#.CDT] to take a look at clean patches intended for CDT submission. If you want to try it, the functionality is still experimental and disabled by default. To enable:

  • first select "Display Providers" tab in Preferences->C/C++->Property Pages Settings,
  • then in project properties C/C++ General->Paths and Symbols you'll get "Providers" tab. Click "I want to try..." check box and use "Configure" button to add providers to the configuration.

To define your own provider refer to Providers_Defined_via_Extension_Point and Dynamic_Providers.

API

Please, note that this API covers unmodifiable providers only, including providers defined in the new extension point org.eclipse.cdt.core.LanguageSettingsProvider. This API does not cover modifiable providers, any caching or persistence for discovered language settings entries. These facilities are intended to be covered by a non-breaking API additions. For a sneak peek at those please see git branch [sd80].

  • New interface ILanguageSettingsProvider. This base interface is the cornerstone of the new Scanner Discovery functionality. It defines following:
public interface ILanguageSettingsProvider {
   public String getId();
   public String getName();
   public List<ICLanguageSettingEntry> getSettingEntries(ICConfigurationDescription cfgDescription, IResource rc, String languageId);
}
public interface ICConfigurationDescription extends ICSettingContainer, ICSettingObject, ICSettingsStorage{
	
	/**
	 * Sets the list of language settings providers. Language settings providers are
	 * used to supply language settings {@link ICLanguageSettingEntry} such as include paths
	 * or preprocessor macros.
	 * 
	 * @param providers the list of providers to assign to the configuration description.
	 * 
	 * @since 6.0
	 */
	public void setLanguageSettingProviders(List<ILanguageSettingsProvider> providers);
	
	/**
	 * Returns the list of language settings providers. Language settings providers are
	 * used to supply language settings {@link ICLanguageSettingEntry} such as include paths
	 * or preprocessor macros.
	 * 
	 * @return the list of providers to assign to the configuration description. This
	 * returns a copy of the internal list.
	 * 
	 * @since 6.0
	 */
	public List<ILanguageSettingsProvider> getLanguageSettingProviders();
}
  • LanguageSettingsManager is a utility class. It provides following API methods, mostly for the usage by UI plugin:
public class LanguageSettingsManager {
...
	/**
	 * Returns the list of setting entries of the given provider
	 * for the given configuration description, resource and language.
	 * This method reaches to the parent folder of the resource recursively
	 * in case the resource does not define the entries for the given provider.
	 *
	 * @param provider - language settings provider.
	 * @param cfgDescription - configuration description.
	 * @param rc - resource such as file or folder.
	 * @param languageId - language id.
	 *
	 * @return the list of setting entries. Never returns {@code null}
	 *     although individual providers return {@code null} if no settings defined.
	 */
	public static List<ICLanguageSettingEntry> getSettingEntriesUpResourceTree(ILanguageSettingsProvider provider, ICConfigurationDescription cfgDescription, IResource rc, String languageId) {
		return LanguageSettingsExtensionManager.getSettingEntriesUpResourceTree(provider, cfgDescription, rc, languageId);
	}

	/**
	 * Returns the list of setting entries of a certain kind (such as include paths)
	 * for the given configuration description, resource and language. This is a
	 * combined list for all providers taking into account settings of parent folder
	 * if settings for the given resource are not defined.
	 *
	 * @param cfgDescription - configuration description.
	 * @param rc - resource such as file or folder.
	 * @param languageId - language id.
	 * @param kind - kind of language settings entries, such as
	 *     {@link ICSettingEntry#INCLUDE_PATH} etc. This is a binary flag
	 *     and it is possible to specify composite kind.
	 *     Use {@link ICSettingEntry#ALL} to get all kinds.
	 *
	 * @return the list of setting entries.
	 */
	public static List<ICLanguageSettingEntry> getSettingEntriesByKind(ICConfigurationDescription cfgDescription, IResource rc, String languageId, int kind) {
		return LanguageSettingsExtensionManager.getSettingEntriesByKind(cfgDescription, rc, languageId, kind);
	}

	/**
	 * @return a list of language settings providers defined on workspace level.
	 * That includes providers defined as
	 * extensions via {@code org.eclipse.cdt.core.LanguageSettingsProvider}
	 * extension point.
	 */
	public static List<ILanguageSettingsProvider> getWorkspaceProviders() {
		return LanguageSettingsExtensionManager.getExtensionProviders();
	}
...

}

  • ICSettingEntry changed to add a new flag.
public interface ICSettingEntry {
...
	/**
	 * Flag {@code UNDEFINED} indicates that the entry should not be defined.
	 * It's main purpose to provide the means to negate entries defined elsewhere.
	 * 
	 * @since 6.0
	 */
	int UNDEFINED = 1 << 5;
...
}

This flag maps to gcc -U compiler setting and used for disabling entries in UI.