ExternalExportProjectProvider
+command-line options4
Invoking the GeneratePDOM application.. 5
Invoking
+as a self-hosted eclipse application5
Invoking
+via the command-line6
Overview
+ +This document describes two +extension points used for generating reusable index content, and for adding +this content into a CDT 4.0 based environment. The intended audience is ISVs +who are looking to build indexes of libraries or SDKs that are of interest to +them and their customers, and to integrate the pre-built index information into +their IDE environment. The extension points are intended to be general enough +to allow ISVs to support unforeseen pre-built index content scenarios, with a +set of default implementations intended to be useful for standard situations. +Other sources that may be helpful are the extension point descriptions, and the +central interfaces’ javadoc.
+ +Export of index content
+ +Export is performed by indexing a +normal CDT project which has been setup and configured programmatically. A +top-level summary of the steps needed is:
+ +(1) +Write a class that can setup your index content as a +CDT project, and register it against an extension point. For simple +libraries/SDKs the default implementation can be used.
+ +(2) +Invoke the GeneratePDOM application from the command-line. +This involves invoking eclipse from an eclipse installation with the CDT 4.0 +plug-ins, and the plug-in containing the project generation code from step (1)
+ +IExportProjectProvider
+
+It is expected that real-world +libraries and SDK’s may need complex configuration before indexing. For +example, per-file macro or include settings, or excluding certain files from +being indexed. In this case, it is necessary for the ISV to write code which +programmatically performs this configuration. If detailed configuration is not +needed then a default implementation of IExportProjectProvider may be +sufficient.
+ +The call-back for project +creation must implement the following interface
+ +org.eclipse.cdt.core.index.export.IExportProjectProvider
The skeletal form of this +interface is shown below:
+ +This interface allows any index +export application to delegate the entire setting up of the project content to +an ISV specific implementation. The interface javadoc describes each method in +more detail but a summary is:
+ +· +setApplicationArguments – this receives any +application arguments specified on the command-line. Its expected +implementations will simply store the arguments for later processing by +createProject.
+ +· +createProject – this is the key method which is +expected to create and configure a project representing the content to be +indexed
+ +· +getLocationConverter – this returns an +IIndexLocationConverter which converts IIndexFileLocation objects (which +represent file locations in the index) to an unspecified ISV determined +internal (String) format. For convenience, an implementation which converts an +IIndexFileLocation to an internal format relative path is provided
+ +o +org.eclipse.cdt.core.index.ResourceContainerRelativeLocationConverter
+ +· +getExportProperties – this allows ISV’s to +associate String values with String keys within exported content. This is +mostly for debugging purposes as it is not exposed to the CDT user in the 4.0 +release.
+ +A default implementation of +this interface, which is also intended to be sub-classed, is org.eclipse.cdt.core.index.export.ExternalExportProjectProvider
+ +The project provider must be +registered as an extension to the org.eclipse.cdt.core.CIndex +extension point under the ExportProjectProvider child +element, in order that it is visible to the CDT core index generation code.
+ +
+
The GeneratePDOM Application
+ +CDT 4.0 provides an eclipse +command-line application for generating the index. Its application ID is:
+ +org.eclipse.cdt.core.GeneratePDOM
+ +This +application can be invoked as any other eclipse command-line application, some +examples are provided later in this document.
+ +Common command-line +options
+ +Command-line options common to +all IExportProjectProvider implementations are:
+ +|
+ -pprovider + |
+
+ The fully qualified classname
+ of a class implementing interface IExportProjectProvider Example: -pprovider com.acme.sdk.AcmeExportProjectProvider + |
+
+ Optional. Defaults to the + fully qualified class name of ExternalExportProjectProvider + |
+
|
+ -target |
+
+ An absolute or relative path of the resulting file + |
+
+ Needed + |
+
|
+ -properties <key=value> … <key=value> + |
+
+ |
+
+ Optional + |
+
|
+ -quiet + |
+
+ If present, problems, statistics and indexer + activity will be suppressed. + |
+
+ Optional + |
+
Other command-line options +depend on what the project provider specified in –pprovider.
+ +ExternalExportProjectProvider command-line options
+ +ExternalExportProjectProvider +specific command-line options are:
+ +|
+ -source |
+
+ The absolute path of a directory to index.
+ Everything under this directory will be indexed. |
+
+ Needed |
+
|
+ -include |
+
+ An absolute or relative path of a pre-include file |
+
+ Optional |
+
|
+ - id |
+
+ A namespaced identifier
+ identifying the indexed content |
+
+ Optional |
+
+ + +
Invoking the +GeneratePDOM application
+ +As an eclipse application, the +GeneratePDOM application can be invoked in the normal ways that any other +eclipse application can [1]. For initial development, its +most convenient to invoke as a self-hosted eclipse application via a launch +configuration. For integrating into an automated build, either direct +command-line invocation or via an ant build is more convenient.
+ +Invoking as a +self-hosted eclipse application
+ +Running as a self-hosted eclipse +application is straightforward. You will need to have the CDT 4.0 plug-ins +installed, or in your workspace. Then the steps are:
+ +1) +Create a new launch configuration of type “Eclipse +Application”
+ +2) +Choose “Run an application” and select “org.eclipse.cdt.core.GeneratePDOM”
+ +3) +Enter the Arguments to the application as detailed in +the previous sections
+ +Invoking via the +command-line
+ +The PDOM generation application +can be invoked via the command-line. Since version 3.3, the Eclipse
+ +distribution +on Windows includes an “ecilpsec.exe” which is for launching eclipse as a +console application.
+ +Invoking +via an Ant script
+ +An example script invoking the +application via Ant is shown below:
+ ++ + +
Import of index content
+
+Once ISV content has been +generated and distributed to the user’s computer, the mechanism to have that +content appear within a CDT 4.0 session is via another extension point:
+ + org.eclipse.cdt.core.CIndex.ReadOnlyPDOMProvider
An implementation of the IReadOnlyPDOMProvider interface is registered under this +extension point.
+ +IReadOnlyPDOMProvider
+ +Since CDT 4.0, the project model +has the concept of project configurations, which in terms of code corresponds +to the interface:
+ +org.eclipse.cdt.core.settings.model.ICConfigurationDescription
The index model allows content to +be associated with ICConfigurationDescription objects +via the CIndex.ReadOnlyPDOMProvider extension point. +ISV implementations are expected to examine the specified ICConfigurationDescription +object, and determine from its properties (for example, macros and include +paths, or perhaps custom builder properties) which ISV content is relevant.
+ +The interface IReadOnlyPDOMProvider +allows index content contributors to register content related to a particular ICConfigurationDescription. This will be queried +dynamically, so it is important to perform only inexpensive logic in this +method. The resulting IPDOMDescriptor objects will be +used to load PDOM format files into the logical index.
+ +The IPDOMDescriptor +consists of the absolute path of the PDOM format file, and a location converter +suitable for converting from the file’s internal representation of paths to the +runtime IIndexFileLocation objects used by the indexing API. The location +converter must be compatible with the one used on export. Again, a default +implementation is provided. If you exported your index content with +org.eclipse.cdt.core.index.ResourceContainerRelativeLocationConverter then the +location converter org.eclipse.cdt.core.index.URIRelativeLocationConverter +is internal format compatible.
+ +Once the provider is registered +in the CDT extension point, then the pre-built index content will be available +via index-based features in the IDE for the appropriate configurations.
+ +
+
Appendix A
package org.eclipse.cdt.core.index;
/**
* Each IIndexFragment
+stores file location representations in an implementation specific manner.
* External to IIndexFragment
+files are identified by an {@link IIndexFileLocation}
*
* Internal to IIndexFragment
+a mechanism for converting between the string location format used
* and the URI world
+is needed. This interface represents that mechanism.
*/
public interface IIndexLocationConverter
+{
/**
* Convert a
+raw string in an internal IIndexFragment
+implementation specific format to
* an IIndexFileLocation or null if
+the internal format could not be translated.
* @param raw
* @return
*/
public abstract IIndexFileLocation fromInternalFormat(String
+raw);
/**
* Convert a IIndexFileLocation to the
+internal IIndexFragment implementation specific
+format
* or null if the location could not be translated.
* @param location
* @return an
+internal representation for the location specified
*/
public abstract String toInternalFormat(IIndexFileLocation
+location);
}
+ + +
Appendix B
+
+/*******************************************************************************
* Copyright (c) 2006 Symbian Software Ltd. and
+others.
* All rights reserved. This program and the
+accompanying materials
* are made available under the terms of the
+Eclipse Public License v1.0
* which accompanies
+this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*
+Andrew Ferguson (Symbian) - initial API and implementation
*******************************************************************************/
+
package org.eclipse.cdt.core.index;
import java.net.URI;
/**
* Files in the index are (conceptually)
+partitioned into workspace and non-workspace (external) files.
* Clients can obtain instances of
+IIndexFileLocation implementations from {@link IndexLocationFactory}
* <p>
* This interface is not intended to be
+implemented by clients.
* </p>
* <p>
*
+<strong>EXPERIMENTAL</strong>. This class or interface has
+been added as
* part of a work in
+progress. There is no guarantee that this API will work or
* that it will remain
+the same. Please do not use this API without consulting
* with the CDT team.
* </p>
*
* @since 4.0
*/
public
+interface IIndexFileLocation {
/**
* The URI of the indexed file
* @return the URI of the indexed file
+(non-null)
*/
public
+URI getURI();
/**
* Return the workspace relative path of the
+indexed file or null if the file
* is not in the workspace
* @return the workspace relative path of the
+file in the index, or null if the
* file is not in
+the workspace
*/
public
+String getFullPath();
}
+ + +