Package ghidra.base.project

# Class GhidraProject

java.lang.Object
ghidra.base.project.GhidraProject

public class GhidraProject extends Object
Helper class for using Ghidra in a "batch" mode. This class provides methods for importing, opening, saving, and analyzing program.

Note: Before using this class you must initialize the Ghidra system. See `Application.initializeApplication(utility.application.ApplicationLayout, ghidra.framework.ApplicationConfiguration)` for more information.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `analyze(Program program)`
  Invokes the auto-analyzer on the program.
  `void`
  `analyze(Program program, boolean debug)`
  Debug version of the auto_analyzer.
  `void`
  `checkPoint(Program program)`
  Creates a checkpoint in the program.
  `void`
  `close()`
  Closes the ghidra project, closing (without saving!) any open programs in that project.
  `void`
  `close(Program program)`
  Closes the given program.
  `static GhidraProject`
  `createProject(String projectDirPath, String projectName, boolean temporary)`
  Creates a new non-shared Ghidra project to be used for storing programs.
  `void`
  `execute(Command<Program> cmd, Program program)`
  Executes the give command on the program.
  `Options`
  `getAnalysisOptions(Program program)`
  Returns a PropertList containing all the analysis option properties that can be set. Changing the value of the analysis properties will affect what happens when the analyze call is made..
  `Project`
  `getProject()`
  Returns the underlying Project instance or null if project was opened for READ access only..
  `ProjectData`
  `getProjectData()`
  Returns the underlying ProjectData instance..
  `DefaultProjectManager`
  `getProjectManager()`
  Returns the project manager
  `DomainFolder`
  `getRootFolder()`
  Returns the root folder for the Ghidra project..
  `static RepositoryAdapter`
  `getServerRepository(String host, int port, String repositoryName, boolean createIfNeeded)`
  Get/Create shared repository.
  `Program`
  `importProgram(File file)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `ProgramLoader`
  `Program`
  `importProgram(File file, Language language, CompilerSpec compilerSpec)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `ProgramLoader`
  `Program`
  `importProgram(File file, Processor processor)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `ProgramLoader`
  `Program`
  `importProgram(File file, Class<? extends Loader> loaderClass)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `ProgramLoader`
  `Program`
  `importProgram(File file, Class<? extends Loader> loaderClass, Language language, CompilerSpec compilerSpec)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `ProgramLoader`
  `Program`
  `importProgramFast(File file)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `ProgramLoader`
  `Program`
  `openProgram(String folderPath, String programName, boolean readOnly)`
  Opens a program.
  `static GhidraProject`
  `openProject(String projectsDir, String projectName)`
  Returns an instance of an open Ghidra Project that can be used to open/save programs.
  `static GhidraProject`
  `openProject(String projectsDir, String projectName, boolean restoreProject)`
  Returns an instance of an open Ghidra Project that can be used to open/save programs.
  `void`
  `rollback(Program program)`
  Rolls back any changes to the program since the last checkpoint.
  `void`
  `save(Program program)`
  Saves any changes in the program back to its file.
  `void`
  `saveAs(Program program, String folderPath, String name, boolean overWrite)`
  Saves the given program to the project with the given name.
  `void`
  `saveAsPackedFile(Program program, File file, boolean overWrite)`
  Saves the given program to as a packed file.
  `void`
  `setDeleteOnClose(boolean toDelete)`
  Updates the flag passed to this project at construction time.

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

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

