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 Programs with support for linking against libraries contained in other Programs.

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.LibrarySearchPath	A library search path
protected static final record	AbstractLibrarySupportLoader.UnprocessedLibrary	A library that has not been processed by the loader yet

Nested classes/interfaces inherited from interface ghidra.app.util.opinion.Loader

Loader.ImporterSettings

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEPTH_OPTION_NAME	How many levels of libraries to load
static final String	LIBRARY_DEST_FOLDER_OPTION_NAME	Path of a DomainFolder to save libraries to.
static final String	LIBRARY_SEARCH_PATH_DUMMY_OPTION_NAME	A dummy option used to produce a custom renderer to select library search paths.
static final String	LINK_EXISTING_OPTION_NAME	Option to attempt to fix up the Loaded Program's external programs with libraries discovered in the project.
static final String	LINK_SEARCH_FOLDER_OPTION_NAME	Path of a DomainFolder to search for libraries
static final String	LOAD_LIBRARY_OPTION_NAME	Whether or not to search for libraries on disk (or in a GFileSystem)
static final String	LOAD_ONLY_LIBRARIES_OPTION_NAME	A hidden option used by the ImporterPlugin's "Load Libraries" action to inform this Loader that the Program to import has already been saved to the project and is currently open, and that only libraries should be loaded.
static final String	MIRROR_LAYOUT_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, loggingDisabled, 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 Loaded<Program>	findLibraryInLoadedList(List<Loaded<Program>> loadedPrograms, String library)	Find the library within the given List of Loaded Programs
protected DomainFile	findLibraryInProject(String library, DomainFolder folder, List<AbstractLibrarySupportLoader.LibrarySearchPath> searchPaths, Loader.ImporterSettings settings)	Find the library within the specified DomainFolder.
protected List<AbstractLibrarySupportLoader.LibrarySearchPath>	getCustomLibrarySearchPaths(ByteProvider provider, List<Option> options, MessageLog log, TaskMonitor monitor)	Gets a List of priority-ordered custom AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries.
List<Option>	getDefaultOptions(ByteProvider provider, LoadSpec loadSpec, DomainObject domainObject, boolean loadIntoProgram, boolean mirrorFsLayout)	Gets the default Loader options.
protected String	getLibraryDestinationFolderPath(Loader.ImporterSettings settings)	Gets the project folder path to load the libraries into.
protected DomainFolder	getLibraryDestinationSearchFolder(String libraryDestinationFolderPath, Loader.ImporterSettings settings)	Gets the project folder that libraries are loaded into, to search for existing libraries.
protected int	getLibraryLoadDepth(Loader.ImporterSettings settings)	Gets the desired recursive library load depth
protected Comparator<String>	getLibraryNameComparator()	Returns a Comparator for comparing library names.
protected List<DomainFolder>	getLibrarySearchFolders(List<Loaded<Program>> loadedPrograms, Loader.ImporterSettings settings)	Gets a List of library search folders based on the current options
protected List<AbstractLibrarySupportLoader.LibrarySearchPath>	getLibrarySearchPaths(Program program, Loader.ImporterSettings settings)	Gets a List of priority-ordered AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries
protected DomainFolder	getLinkSearchFolder(Program program, Loader.ImporterSettings settings)	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	isLinkExistingLibraries(Loader.ImporterSettings settings)	Checks to see if existing libraries should be linked
protected boolean	isLoadLibraries(Loader.ImporterSettings settings)	Checks to see if libraries from disk should be loaded
protected boolean	isMirroredLayout(Loader.ImporterSettings settings)	Checks to see if library organization mirrors filesystem layout
protected boolean	isValidSearchPath(FSRL fsrl, Loader.ImporterSettings settings)	Checks to make sure the given search path FSRL is valid before processing it.
protected abstract void	load(Program program, Loader.ImporterSettings settings)	Loads bytes in a particular format into the given Program.
protected List<Loaded<Program>>	loadProgram(Loader.ImporterSettings settings)	Loads bytes in a particular format as a new Loaded Program.
protected void	loadProgramInto(Program program, Loader.ImporterSettings settings)	Loads program bytes into the specified Program.
protected DomainFile	lookupLibraryInFolder(String libraryName, DomainFolder folder)	Looks in the given DomainFolder for the given name using the loader's library name comparator
protected GFile	lookupLibraryInFs(String library, GFileSystem fs)	Looks in the given GFileSystem for the given library using the loader's library name comparator
protected LoadSpec	matchSupportedLoadSpec(LoadSpec desiredLoadSpec, ByteProvider provider)	Ensures the given LoadSpec matches one supported by the loader
protected void	postLoadProgramFixups(List<Loaded<Program>> loadedPrograms, Loader.ImporterSettings settings)	This gets called after the given list of loaded programss is finished loading.
protected void	processLibrary(Program library, String libraryName, FSRL libraryFsrl, Queue<AbstractLibrarySupportLoader.UnprocessedLibrary> unprocessed, int depth, Loader.ImporterSettings settings)	Performs optional follow-on actions after an the given library has been loaded
protected boolean	shouldLoadOnlyLibraries(Loader.ImporterSettings settings)	Checks to see if only libraries should be loaded (i.e., not the main program)
protected boolean	shouldSearchAllPaths(Program program, Loader.ImporterSettings settings)	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

