CDT/Obsolete/ScannerDiscovery61/API

Scanner Discovery project

The project has been delivered - initial version in CDT 8.1 (Juno) and more mature version in CDT 8.2 (Kepler).

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.

• New interface ILanguageSettingsProvidersKeeper for modifying language setting providers, which is implemented by the CConfigurationDescription class. See the function testProjectDescription_ReadWriteDescription() in LanguageSettingsPersistenceProjectTests for example code.

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 a number of useful utility API methods:

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.