Package org.eclipse.cdt.core

Interface ISourceFinder

public interface ISourceFinder
This interface is available for a Binary via the adapter mechanism. It is used to translate the file specification of a source file that was used to produce the executable to its local counterpart. In other words, the debug information in the binary tells us what source files where involved in building it. Such a file specification may be a simple file name, a relative path, or an absolute path that might be invalid on the local machine (the executable may have been built on another machine). In all cases, the file is found on the local machine by using source locators (see ISourceLocator). ISourceFinder is a front end to that search capability.

CDT has:

  • A global (common) source locator. Its containers are defined via Window > Preferences > C/C++ > Debug > Source Lookup Path
  • Launch configuration source locators. The containers of such a locator are defined via the 'Source' tab in a CDT launch configuration. The common source containers are automatically added to this locator.
  • Launch source locators. Typically, a launch's locator is the one defined in the launch configuration that spawned the launch, but technically, they could be different. The ILaunch API allows any source locator to be associated with a launch.

So, when trying to translate a source file specification in the debug information to a local file, there are a variety of locators that need to be considered. An ISourceFinder shields client code from having to worry about those details. A client simply wants to find a file locally.

This interface provides two choices for searching. One caters to logic involved in actively debugging a binary (e.g., a breakpoint is hit). The other is for use when there is no debug-session context (double clicking on a child file element of a Binary object in the Projects view). The former will search using only the locator associated with the ILaunch. The latter will use the locator of any relevant launch or launch configuration. In all cases, the global locator is consulted if no other locator has converted the file.

A new instance is created every time a Binary object is queried for this interface. Clients must call dispose() when it is done with the object.

Since:
5.2
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dispose()
    Clients must call this to ensure that the object properly cleans up.
    String
    toLocalPath(String compilationPath)
    Use this method to find a file if you do not have a debug context.
    String
    toLocalPath(org.eclipse.core.runtime.IAdaptable launch, String compilationPath)
    Deprecated.
    This method is unused in CDT code base.

  • Method Details

    • toLocalPath

      String toLocalPath(String compilationPath)
      Use this method to find a file if you do not have a debug context. The implementation will consult locators in the following order:
      1. If there is an ongoing debug session on that binary, use that's ILaunch's locator. If there are multiple such debug sessions going on, the first one encountered is used.
      2. If there are no ongoing debug sessions on that binary that provide a locator, search for a CDT launch configuration that references the binary. Use the locator of the first matching configuration.
      3. If neither of the above result in a locator, explicitly consult the common (global) locator. Note that the common locator's containers are automatically added to every launch configuration locator. So, in effect, the common locator is always searched, and always last.
      In the first two cases, only the first locator of the first matching launch or launch configuration is used, even if that locator doesn't find the file. Potentially, another matching one could find the file, but it could easily get very expensive to iterate through numerous matches that way. Searching for a file using a single launch/config's locator is expensive enough (it has numerous source containers). Searching through multiple ones could make this method unbearably slow. And because finding a matching launch/config can itself be a bit expensive, once a match has been found, its locator is used from that point on in all subsequent calls to this method. The implementation listens for launch and configurations changes, though, so we find a new locator when the active locator is no longer relevant. Note that calls to toLocalPath(IAdaptable, String) have no effect on the active locator we use in this method.
      Parameters:
      compilationPath - the path of a file as found in the debug information
      Returns:
      if we are able to find the file, the location on the host machine, otherwise null. The result is in OS specific format, specifically what File.getCanonicalPath() returns. Note that by "on the host machine", we simply mean a specification that is accessible by the host machine. The file may be on a network drive, e.g., and thus not really be "local".

    • toLocalPath

      @Deprecated String toLocalPath(org.eclipse.core.runtime.IAdaptable launch, String compilationPath)
      Deprecated.
      This method is unused in CDT code base. Use toLocalPath(String) or request undeprecating on the cdt-dev mailing list.
      Restriction:
      This method is not intended to be referenced by clients.

    • dispose

      void dispose()
      Clients must call this to ensure that the object properly cleans up. E.g., a source finder may register itself as a listener for changes that would effect how it searches for files. Calling this method will allow it to unregister itself.