addExternalBlock, createDefaultMemoryBlocks, createProgram, createProgram, generateBlockName, getLanguageService, load, loadInto, markAsFunction, postLoadCleanup, 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

Option to attempt to fix up the Loaded Program's external programs with libraries discovered in the project. This alone does not cause new library programs to be loaded.

See Also:

• Constant Field Values

LINK_SEARCH_FOLDER_OPTION_NAME

public static final String LINK_SEARCH_FOLDER_OPTION_NAME

Path of a DomainFolder to search for libraries

See Also:

• Constant Field Values

LOAD_LIBRARY_OPTION_NAME

public static final String LOAD_LIBRARY_OPTION_NAME

Whether or not to search for libraries on disk (or in a GFileSystem)

See Also:

• Constant Field Values

LIBRARY_SEARCH_PATH_DUMMY_OPTION_NAME

public static final String LIBRARY_SEARCH_PATH_DUMMY_OPTION_NAME

A dummy option used to produce a custom renderer to select library search paths.

See Also:

• LibrarySearchPathDummyOption
• Constant Field Values

DEPTH_OPTION_NAME

public static final String DEPTH_OPTION_NAME

How many levels of libraries to load

See Also:

• Constant Field Values

LIBRARY_DEST_FOLDER_OPTION_NAME

public static final String LIBRARY_DEST_FOLDER_OPTION_NAME

Path of a DomainFolder to save libraries to. This location will also be used as a location to search for already-loaded libraries.

See Also:

• Constant Field Values

MIRROR_LAYOUT_OPTION_NAME

public static final String MIRROR_LAYOUT_OPTION_NAME

See Also:

• Constant Field Values

LOAD_ONLY_LIBRARIES_OPTION_NAME

public static final String LOAD_ONLY_LIBRARIES_OPTION_NAME

A hidden option used by the ImporterPlugin's "Load Libraries" action to inform this Loader that the Program to import has already been saved to the project and is currently open, and that only libraries should be loaded.

See Also:

• Constant Field Values

Constructor Details

AbstractLibrarySupportLoader

public AbstractLibrarySupportLoader()

Method Details

load

protected abstract void load(Program program,
 Loader.ImporterSettings settings)
                      throws CancelledException,
IOException

Loads bytes in a particular format into the given Program.

Parameters:

program - The Program to load into.

settings - The Loader.ImporterSettings

Throws:

IOException - if there was an IO-related problem loading.

CancelledException - if the user cancelled the load.

loadProgram

protected List<Loaded<Program>> loadProgram(Loader.ImporterSettings settings)
                                     throws CancelledException,
IOException

Loads bytes in a particular format as a new Loaded Program. Multiple Programs may end up getting created, depending on the nature of the format.

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

It is also the responsibility of the caller to close the returned Loaded Programs with Loaded.close() when they are no longer needed.

In addition to loading the given program bytes, this implementation will attempt to locate the libraries that the program links to from the project library search folder, the library destination folder and the libraries found on disk. All of these locations are controlled by loader options.

If the hidden LOAD_ONLY_LIBRARIES_OPTION_NAME option is set and the given project is not null, it is assumed that a DomainFile exists at projectFolderPath/loadedName, is open, and the provider corresponds to its contents. If this is the case, the primary (first) Loaded Program in the returned list will NOT be affected by a LoadResults.save(TaskMonitor) operation. It will be the responsibility of the user to save this open program if desired.

Specified by:

