Package ghidra.app.util.opinion

# Class AbstractLibrarySupportLoader

java.lang.Object
ghidra.app.util.opinion.AbstractProgramLoader
ghidra.app.util.opinion.AbstractLibrarySupportLoader

All Implemented Interfaces:
  `Loader`, `ExtensionPoint`, `Comparable<Loader>`

Direct Known Subclasses:
  `AbstractOrdinalSupportLoader`, `CoffLoader`, `ElfLoader`, `MachoLoader`, `MzLoader`

public abstract class AbstractLibrarySupportLoader extends AbstractProgramLoader
An abstract `Loader` that provides a framework to conveniently load `Program`s with support for linking against libraries contained in other `Program`s.

Subclasses may override various protected methods to customize how libraries are loaded.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static final record`
  `AbstractLibrarySupportLoader.FileSystemSearchPath`
  A file system search path

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEPTH_OPTION_NAME`
  `static final String`
  `LIBRARY_DEST_FOLDER_OPTION_NAME`
  `static final String`
  `LINK_EXISTING_OPTION_NAME`
  `static final String`
  `LINK_SEARCH_FOLDER_OPTION_NAME`
  `static final String`
  `LOCAL_LIBRARY_OPTION_NAME`
  `static final String`
  `SYSTEM_LIBRARY_OPTION_NAME`

  ### Fields inherited from class ghidra.app.util.opinion.AbstractProgramLoader

  `ANCHOR_LABELS_OPTION_NAME, APPLY_LABELS_OPTION_NAME`

  ### Fields inherited from interface ghidra.app.util.opinion.Loader

  `COMMAND_LINE_ARG_PREFIX, OPTIONS_PROJECT_SAVE_STATE_KEY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractLibrarySupportLoader()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected ByteProvider`
  `createLibraryByteProvider(FSRL libFsrl, LoadSpec loadSpec, MessageLog log, TaskMonitor monitor)`
  Creates a `ByteProvider` for the given library `FSRL`
  `protected List<AbstractLibrarySupportLoader.FileSystemSearchPath>`
  `getCustomLibrarySearchPaths(ByteProvider provider, List<Option> options, MessageLog log, TaskMonitor monitor)`
  Gets a `List` of priority-ordered custom `AbstractLibrarySupportLoader.FileSystemSearchPath`s used to search for libraries.
  `List<Option>`
  `getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram)`
  Gets the default `Loader` options.
  `protected String`
  `getLibraryDestinationFolderPath(Project project, String projectFolderPath, List<Option> options)`
  Gets the project folder path to load the libraries into.
  `protected DomainFolder`
  `getLibraryDestinationSearchFolder(Project project, String libraryDestinationFolderPath, List<Option> options)`
  Gets the `project folder` that libraries are loaded into, to search for existing libraries.
  `protected int`
  `getLibraryLoadDepth(List<Option> options)`
  Gets the desired recursive library load depth
  `protected DomainFolder`
  `getLinkSearchFolder(Project project, String projectFolderPath, List<Option> options)`
  Gets the `project folder` to search for existing libraries
  `LoaderTier`
  `getTier()`
  For ordering purposes; lower tier numbers are more important (and listed first).
  `int`
  `getTierPriority()`
  For ordering purposes; lower numbers are more important (and listed first, within its tier).
  `protected boolean`
  `isCaseInsensitiveLibraryFilenames()`
  Specifies if the library filenames specified by this loader should be exact case match or case-insensitive.
  `protected boolean`
  `isLinkExistingLibraries(List<Option> options)`
  Checks to see if existing libraries should be linked
  `protected boolean`
  `isLoadLocalLibraries(List<Option> options)`
  Checks to see if local libraries should be loaded.
  `protected boolean`
  `isLoadSystemLibraries(List<Option> options)`
  Checks to see if system libraries should be loaded.
  `protected boolean`
  `isOptionalLibraryFilenameExtensions()`
  Specifies if this loader can refer to library filenames without filename extensions.
  `protected abstract void`
  `load(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program, TaskMonitor monitor, MessageLog log)`
  Loads bytes in a particular format into the given `Program`.
  `protected List<Loaded<Program>>`
  `loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor)`
  Loads bytes in a particular format as a new `Loaded` `Program`.
  `protected void`
  `loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, Program program, TaskMonitor monitor)`
  Loads program bytes into the specified `Program`.
  `protected LoadSpec`
  `matchSupportedLoadSpec(LoadSpec desiredLoadSpec, ByteProvider provider)`
  Ensures the given `LoadSpec` matches one supported by the loader
  `protected void`
  `postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor)`
  This gets called after the given list of `loaded programs`s is finished loading.
  `protected void`
  `processLibrary(Program library, String libraryName, FSRL libraryFsrl, ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, TaskMonitor monitor)`
  Performs optional follow-on actions after an the given library has been loaded
  `protected FSRL`
  `resolveLibraryFile(GFileSystem fs, Path libraryParentPath, String libraryName)`
  Resolves the given library path to an existing `FSRL`.
  `protected boolean`
  `shouldLoadLibrary(String libraryName, FSRL libraryFsrl, ByteProvider provider, LoadSpec desiredLoadSpec, MessageLog log)`
  Checks whether or not the given library should be loaded.
  `protected boolean`
  `shouldSearchAllPaths(List<Option> options)`
  Checks whether or not to search for libraries using all possible search paths, regardless of what options are set
  `String`
  `validateOptions(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program)`
  Validates the `Loader`'s options and returns null if all options are valid; otherwise, an error message describing the problem is returned.

  ### Methods inherited from class ghidra.app.util.opinion.AbstractProgramLoader

  `concatenatePaths, createDefaultMemoryBlocks, createProgram, generateBlockName, getLanguageService, load, loadInto, markAsFunction, postLoadCleanup, release, setProgramProperties, shouldApplyProcessorLabelsByDefault`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.app.util.opinion.Loader

  `compareTo, findSupportedLoadSpecs, getName, getPreferredFileName, loadsIntoNewFolder, supportsLoadIntoProgram, supportsLoadIntoProgram`