- ## Method Details

  - ### openProject

    public static GhidraProject openProject(String projectsDir, String projectName) throws NotFoundException, NotOwnerException, LockException, IOException
    Returns an instance of an open Ghidra Project that can be used to open/save programs.
    Parameters:
      `projectsDir` - the directory containing the Ghidra project.
      `projectName` - the name of the ghidra project.
    Returns:
      an open ghidra project.
    Throws:
      `NotFoundException` - if the file for the project was not found.
      `NotOwnerException` - if the project owner is not the user
      `LockException` - if the project is already opened by another user
      `IOException` - if an IO-related problem occurred

  - ### openProject

    public static GhidraProject openProject(String projectsDir, String projectName, boolean restoreProject) throws NotFoundException, NotOwnerException, LockException, IOException
    Returns an instance of an open Ghidra Project that can be used to open/save programs.
    Parameters:
      `projectsDir` - the directory containing the Ghidra project.
      `projectName` - the name of the ghidra project.
      `restoreProject` - if true the project tool state is restored
    Returns:
      an open ghidra project.
    Throws:
      `NotFoundException` - if the file for the project was not found.
      `NotOwnerException` - if the project owner is not the user
      `LockException` - if the project is already opened by another user
      `IOException` - if an IO-related problem occurred

  - ### createProject

    public static GhidraProject createProject(String projectDirPath, String projectName, boolean temporary) throws IOException
    Creates a new non-shared Ghidra project to be used for storing programs.

    Note: Calling this method will delete any existing project files on disk that match the given project name.

    Parameters:
      `projectDirPath` - the directory path to contain the new Ghidra project.
      `projectName` - the name of the project to be created.
      `temporary` - if true, deletes the project when it is closed - useful for testing.
    Returns:
      an open ghidra project.
    Throws:
      `IOException` - if there was a problem accessing the project

  - ### getServerRepository

    public static RepositoryAdapter getServerRepository(String host, int port, String repositoryName, boolean createIfNeeded) throws DuplicateNameException
    Get/Create shared repository.
    Parameters:
      `host` - Ghidra Server host
      `port` - Ghidra Server port (0 = use default port)
      `repositoryName` - The repository name
      `createIfNeeded` - if true repository will be created if it does not exist
    Returns:
      A `handle` to the new repository
    Throws:
      `DuplicateNameException` - if the repository name already exists

  - ### getProjectManager

    public DefaultProjectManager getProjectManager()
    Returns the project manager
    Returns:
      the project manager

  - ### getProject

    public Project getProject()
    Returns the underlying Project instance or null if project was opened for READ access only..
    Returns:
      the underlying Project instance or null if project was opened for READ access only.

  - ### getProjectData

    public ProjectData getProjectData()
    Returns the underlying ProjectData instance..
    Returns:
      the underlying ProjectData instance.

  - ### close

    public void close()
    Closes the ghidra project, closing (without saving!) any open programs in that project. Also deletes the project if created as a temporary project.

  - ### setDeleteOnClose

    public void setDeleteOnClose(boolean toDelete)
    Updates the flag passed to this project at construction time.
    Parameters:
      `toDelete` - true to delete on close; false in the opposite condition

  - ### close

    public void close(Program program)
    Closes the given program. Any changes in the program will be lost.
    Parameters:
      `program` - the program to close.

  - ### openProgram

    public Program openProgram(String folderPath, String programName, boolean readOnly) throws IOException
    Opens a program.
    Parameters:
      `folderPath` - the path of the program within the project. ("/" is root)
      `programName` - the name of the program to open.
      `readOnly` - flag if the program will only be read and not written.
    Returns:
      an open program.
    Throws:
      `IOException` - if there was a problem accessing the program

  - ### save

    public void save(Program program) throws IOException
    Saves any changes in the program back to its file. If the program does not have an associated file (it was created), then it is an error to call this method, use saveAs instead. Any open transaction will be terminated.
    Parameters:
      `program` - the program to be saved.
    Throws:
      `IOException` - if there was a problem accessing the program

  - ### getRootFolder

    public DomainFolder getRootFolder()
    Returns the root folder for the Ghidra project..
    Returns:
      the root folder for the Ghidra project.

  - ### saveAs

    public void saveAs(Program program, String folderPath, String name, boolean overWrite) throws InvalidNameException, IOException
    Saves the given program to the project with the given name.
    Parameters:
      `program` - the program to be saved
      `folderPath` - the path where to save the program.
      `name` - the name to save the program as.
      `overWrite` - if true, any existing program with that name will be over-written.
    Throws:
      `DuplicateFileException` - if a file exists with that name and overwrite is false or overwrite failed
      `InvalidNameException` - the name is null or has invalid characters.
      `IOException` - if there was a problem accessing the program

  - ### saveAsPackedFile

    public void saveAsPackedFile(Program program, File file, boolean overWrite) throws InvalidNameException, IOException
    Saves the given program to as a packed file.
    Parameters:
      `program` - the program to be saved
      `file` - the packed file destination.
      `overWrite` - if true, any existing program with that name will be over-written.
    Throws:
      `InvalidNameException` - the name is null or has invalid characters.
      `IOException` - if there was a problem accessing the program

  - ### checkPoint

    public void checkPoint(Program program)
    Creates a checkpoint in the program. Any changes since the last checkpoint can be instantly undone by calling the rollback command.
    Parameters:
      `program` - the program to be checkpointed.

  - ### rollback

    public void rollback(Program program)
    Rolls back any changes to the program since the last checkpoint.
    Parameters:
      `program` - the program to be rolled back.

  - ### analyze

    public static void analyze(Program program)
    Invokes the auto-analyzer on the program. Depending on which analyzers are in the classpath, generally will disassemble at entry points, and create and analyze functions that are called.
    Parameters:
      `program` - the program to analyze.

  - ### analyze

    public void analyze(Program program, boolean debug)
    Debug version of the auto_analyzer. Same as regular analyzer except that any stack traces are not trapped.
    Parameters:
      `program` - the program to be analyzed
      `debug` - true to allow stack traces to propagate out.

  - ### getAnalysisOptions

    public Options getAnalysisOptions(Program program)
    Returns a PropertList containing all the analysis option properties that can be set. Changing the value of the analysis properties will affect what happens when the analyze call is made..
    Parameters:
      `program` - the program whose analysis options are to be set.
    Returns:
      a PropertList containing all the analysis option properties that can be set. Changing the value of the analysis properties will affect what happens when the analyze call is made.

  - ### execute

    public void execute(Command<Program> cmd, Program program)
    Executes the give command on the program.
    Parameters:
      `cmd` - the command to be applied to the program.
      `program` - the program on which the command is to be applied.

  - ### importProgram

    @Deprecated(since="12.0", forRemoval=true) public Program importProgram(File file, Language language, CompilerSpec compilerSpec) throws CancelledException, VersionException, LanguageNotFoundException, LoadException, IOException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `ProgramLoader`
    Automatically imports the given `File` with the best matching `Loader` that supports the given language and compiler specification.

    NOTE: It is the responsibility of the caller to release the returned `Program` with `DomainObject.release(Object)` when it is no longer needed, with `this` `GhidraProject` instance as the consumer.

    Parameters:
      `file` - The `File` to import
      `language` - The desired `Language`
      `compilerSpec` - The desired `compiler specification`
    Returns:
      The imported `Program`
    Throws:
      `IOException` - if there was an IO-related problem loading
      `LanguageNotFoundException` - if there was a problem getting the language
      `CancelledException` - if the operation was cancelled
      `VersionException` - if there was an issue with database versions, probably due to a failed language upgrade
      `LoadException` - if there was a problem loading

  - ### importProgram

    @Deprecated(since="12.0", forRemoval=true) public Program importProgram(File file, Processor processor) throws CancelledException, VersionException, LanguageNotFoundException, LoadException, IOException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `ProgramLoader`
    Automatically imports the given `File` with the best matching `Loader` that supports the given processor.

    NOTE: It is the responsibility of the caller to release the returned `Program` with `DomainObject.release(Object)` when it is no longer needed, with `this` `GhidraProject` instance as the consumer.

    Parameters:
      `file` - The `File` to import
      `processor` - The desired `Processor`
    Returns:
      The imported `Program`
    Throws:
      `IOException` - if there was an IO-related problem loading
      `LanguageNotFoundException` - if there was a problem getting the language
      `CancelledException` - if the operation was cancelled
      `VersionException` - if there was an issue with database versions, probably due to a failed language upgrade
      `LoadException` - if there was a problem loading

  - ### importProgram

    @Deprecated(since="12.0", forRemoval=true) public Program importProgram(File file, Class<? extends Loader> loaderClass) throws CancelledException, VersionException, LanguageNotFoundException, LoadException, IOException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `ProgramLoader`
    Automatically imports the given `File` with the given `Loader`.

    NOTE: It is the responsibility of the caller to release the returned `Program` with `DomainObject.release(Object)` when it is no longer needed, with `this` `GhidraProject` instance as the consumer.

    Parameters:
      `file` - The `File` to import
      `loaderClass` - The desired `Loader`
    Returns:
      The imported `Program`
    Throws:
      `IOException` - if there was an IO-related problem loading
      `LanguageNotFoundException` - if there was a problem getting the language
      `CancelledException` - if the operation was cancelled
      `VersionException` - if there was an issue with database versions, probably due to a failed language upgrade
      `LoadException` - if there was a problem loading

  - ### importProgram

    @Deprecated(since="12.0", forRemoval=true) public Program importProgram(File file, Class<? extends Loader> loaderClass, Language language, CompilerSpec compilerSpec) throws CancelledException, VersionException, LanguageNotFoundException, LoadException, IOException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `ProgramLoader`
    Automatically imports the given `File` with the given `Loader`, `Language`, and `compiler specification`.

    NOTE: It is the responsibility of the caller to release the returned `Program` with `DomainObject.release(Object)` when it is no longer needed, with `this` `GhidraProject` instance as the consumer.

    Parameters:
      `file` - The `File` to import
      `loaderClass` - The desired `Loader`
      `language` - The desired `Language`
      `compilerSpec` - The desired `compiler specification`
    Returns:
      The imported `Program`
    Throws:
      `IOException` - if there was an IO-related problem loading
      `LanguageNotFoundException` - if there was a problem getting the language
      `CancelledException` - if the operation was cancelled
      `VersionException` - if there was an issue with database versions, probably due to a failed language upgrade
      `LoadException` - if there was a problem loading

  - ### importProgram

    @Deprecated(since="12.0", forRemoval=true) public Program importProgram(File file) throws CancelledException, VersionException, LanguageNotFoundException, LoadException, IOException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `ProgramLoader`
    Automatically imports the given `File`.

    NOTE: It is the responsibility of the caller to release the returned `Program` with `DomainObject.release(Object)` when it is no longer needed, with `this` `GhidraProject` instance as the consumer.

    Parameters:
      `file` - The `File` to import
    Returns:
      The imported `Program`
    Throws:
      `IOException` - if there was an IO-related problem loading
      `LanguageNotFoundException` - if there was a problem getting the language
      `CancelledException` - if the operation was cancelled
      `VersionException` - if there was an issue with database versions, probably due to a failed language upgrade
      `LoadException` - if there was a problem loading

  - ### importProgramFast

    @Deprecated(since="12.0", forRemoval=true) public Program importProgramFast(File file) throws CancelledException, VersionException, LanguageNotFoundException, LoadException, IOException
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `ProgramLoader`
    Automatically imports the given `File`.

    NOTE: It is the responsibility of the caller to release the returned `Program` with `DomainObject.release(Object)` when it is no longer needed, with `this` `GhidraProject` instance as the consumer.

    Parameters:
      `file` - The `File` to import
    Returns:
      The imported `Program`
    Throws:
      `IOException` - if there was an IO-related problem loading
      `LanguageNotFoundException` - if there was a problem getting the language
      `CancelledException` - if the operation was cancelled
      `VersionException` - if there was an issue with database versions, probably due to a failed language upgrade
      `LoadException` - if there was a problem loading