loadProgram in class AbstractProgramLoader

Parameters:

settings - The Loader.ImporterSettings.

Returns:

A List of one or more Loaded Programs (created but not saved). The first element in the List will the primary program, with the remaining elements being any newly loaded libraries.

Throws:

LoadException - if the load failed in an unexpected way. If the LOAD_ONLY_LIBRARIES_OPTION_NAME option is set, this exception will be thrown if the DomainFile at projectFolderPath/loadedName does not correspond to an open Program.

CancelledException - if the user cancelled the load.

IOException - if there was an IO-related problem loading.

loadProgramInto

protected void loadProgramInto(Program program,
 Loader.ImporterSettings settings)
                        throws CancelledException,
LoadException,
IOException

Description copied from class: AbstractProgramLoader

Loads program bytes into the specified Program. This method will not create any new Programs. 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:

program - The Program to load into.

settings - The Loader.ImporterSettings.

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,
 Loader.ImporterSettings settings)
                              throws CancelledException,
IOException

This gets called after the given list of loaded programss is finished loading. It provides subclasses an opportunity to do follow-on actions to the load.

Fix up program's external library entries so that they point to a path in the project.

Overrides:

postLoadProgramFixups in class AbstractProgramLoader

Parameters:

loadedPrograms - The loaded programs to be fixed up.

settings - The Loader.ImporterSettings.

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,
 boolean mirrorFsLayout)

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.

mirrorFsLayout - True if the filesystem layout should be mirrored when loading; 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 Options 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 Options are valid; otherwise, an error message describing the problem is returned.

isLinkExistingLibraries

protected boolean isLinkExistingLibraries(Loader.ImporterSettings settings)

Checks to see if existing libraries should be linked

Parameters:

settings - The Loader.ImporterSettings

Returns:

True if existing libraries should be linked; otherwise, false

getLinkSearchFolder

protected DomainFolder getLinkSearchFolder(Program program,
 Loader.ImporterSettings settings)

Gets the project folder to search for existing libraries

Parameters:

program - The Program being loaded

settings - The Loader.ImporterSettings

Returns:

The path of the project folder to search for existing libraries, or null if no project folders can be or should be searched

isLoadLibraries

protected boolean isLoadLibraries(Loader.ImporterSettings settings)

Checks to see if libraries from disk should be loaded

Parameters:

settings - The Loader.ImporterSettings

Returns:

True if libraries from disk should be loaded; otherwise, false

isMirroredLayout

protected boolean isMirroredLayout(Loader.ImporterSettings settings)

Checks to see if library organization mirrors filesystem layout

Parameters:

settings - The Loader.ImporterSettings

Returns:

True if library organization mirrors filesystem layout; false if flat layout

shouldLoadOnlyLibraries

protected boolean shouldLoadOnlyLibraries(Loader.ImporterSettings settings)

Checks to see if only libraries should be loaded (i.e., not the main program)

Parameters:

settings - The Loader.ImporterSettings

Returns:

True if only libraries should be loaded; otherwise, false

getLibraryLoadDepth

protected int getLibraryLoadDepth(Loader.ImporterSettings settings)

Gets the desired recursive library load depth

Parameters:

settings - The Loader.ImporterSettings

Returns:

The desired recursive library load depth

getLibraryDestinationFolderPath

protected String getLibraryDestinationFolderPath(Loader.ImporterSettings settings)

Gets the project folder path to load the libraries into. It does not have to exist in the project yet.

Parameters:

settings - The Loader.ImporterSettings

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(String libraryDestinationFolderPath,
 Loader.ImporterSettings settings)

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:

libraryDestinationFolderPath - The path of the project folder to load the libraries into. Could be null (@see #getLibraryDestinationFolderPath(Project, String, List)).

settings - The Loader.ImporterSettings

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

getLibrarySearchFolders

protected List<DomainFolder> getLibrarySearchFolders(List<Loaded<Program>> loadedPrograms,
 Loader.ImporterSettings settings)

Gets a List of library search folders based on the current options

Parameters:

loadedPrograms - the list of Loaded Programs

settings - The Loader.ImporterSettings

Returns:

A List of library search folders based on the current options

shouldSearchAllPaths

protected boolean shouldSearchAllPaths(Program program,
 Loader.ImporterSettings settings)

Checks whether or not to search for libraries using all possible search paths, regardless of what options are set

Parameters:

program - The Program being loaded

settings - The Loader.ImporterSettings

Returns:

True if all possible search paths should be used, regardless of what options are set

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

processLibrary

protected void processLibrary(Program library,
 String libraryName,
 FSRL libraryFsrl,
 Queue<AbstractLibrarySupportLoader.UnprocessedLibrary> unprocessed,
 int depth,
 Loader.ImporterSettings settings)
                       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

unprocessed - The Queue of unprocessed libraries

depth - The load depth of the library to load

settings - The Loader.ImporterSettings

Throws:

IOException - If an IO-related error occurred

CancelledException - If the user cancelled the action

findLibraryInProject

protected DomainFile findLibraryInProject(String library,
 DomainFolder folder,
 List<AbstractLibrarySupportLoader.LibrarySearchPath> searchPaths,
 Loader.ImporterSettings settings)
                                   throws CancelledException

Find the library within the specified DomainFolder.

If the library path is a simple name without any path separators, only the given folder will be searched.

If the library path has a path, it will be treated as a relative path under given folder and if found that DomainFile will be returned.

If the library path has a path and it wasn't found under the given folder, the filename part of library path will be used to search the given folder for matches.

Parameters:

library - The library to find. Depending on the type of library, this could be a simple filename or an absolute path.

folder - root folder within which imported libraries will be searched. If null this method will return null.

searchPaths - A List of AbstractLibrarySupportLoader.LibrarySearchPaths that will be searched

settings - The Loader.ImporterSettings

Returns:

The found DomainFile or null if not found

Throws:

CancelledException - if the user cancelled the load

lookupLibraryInFolder

protected DomainFile lookupLibraryInFolder(String libraryName,
 DomainFolder folder)

Looks in the given DomainFolder for the given name using the loader's library name comparator

Parameters:

libraryName - The library name to search for (no path included)

folder - The DomainFolder to search in

Returns:

A matching library DomainFile, or null if one was not found

getCustomLibrarySearchPaths

protected List<AbstractLibrarySupportLoader.LibrarySearchPath> getCustomLibrarySearchPaths(ByteProvider provider,
 List<Option> options,
 MessageLog log,
 TaskMonitor monitor)
                                                                                    throws CancelledException

Gets a List of priority-ordered custom AbstractLibrarySupportLoader.LibrarySearchPaths 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.LibrarySearchPaths used to search for libraries

Throws:

CancelledException - if the user cancelled the load

isValidSearchPath

protected boolean isValidSearchPath(FSRL fsrl,
 Loader.ImporterSettings settings)
                             throws CancelledException

Checks to make sure the given search path FSRL is valid before processing it. Subclasses can override it as needed.

Parameters:

fsrl - The search path FSRL

settings - The Loader.ImporterSettings

Returns:

True is the search path is valid; otherwise, false

Throws:

CancelledException - if the user cancelled the load

getLibrarySearchPaths

protected List<AbstractLibrarySupportLoader.LibrarySearchPath> getLibrarySearchPaths(Program program,
 Loader.ImporterSettings settings)
                                                                              throws CancelledException

Gets a List of priority-ordered AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries

Parameters:

program - The Program being loaded

settings - The Loader.ImporterSettings

Returns:

A List of priority-ordered AbstractLibrarySupportLoader.LibrarySearchPaths used to search for libraries

Throws:

CancelledException - if the user cancelled the load

findLibraryInLoadedList

protected Loaded<Program> findLibraryInLoadedList(List<Loaded<Program>> loadedPrograms,
 String library)

Find the library within the given List of Loaded Programs

Parameters:

loadedPrograms - the list of Loaded Programs

library - The library name to lookup. Depending on the type of library, this could be a simple filename or an absolute path.

Returns:

The found Loaded Program or null if not found

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

lookupLibraryInFs

protected GFile lookupLibraryInFs(String library,
 GFileSystem fs)
                           throws IOException

Looks in the given GFileSystem for the given library using the loader's library name comparator

Parameters:

library - The library. Depending on the type of library, this could be a simple filename or an absolute path.

fs - The file system to look in in

Returns:

A matching library GFile, or null if one was not found

Throws:

IOException - If an IO-related problem occurred

getLibraryNameComparator

protected Comparator<String> getLibraryNameComparator()

Returns a Comparator for comparing library names.

No assumptions should be made about whether the library name includes path information or not.

Returns:

a Comparator for comparing library names