- ## Field Details

  - ### LINK_EXISTING_OPTION_NAME

    public static final String LINK_EXISTING_OPTION_NAME
    See Also:
      - Constant Field Values

  - ### LINK_SEARCH_FOLDER_OPTION_NAME

    public static final String LINK_SEARCH_FOLDER_OPTION_NAME
    See Also:
      - Constant Field Values

  - ### LOCAL_LIBRARY_OPTION_NAME

    public static final String LOCAL_LIBRARY_OPTION_NAME
    See Also:
      - Constant Field Values

  - ### SYSTEM_LIBRARY_OPTION_NAME

    public static final String SYSTEM_LIBRARY_OPTION_NAME
    See Also:
      - Constant Field Values

  - ### DEPTH_OPTION_NAME

    public static final String DEPTH_OPTION_NAME
    See Also:
      - Constant Field Values

  - ### LIBRARY_DEST_FOLDER_OPTION_NAME

    public static final String LIBRARY_DEST_FOLDER_OPTION_NAME
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### AbstractLibrarySupportLoader

    public AbstractLibrarySupportLoader()

- ## Method Details

  - ### load

    protected abstract void load(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program, TaskMonitor monitor, MessageLog log) throws CancelledException, IOException
    Loads bytes in a particular format into the given `Program`.
    Parameters:
      `provider` - The bytes to load.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `program` - The `Program` to load into.
      `monitor` - A cancelable task monitor.
      `log` - The message log.
    Throws:
      `IOException` - if there was an IO-related problem loading.
      `CancelledException` - if the user cancelled the load.

  - ### loadProgram

    protected List<Loaded<Program>> loadProgram(ByteProvider provider, String loadedName, Project project, String projectFolderPath, LoadSpec loadSpec, List<Option> options, MessageLog log, Object consumer, TaskMonitor monitor) throws CancelledException, IOException
    Description copied from class: `AbstractProgramLoader`
    Loads bytes in a particular format as a new `Loaded` `Program`. Multiple `Program`s may end up getting created, depending on the nature of the format.

    Note that when the load completes, the returned `Loaded` `Program`s are not saved to a project. That is the responsibility of the caller (see `Loaded.save(Project, MessageLog, TaskMonitor)`).

    It is also the responsibility of the caller to release the returned `Loaded` `Program`s with `Loaded.release(Object)` when they are no longer needed.

    Specified by:
      `loadProgram` in class `AbstractProgramLoader`
    Parameters:
      `provider` - The bytes to load.
      `loadedName` - A suggested name for the primary `Loaded` `Program`. This is just a suggestion, and a `Loader` implementation reserves the right to change it. The `Loaded` `Program`s should be queried for their true names using `Loaded.getName()`.
      `project` - The `Project`. Loaders can use this to take advantage of existing `DomainFolder`s and `DomainFile`s to do custom behaviors such as loading libraries. Could be null if there is no project.
      `projectFolderPath` - A suggested project folder path for the `Loaded` `Program`s. This is just a suggestion, and a `Loader` implementation reserves the right to change it for each `Loaded` result. The `Loaded` `Program`s should be queried for their true project folder paths using `Loaded.getProjectFolderPath()`.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `log` - The message log.
      `consumer` - A consumer object for generated `Program`s.
      `monitor` - A task monitor.
    Returns:
      A `List` of one or more `Loaded` `Program`s (created but not saved).
    Throws:
      `CancelledException` - if the user cancelled the load.
      `LoadException` - if the load failed in an expected way.
      `IOException` - if there was an IO-related problem loading.

  - ### loadProgramInto

    protected void loadProgramInto(ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, Program program, TaskMonitor monitor) throws CancelledException, LoadException, IOException
    Description copied from class: `AbstractProgramLoader`
    Loads program bytes into the specified `Program`. This method will not create any new `Program`s. It is only for adding to an existing `Program`.

    NOTE: The loading that occurs in this method will automatically be done in a transaction.

    Specified by:
      `loadProgramInto` in class `AbstractProgramLoader`
    Parameters:
      `provider` - The bytes to load into the `Program`.
      `loadSpec` - The `LoadSpec` to use during load.
      `options` - The load options.
      `log` - The message log.
      `program` - The `Program` to load into.
      `monitor` - A cancelable task monitor.
    Throws:
      `CancelledException` - if the user cancelled the load.
      `LoadException` - if the load failed in an expected way.
      `IOException` - if there was an IO-related problem loading.

  - ### postLoadProgramFixups

    protected void postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Project project, List<Option> options, MessageLog messageLog, TaskMonitor monitor) throws CancelledException, IOException
    Description copied from class: `AbstractProgramLoader`
    This gets called after the given list of `loaded programs`s is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.
    Overrides:
      `postLoadProgramFixups` in class `AbstractProgramLoader`
    Parameters:
      `loadedPrograms` - The `loaded programs` to be fixed up.
      `project` - The `Project` to load into. Could be null if there is no project.
      `options` - The load options.
      `messageLog` - The message log.
      `monitor` - A cancelable task monitor.
    Throws:
      `CancelledException` - if the user cancelled the load.
      `IOException` - if there was an IO-related problem loading.

  - ### getTier

    public LoaderTier getTier()
    Description copied from interface: `Loader`
    For ordering purposes; lower tier numbers are more important (and listed first).
    Returns:
      the tier of the loader

  - ### getTierPriority

    public int getTierPriority()
    Description copied from interface: `Loader`
    For ordering purposes; lower numbers are more important (and listed first, within its tier).
    Returns:
      the ordering of the loader within its tier

  - ### getDefaultOptions

    public List<Option> getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram)
    Description copied from interface: `Loader`
    Gets the default `Loader` options.
    Specified by:
      `getDefaultOptions` in interface `Loader`
    Overrides:
      `getDefaultOptions` in class `AbstractProgramLoader`
    Parameters:
      `provider` - The bytes of the thing being loaded.
      `loadSpec` - The `LoadSpec`.
      `domainObject` - The `DomainObject` being loaded.
      `loadIntoProgram` - True if the load is adding to an existing `DomainObject`; otherwise, false.
    Returns:
      A list of the `Loader`'s default options.

  - ### validateOptions

    public String validateOptions(ByteProvider provider, LoadSpec loadSpec, List<Option> options, Program program)
    Description copied from interface: `Loader`
    Validates the `Loader`'s options and returns null if all options are valid; otherwise, an error message describing the problem is returned.
    Specified by:
      `validateOptions` in interface `Loader`
    Overrides:
      `validateOptions` in class `AbstractProgramLoader`
    Parameters:
      `provider` - The bytes of the thing being loaded.
      `loadSpec` - The proposed `LoadSpec`.
      `options` - The list of `Option`s to validate.
      `program` - existing program if the loader is adding to an existing program. If it is a fresh import, then this will be null.
    Returns:
      null if all `Option`s are valid; otherwise, an error message describing the problem is returned.

  - ### isLinkExistingLibraries

    protected boolean isLinkExistingLibraries(List<Option> options)
    Checks to see if existing libraries should be linked
    Parameters:
      `options` - a `List` of `Option`s
    Returns:
      True if existing libraries should be linked; otherwise, false

  - ### getLinkSearchFolder

    protected DomainFolder getLinkSearchFolder(Project project, String projectFolderPath, List<Option> options)
    Gets the `project folder` to search for existing libraries
    Parameters:
      `project` - The `Project`. Could be null if there is no project.
      `projectFolderPath` - The project folder path the program will get saved to. Could be null if the program is not getting saved to the project.
      `options` - a `List` of `Option`s
    Returns:
      The path of the project folder to search for existing libraries, or null if no project folders can be or should be searched

  - ### isLoadLocalLibraries

    protected boolean isLoadLocalLibraries(List<Option> options)
    Checks to see if local libraries should be loaded. Local libraries are libraries that live in the same directory as the imported program.
    Parameters:
      `options` - a `List` of `Option`s
    Returns:
      True if local libraries should be loaded; otherwise, false

  - ### isLoadSystemLibraries

    protected boolean isLoadSystemLibraries(List<Option> options)
    Checks to see if system libraries should be loaded. System libraries are libraries that live in the directories specified in the GUI path list.
    Parameters:
      `options` - a `List` of `Option`s
    Returns:
      True if system libraries should be loaded; otherwise, false

  - ### getLibraryLoadDepth

    protected int getLibraryLoadDepth(List<Option> options)
    Gets the desired recursive library load depth
    Parameters:
      `options` - a `List` of `Option`s
    Returns:
      The desired recursive library load depth

  - ### getLibraryDestinationFolderPath

    protected String getLibraryDestinationFolderPath(Project project, String projectFolderPath, List<Option> options)
    Gets the project folder path to load the libraries into. It does not have to exist in the project yet.
    Parameters:
      `project` - The `Project`. Could be null if there is no project.
      `projectFolderPath` - The project folder path the program will get saved to. Could be null if the program is not getting saved to the project.
      `options` - a `List` of `Option`s
    Returns:
      The path of the project folder to load the libraries into. Could be null if the specified project is null or a destination folder path could not be determined.

  - ### getLibraryDestinationSearchFolder

    protected DomainFolder getLibraryDestinationSearchFolder(Project project, String libraryDestinationFolderPath, List<Option> options)
    Gets the `project folder` that libraries are loaded into, to search for existing libraries. It will only be returned if the options to load new libraries into the project are set.
    Parameters:
      `project` - The `Project`. Could be null if there is no project.
      `libraryDestinationFolderPath` - The path of the project folder to load the libraries into. Could be null (@see #getLibraryDestinationFolderPath(Project, String, List)).
      `options` - a `List` of `Option`s
    Returns:
      The path of the destination project folder to search for existing libraries, or null if the destination folder is not being used or should not be searched

  - ### shouldSearchAllPaths

    protected boolean shouldSearchAllPaths(List<Option> options)
    Checks whether or not to search for libraries using all possible search paths, regardless of what options are set
    Parameters:
      `options` - a `List` of `Option`s
    Returns:
      True if all possible search paths should be used, regardless of what options are set

  - ### isCaseInsensitiveLibraryFilenames

    protected boolean isCaseInsensitiveLibraryFilenames()
    Specifies if the library filenames specified by this loader should be exact case match or case-insensitive.

    Derived loader classes should override this method and specify if the OS that normally handles this type of binary is case-insensitive.

    Returns:
      True if case-insensitive or false if case-sensitive.

  - ### isOptionalLibraryFilenameExtensions

    protected boolean isOptionalLibraryFilenameExtensions()
    Specifies if this loader can refer to library filenames without filename extensions.

    Derived loader classes should override this method if library filename extensions are optional. If they are required, there is no need to override this method.

    Returns:
      True if library filename extensions are optional; otherwise, false

  - ### createLibraryByteProvider

    protected ByteProvider createLibraryByteProvider(FSRL libFsrl, LoadSpec loadSpec, MessageLog log, TaskMonitor monitor) throws IOException, CancelledException
    Creates a `ByteProvider` for the given library `FSRL`
    Parameters:
      `libFsrl` - The library `FSRL` to get a `ByteProvider` for
      `loadSpec` - An optional `LoadSpec` the `ByteProvider` should conform to
      `log` - The log
      `monitor` - A cancellable monitor
    Returns:
      A `ByteProvider` for the given library `FSRL`, or null if one could not be created that matches the given `LoadSpec`
    Throws:
      `IOException` - If there was an IO-related issue
      `CancelledException` - If the user cancelled the operation

  - ### shouldLoadLibrary

    protected boolean shouldLoadLibrary(String libraryName, FSRL libraryFsrl, ByteProvider provider, LoadSpec desiredLoadSpec, MessageLog log) throws IOException
    Checks whether or not the given library should be loaded.

    It may be appropriate to not load a specific library after examining its bytes.

    Parameters:
      `libraryName` - The name of the library
      `libraryFsrl` - The library `FSRL`
      `provider` - The library bytes
      `desiredLoadSpec` - The desired `LoadSpec`
      `log` - The log
    Returns:
      True if the given library should be loaded; otherwise, false
    Throws:
      `IOException` - If an IO-related error occurred

  - ### processLibrary

    protected void processLibrary(Program library, String libraryName, FSRL libraryFsrl, ByteProvider provider, LoadSpec loadSpec, List<Option> options, MessageLog log, TaskMonitor monitor) throws IOException, CancelledException
    Performs optional follow-on actions after an the given library has been loaded
    Parameters:
      `library` - The loaded library `Program`
      `libraryName` - The name of the library
      `libraryFsrl` - The library `FSRL`
      `provider` - The library bytes
      `loadSpec` - The `LoadSpec` used for the load
      `options` - The options
      `log` - The log
      `monitor` - A cancelable monitor
    Throws:
      `IOException` - If an IO-related error occurred
      `CancelledException` - If the user cancelled the action

  - ### getCustomLibrarySearchPaths

    protected List<AbstractLibrarySupportLoader.FileSystemSearchPath> getCustomLibrarySearchPaths(ByteProvider provider, List<Option> options, MessageLog log, TaskMonitor monitor)
    Gets a `List` of priority-ordered custom `AbstractLibrarySupportLoader.FileSystemSearchPath`s used to search for libraries. The default implementation of this method returns an empty `List`. Subclasses can override it as needed.
    Parameters:
      `provider` - The `ByteProvider` of the program being loaded
      `options` - The options
      `log` - The log
      `monitor` - A cancelable task monitor
    Returns:
      A `List` of priority-ordered custom `AbstractLibrarySupportLoader.FileSystemSearchPath`s used to search for libraries

  - ### matchSupportedLoadSpec

    protected LoadSpec matchSupportedLoadSpec(LoadSpec desiredLoadSpec, ByteProvider provider) throws IOException
    Ensures the given `LoadSpec` matches one supported by the loader
    Parameters:
      `desiredLoadSpec` - The desired `LoadSpec`
      `provider` - The provider
    Returns:
      A supported `LoadSpec` that matches the desired one, or null of none matched
    Throws:
      `IOException` - if there was an IO-related error

  - ### resolveLibraryFile

    protected FSRL resolveLibraryFile(GFileSystem fs, Path libraryParentPath, String libraryName) throws IOException
    Resolves the given library path to an existing `FSRL`. Some `Loader`s have relaxed requirements on what counts as a valid library filename match. For example, case-insensitive lookup may be allowed, and filename extensions may be optional.
    Parameters:
      `fs` - The `file system` to resolve in
      `libraryParentPath` - The `Path` of the libraries parent directory, relative to the given file system (could be null)
      `libraryName` - The library name
    Returns:
      The library resolved to an existing `FSRL`, or null if it did not resolve
    Throws:
      `IOException` - If an IO-related problem occurred