Difference between revisions of "CDT/Obsolete/ScannerDiscovery61/API"

Revision as of 15:28, 26 December 2010

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

• 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);
}

• LanguageSettingsBaseProvider is a an implementation of ILanguageSettingsProvider for the new extension point org.eclipse.cdt.core.LanguageSettingsProvider. This class is intended to be extended by concrete provider implementations like GCC Build Output Parser etc.

• ICConfigurationDescription interface got a getter and a setter to keep a list of providers:

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.