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

Latest revision as of 14:03, 22 January 2020

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

This API page was created to present the proposal to CDT community. For more accurate and up to date documentation please refer to JavaDoc in CDT source code.

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