CDT/ScannerDiscovery61/API

From Eclipsepedia

Jump to: navigation, search

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 ILanguageSettingsProvidersKeeper {
	/**
	 * 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 owner (configuration description).
	 *    This method clones the internal list or otherwise ensures immutability of the internal
	 *    list before actual addition to the project model. That is to ensure that there is no
	 *    back-door access and all changes in the list done by this method which fires notifications
	 *    to the registered listeners about the accompanied changes in settings entries, see
	 *    {@link LanguageSettingsManager#registerLanguageSettingsChangeListener(ILanguageSettingsChangeListener)}.
	 */
	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 owner (configuration description). This
	 *    returns immutable list. Use {@link #setLanguageSettingProviders(List)} to change.
	 *    This method does not return {@code null}.
	 */
	public List<ILanguageSettingsProvider> getLanguageSettingProviders();

	/**
	 * Sets the list of IDs of default language settings providers.
	 * 

* The method is intended to be used by MBS to set the list from tool-chain definition. * The default list from the tool-chain is used, for example, while resetting * configuration providers to default in UI. * * @param ids - default provider IDs specified in the tool-chain. */ public void setDefaultLanguageSettingsProvidersIds(String[] ids); /** * Retrieve the list of IDs of default language settings providers. * Normally the list would come from the tool-chain definition. * * @return default provider IDs or {@code null} if default providers are not defined. */ public String[] getDefaultLanguageSettingsProvidersIds(); }
  • 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.