Nixyri/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra.git synced 2024-11-24 13:11:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'GP-0_ryanmkurtz_InstallationGuide'

Browse Source
This commit is contained in:
Ryan Kurtz 2024-10-24 13:30:09 -04:00
commit aff12cd6e0
8 changed files with 464 additions and 1236 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

497
GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/GhidraDev_README.html
View File

@ -1,497 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>GhidraDev README</title>
<style name="text/css">
li { font-family:times new roman; font-size:14pt; font-family:times new roman; font-size:14pt; margin-bottom: 12px; }
h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; }
h2 { padding-top:30px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; }
p { font-family:times new roman; font-size:14pt; }
td { font-family:times new roman; font-size:14pt; padding-left:10px; padding-right:10px; }
th { font-family:times new roman; font-size:14pt; font-weight:bold; padding-left:10px; padding-right:10px; }
code { color:black; font-family:courier new font-size: 14pt; }
span.code { font-family:courier new font-size: 14pt; color:#000000; }
</style>
</head>
<body>
<h1>GhidraDev README</h1>
<p>GhidraDev provides support for developing and debugging Ghidra scripts and modules in Eclipse.
</p>
<p>The information provided in this document is effective as of GhidraDev 4.0.0 and is subject to
change with future releases.</p>
<ul>
<li><a href="#ChangeHistory">Change History</a></li>
<li><a href="#MinimumRequirements">Minimum Requirements</a></li>
<li><a href="#OptionalRequirements">Optional Requirements</a></li>
<li><a href="#Install">Installing</a></li>
<ul>
<li><a href="#ManualInstall">Manual Installation in Eclipse</a></li>
<li><a href="#AutoInstall">Automatic Installation through Ghidra</a></li>
</ul>
<li><a href="#Features">GhidraDev Features</a></li>
<ul>
<li><a href="#NewGhidraScript">New Ghidra Script</a></li>
<li><a href="#NewGhidraScriptProject">New Ghidra Script Project</a></li>
<li><a href="#NewGhidraModuleProject">New Ghidra Module Project</a></li>
<li><a href="#ImportGhidraModuleSource">Import Ghidra Module Source</a></li>
<li><a href="#ExportGhidraModuleExtension">Export Ghidra Module Extension</a></li>
<li><a href="#Preferences">Preferences</a></li>
<li><a href="#LinkGhidra">Link Ghidra</a></li>
</ul>
<li><a href="#Launching">Launching and Debugging Ghidra</a></li>
<li><a href="#PyDevSupport">PyDev Support</a></li>
<ul>
<li><a href="#PyDevInstall">Installing PyDev</a></li>
<li><a href="#PyDevConfigure">Configuring PyDev</a></li>
</ul>
<li><a href="#Upgrade">Upgrading</a></li>
<li><a href="#Uninstall">Uninstalling</a></li>
<li><a href="#FAQ">Frequently Asked Questions</a></li>
<li><a href="#AdditionalResources">Additional Resources</a></li>
</ul>
<h2><a name="ChangeHistory"></a>Change History</h2>
<p><u><b>4.0.0</b>:</u>
<ul>
<li>
GhidraDev has been upgraded to be compatible with Ghidra 11.2 and later. It is not backwards
compatible with versions of Ghidra prior to 11.2. Older versions of GhidraDev will report an
error when trying to link against Ghidra 11.2 or later.
</li>
<li>
GhidraDev now requires Eclipse 2023-12 4.30 or later.
</li>
<li>
GhidraDev now requires JDK 21.
</li>
<li>
Fixed an issue that could result in a <i>GhidraHelpService</i> exception when launching
Ghidra. GhidraDev now properly enforces that Ghidra is only launched with <i>Utility.jar</i> on
the initial classpath.
</li>
</ul>
<p><u><b>3.1.0</b>:</u>
<ul>
<li>
GhidraDev has been upgraded to be compatible with Ghidra 11.1 and later. Older versions of
GhidraDev will report an error when trying to link against Ghidra 11.1 or later.
</li>
<li>
GhidraDev now supports importing a Ghidra module source directory. This will work best
with Ghidra module projects created from Ghidra 11.1 or later.
</li>
<li>
GhidraDev will now fail to launch Ghidra if a top-level <i>build</i> directory is detected.
Presence of this intermediate build artifact can cause Ghidra to have runtime/debugging issues.
</li>
</ul>
<p><u><b>3.0.2</b>:</u>
<ul>
<li>
GhidraDev no longer throws an IOException when performing a "Link Ghidra" action on a Ghidra
project whose original Ghidra installation moved.
</li>
<li>
GhidraDev now prevents unsupported versions of PyDev from being used.
</li>
</ul>
<p><u><b>3.0.1</b>:</u>
<ul>
<li>
Exporting a Ghidra Module Extension produces an intermediate <i>build</i> directory within the
project. This <i>build</i> directory now gets automatically cleaned up to avoid Ghidra
runtime/debugging issues.
</li>
<li>
GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra
installations.
</li>
</ul>
<p><u><b>3.0.0</b>:</u>
<ul>
<li>
GhidraDev now requires Eclipse 2021-12 4.22 or later.
</li>
<li>
GhidraDev now requires JDK 17.
</li>
<li>
Fixed an issue that could cause old extensions to incorrectly remain on the Ghidra project
classpath after performing a "Link Ghidra."
</li>
</ul>
<p><u><b>2.1.5</b>:</u> Eclipse Python breakpoints now work when Eclipse installs PyDev in .p2
bundle pool directory.</p>
<p><u><b>2.1.4</b>:</u> Fixed exception that occurred when performing a "Link Ghidra" on projects
that use a Gradle classpath container.</p>
<p><u><b>2.1.3</b>:</u> Fixed a bug that prevented Ghidra projects from recognizing extensions
installed in the user's <i>~/.ghidra/.ghidra_&lt;version&gt;/Extensions</i> directory.</p>
<p><u><b>2.1.2</b>:</u> Fixed exception that occurred when creating a new Ghidra scripting project
if a <i>~/ghidra_scripts</i> directory does not exist.</p>
<p><u><b>2.1.1</b>:</u>
<ul>
<li>
Python debugging now works when PyDev is installed via the Eclipse "dropins" directory.
</li>
<li>
Fixed a bug in the check that prevents Ghidra projects from being created within the Ghidra
installation directory.
</li>
</ul>
<p><u><b>2.1.0</b>:</u>
<ul>
<li>
Added support for Ghidra 9.1. GhidraDev 2.1.0 will be unable to create new Eclipse projects for
versions of Ghidra earlier than 9.1.
</li>
<li>
Prevented Ghidra projects from being created inside of a Ghidra installation directory.
</li>
<li>
Added an <i>Environments</i> tab to the Ghidra run configuration for setting environment
variables when launching Ghidra.
</li>
</ul>
<p><u><b>2.0.1</b>:</u> Fixed exception that occurred when performing certain actions on a Ghidra
project that was imported from a previously exported Archive File.</p>
<p><u><b>2.0.0</b>:</u>
<ul>
<li>
Improved Ghidra module project starting templates for Analyzer and Plugin and added new
templates for Loader, Exporter, and FileSystem.
</li>
<li>
When creating a new Ghidra project, there is now an option to automatically create a Ghidra run
configuration for the project with a customizable amount of maximum Java heap space.
</li>
<li>
When creating a new Ghidra project, the project root directory now defaults to the workspace
directory if a project root directory has never been set.
</li>
<li>
When creating a new Ghidra project, the add button in the Python Support wizard page now
automatically adds the Jython interpreter found in the Ghidra installation directory to PyDev if
PyDev does have any Jython interpreters configured.
</li>
<li>
A Ghidra project's dependencies that are also projects are now passed along to a launched
Ghidra so Ghidra can discover those projects as potential modules.
</li>
<li>
The GhidraDev popup menu is now visible from within the Project Explorer (it was previously only
visible in the Package Explorer).
</li>
<li>
A new page has been added to the Export Ghidra Module Extension wizard that allows the user to
point to a specific Gradle installation.
</li>
</ul>
<p><u><b>1.0.2</b>:</u> Fixed exception that occurred when performing a "Link Ghidra" on projects
that specify other projects on their build paths.</p>
<p><u><b>1.0.1</b>:</u> Initial Release.</p>
<h2><a name="MinimumRequirements"></a>Minimum Requirements</h2>
<ul>
<li>Eclipse 2023-12 4.30 or later</li>
<li>Ghidra 11.2 or later</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="OptionalRequirements"></a>Optional Requirements</h2>
<ul>
<li>PyDev 6.3.1 - 9.3.0 (<a href="#PyDevSupport">more info</a>)</li>
<li>CDT 8.6.0 or later</li>
<li>
Gradle - required version(s) specified by linked Ghidra release
(<a href="#ExportGhidraModuleExtension">more info</a>)
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Install"></a>Installing GhidraDev</h2>
<p>GhidraDev can be installed either manually into Eclipse or automatically by Ghidra, depending on
your uses cases. The following two sections outline both procedures.</p>
<h3><a name="ManualInstall"></a>Manual Installation in Eclipse</h3>
<p>GhidraDev can be installed into an existing installation of Eclipse the same way most Eclipse
plugins are installed. From Eclipse:</p>
<ol>
<li>Click <b>Help &#8594; Install New Software...</b></li>
<li>Click <b>Add...</b></li>
<li>Click <b>Archive...</b></li>
<li>
Select GhidraDev zip file from <i>&lt;GhidraInstallDir&gt;</i>/Extensions/Eclipse/GhidraDev/
</li>
<li>Click <b>OK</b> (name field can be blank)</li>
<li>Check <b>Ghidra</b> category (or <b>GhidraDev</b> entry)</li>
<li>Click <b>Next</b></li>
<li>Click <b>Next</b></li>
<li>Accept the terms of the license agreement</li>
<li>Click <b>Finish</b></li>
<li>Check <b>Unsigned</b> table entry</li>
<li>Click <b>Trust Selected</b></li>
<li>Click <b>Restart Now</b></li>
</ol>
<h3><a name="AutoInstall"></a>Automatic Installation through Ghidra</h3>
<p>Ghidra has the ability to launch an externally linked Eclipse when certain actions are performed,
such as choosing to edit a Ghidra script by clicking the Eclipse icon in the Ghidra Script Manager.
Ghidra requires knowledge of where Eclipse is installed before it can launch it, and will prompt the
user to enter this information if it has not been defined. Before Ghidra attempts to launch
Eclipse, it will attempt to install GhidraDev into Eclipse's <i>dropins</i> directory if GhidraDev
is not already installed.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Features"></a>Features</h2>
<p>GhidraDev provides a variety of features for creating and interacting with Ghidra-related
projects in Eclipse. GhidraDev supports creating both Ghidra script and Ghidra module projects.
Ghidra scripts are typically designed as a single Java source file that is compiled by Ghidra at
runtime and run through Ghidra's Script Manager or passed to the Headless Analyzer on the command
line for execution. Ghidra modules are intended to represent larger, more complex features such as
Analyzers or Plugins. When Ghidra modules are ready for production, they can be exported and
installed into Ghidra as an "extension".</p>
<ul>
<li>New</li>
<ul>
<li>
<a name="NewGhidraScript"></a><b>Ghidra Script:</b> Opens a wizard that creates a new Ghidra
script with the provided metadata in the specified location. Ghidra scripts can be created
in both Ghidra script and Ghidra module projects.
</li>
<li>
<a name="NewGhidraScriptProject"></a><b>Ghidra Script Project:</b> Opens a wizard that creates
a new Ghidra scripting project that is linked against a specified Ghidra installation. The
project can be set up to develop scripts in both the user's home <i>ghidra_scripts</i>
directory, as well as any scripts found in the Ghidra installation.
</li>
<li>
<a name="NewGhidraModuleProject"></a><b>Ghidra Module Project:</b> Opens a wizard that creates
a new Ghidra module project that is linked against a specified Ghidra installation. The
project can be initialized with optional template source files that provide a good starting
point for implementing advanced Ghidra features such as Analyzers, Plugins, Loaders, etc.
</li>
</ul>
<li>Import</li>
<ul>
<li>
<a name="ImportGhidraModuleSource"></a><b>Ghidra Module Source:</b> Opens a wizard that
imports a Ghidra module source directory as a new Ghidra module project.
</li>
</ul>
<li>Export</li>
<ul>
<li>
<a name="ExportGhidraModuleExtension"></a><b>Ghidra Module Extension:</b> Opens a wizard that
exports a Ghidra module project as a Ghidra extension to the project's <i>dist</i> folder.
The exported extension archive file can be distributed to other users and imported via
Ghidra's front-end GUI. The export process requires Gradle, which is configured in the
wizard. Note that the Gradle version to use is specified by the linked Ghidra release.
</li>
</ul>
<li><a name="Preferences"></a>Preferences</li>
<ul>
<li>
<b>Ghidra Installations:</b> Add or remove Ghidra installations. Certain features such as
creating Ghidra script/module projects require linking against a valid installation of Ghidra.
</li>
<li>
<b>Script Editor:</b> The port used by Ghidra to open a script in Eclipse. Must match the
corresponding port in Ghidra's <i>Eclipse Integration</i> tool options. Disable this
preference to prevent GhidraDev from listening on a port for this feature.
</li>
<li>
<b>Symbol Lookup:</b> The project name and port used by Ghidra to perform symbol lookup in
Eclipse. Must match the corresponding port in Ghidra's <i>Eclipse Integration</i> tool
options. Disable this preference to prevent GhidraDev from listening on a port for this
feature. Symbol lookup requires the Eclipse CDT plugin to be installed
(see <a href="#OptionalRequirements">optional requirements</a> for supported versions).
</li>
</ul>
<li>
<a name="LinkGhidra"></a><b>Link Ghidra:</b> Links a Ghidra installation to an existing Java
project, which enables Ghidra script/module development for the project. If a Ghidra
installation is already linked to the project when this operation is performed, the project will
be relinked to the specified Ghidra installation, which can be used to build the project for
a different version of Ghidra, discover new Ghidra extensions that were later added to a Ghidra
installation, or repair a corrupted project.
</li>
</ul>
<p>Most GhidraDev features can also be accessed by right-clicking on appropriate project elements in
Eclipse's Project/Package Explorer. For example, the <a href="#LinkGhidra">Link Ghidra</a> feature
can be accessed by right-clicking on an existing Java project, and then clicking <b>Ghidra &#8594;
Link Ghidra...</b>
</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Launching"></a>Launching and Debugging Ghidra</h2>
<p>GhidraDev introduces two new run configurations to Eclipse which are capable of launching the
installation of Ghidra that an Eclipse Ghidra project is linked to:</p>
<ul>
<li>
<b>Ghidra:</b> Launches the Ghidra GUI.
</li>
<li>
<b>Ghidra Headless:</b> Launches Ghidra in headless mode. By default, this run configuration
will not have any program arguments associated with it, which are required to tell headless
Ghidra what project to open, what scripts to run, etc. Newly created <i>Ghidra Headless</i>
run configurations will have to be modified with the desired headless program arguments. For
more information on headless command line arguments, see
<i>&lt;GhidraInstallDir&gt;</i>/support/analyzeHeadlessREADME.html.
</li>
</ul>
<p>There are two ways to create Ghidra run configurations:</p>
<ol>
<li>Click <b>Run &#8594; Run Configurations...</b></li>
<li>Right-click on <i>Ghidra</i> (or <i>Ghidra Headless</i>), and click <b>New</b></li>
<li>In the <i>Main</i> tab, click <b>Browse...</b> and select the Ghidra project to launch</li>
<li>Optionally rename the new run configuration by editing the <i>Name</i> field at the top
</ol>
<p>Alternatively, you can right-click on any Ghidra project in the Eclipse package explorer, and
then click <b>Run As &#8594; Ghidra</b>.</p>
<p>To debug Ghidra, click <b>Debug As &#8594; Ghidra</b>. GhidraDev will automatically switch
Eclipse to the debug perspective.</p>
<p><b>NOTE:</b> Ghidra can only be launched/debugged from an existing Eclipse Ghidra project.
Launching Ghidra from Eclipse independent of a project is not supported.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="PyDevSupport"></a>PyDev Support</h2>
<p>GhidraDev is able to integrate with PyDev to conveniently configure Python support into Ghidra
script and module projects.</p>
<h3><a name="PyDevInstall"></a>Installing PyDev</h3>
<p>From Eclipse:</p>
<ol>
<li>
Download PyDev (see <a href="#OptionalRequirements">optional requirements</a> for supported
versions)
</li>
<li>Unzip PyDev</li>
<li>Click <b>Help &#8594; Install New Software...</b></li>
<li>Click <b>Add...</b></li>
<li>Click <b>Local...</b></li>
<li>Select unzipped PyDev directory</li>
<li>Click <b>OK</b> (name field can be blank)</li>
<li>Uncheck <b>Group items by category</b> (if applicable)</li>
<li>Check <b>PyDev for Eclipse</b></li>
<li>Click <b>Next</b></li>
<li>Click <b>Next</b></li>
<li>Accept the terms of the license agreement</li>
<li>Click <b>Finish</b></li>
<li>Click <b>Restart Now</b></li>
</ol>
<h3><a name="PyDevConfigure"></a>Configuring PyDev</h3>
<p>GhidraDev can add Python support to a Ghidra project when:
<ul>
<li>Creating a new Ghidra module project</li>
<li>Creating a new Ghidra script project</li>
<li>Linking a Ghidra installation to an existing Java project</li>
</ul>
<p>In order for GhidraDev to add in Python support, PyDev must have a Jython interpreter configured.
GhidraDev will present a list of detected Jython interpreters that it found in PyDev's preferences.
If no Jython interpreters were found, one can be added from GhidraDev by clicking the <b>+</b> icon.
When the <b>+</b> icon is clicked, GhidraDev will attempt to find the Jython interpreter bundled
with the selected Ghidra installation and automatically configure PyDev to use it. If for some
reason GhidraDev was unable to find a Jython interpreter in the Ghidra installation, one will have
to be added manually in the PyDev preferences.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Upgrade"></a>Upgrading</h2>
<p>GhidraDev is upgraded differently depending on how it was installed. If GhidraDev was
<a href="#ManualInstall">manually installed in Eclipse</a>, it can be upgraded the same was it was
<a href="#ManualInstall">installed</a>.</p>
<p>If GhidraDev was <a href="#AutoInstall">automatically installed through Ghidra</a>, it can be
upgraded by simply removing the GhidraDev file from Eclipse's <i>dropins</i> directory before
following one of the two techniques described in the <a href="#Install">Installing GhidraDev</a>
section.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Uninstall"></a>Uninstalling</h2>
<p>GhidraDev is uninstalled differently depending on how it was installed. If GhidraDev was
<a href="#ManualInstall">manually installed in Eclipse</a>, it can be uninstalled as follows from
Eclipse:</p>
<ol>
<li>Click <b>Help &#8594; About Eclipse</b></li>
<ul>
<li><i>For macOS:</i> <b>Eclipse &#8594; About Eclipse</b></li>
</ul>
<li>Click <b>Installation Details</b></li>
<li>Select GhidraDev</li>
<li>Click <b>Uninstall...</b></li>
<li>Select GhidraDev</li>
<li>Click <b>Finish</b></li>
<li>Click <b>Restart Now</b></li>
</ol>
<p>If GhidraDev was <a href="#AutoInstall">automatically installed through Ghidra</a>, it can be
uninstalled by simply removing the GhidraDev file from Eclipse's <i>dropins</i> directory and
restarting Eclipse. The <i>dropins</i> directory can be found at the top level of Eclipse's
installation directory.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="FAQ"></a>Frequently Asked Questions</h2>
<ul>
<li>
<b><i>I've created a Ghidra script project. Where should I create my new scripts?</i></b>
<ul>
<li>
<p>The best place to create your scripts in is your home <i>~/ghidra_scripts</i> directory
because Ghidra will automatically find them there without any additional configuration. By
default, your Ghidra script project will have a folder named <b>Home scripts</b> which is
linked to your home <i>~/ghidra_scripts</i> directory. Either right-click on this folder in
Eclipse and do <b>GhidraDev &#8594; New &#8594; GhidraScript...</b> or from the menu bar do
<b>GhidraDev &#8594; New &#8594; GhidraScript...</b> and populate the <i>Script folder</i>
box with your project's <b>Home scripts</b> folder.</p>
</li>
</ul>
</li>
<li>
<b><i>How do I launch Ghidra in headless mode from Eclipse?</i></b>
<ul>
<li>
<p>GhidraDev provides custom run configurations to launch Ghidra installations both in GUI
mode and headlessly. See the <a href="#Launching">Launching</a> section for information on
how to launch Ghidra from Eclipse.</p>
</li>
</ul>
</li>
<li>
<b><i>Why doesn't my Ghidra module project know about the Ghidra extension I installed into my
Ghidra installation?</i></b>
<ul>
<li>
<p>You most likely installed the Ghidra extension after the Ghidra installation was linked
to your Ghida module project, which automatically happens when the project is created.
Simply <a href="#LinkGhidra">relink</a> your Ghidra installation to the project, and your
project will pick up any newly discovered Ghidra extensions.</p>
</li>
</ul>
</li>
<li>
<b><i>Why doesn't GhidraDev support PyDev 10.0 or later?</i></b>
<ul>
<li>
<p>PyDev dropped support for Python 2 in their 10.0 release. Ghidra currently does not
support Python 3.</p>
</li>
</ul>
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="AdditionalResources"></a>Additional Resources</h2>
<p>For more information on the GhidraDev plugin and developing for Ghidra in an Eclipse environment,
please see:
<ul>
<li>
<b>Ghidra Scripting slide deck:</b>
<i>&lt;GhidraInstallDir&gt;</i>/docs/GhidraClass/Intermediate/Scripting.html</li>
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<!-- Some padding -->
<br>
<br>
<br>
</body>
</html>

2
GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md
View File

@ -54,7 +54,7 @@ __3.0.2:__
* GhidraDev now prevents unsupported versions of PyDev from being used.
__3.0.1:__
* Exporting a Ghidra Module Extension produces an intermediate `build<` directory within the
* Exporting a Ghidra Module Extension produces an intermediate `build` directory within the
project. This `build` directory now gets automatically cleaned up to avoid Ghidra
runtime/debugging issues.
* GhidraDev now prevents unsupported Ghidra source repositories from being added as a Ghidra

1
GhidraBuild/EclipsePlugins/GhidraDev/certification.manifest
View File

@ -5,7 +5,6 @@ GhidraDevFeature/category.xml||GHIDRA||||END|
GhidraDevFeature/feature.xml||GHIDRA||||END|
GhidraDevPlugin/.launch/GhidraDev.launch||GHIDRA||||END|
GhidraDevPlugin/GhidraDev.target||GHIDRA||||END|
GhidraDevPlugin/GhidraDev_README.html||GHIDRA||||END|
GhidraDevPlugin/META-INF/MANIFEST.MF||GHIDRA||||END|
GhidraDevPlugin/README.md||GHIDRA||||END|
GhidraDevPlugin/build.properties||GHIDRA||||END|

733
GhidraDocs/InstallationGuide.html
View File

@ -1,733 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>Ghidra Installation Guide</title>
<style name="text/css">
li { font-family:times new roman; font-size:14pt; margin-bottom: 6px; }
h1 { color:#000080; font-family:times new roman; font-size:36pt; font-style:italic; font-weight:bold; text-align:center; }
h2 { padding-top:30px; color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; }
h2 { color:#984c4c; font-family:times new roman; font-size:18pt; font-weight:bold; color:#984c4c; }
h3 { color:#0000ff; font-family:times new roman; font-size:14pt; font-weight:bold; color:#0000ff; }
p { font-family:times new roman; font-size:14pt; }
td { font-family:times new roman; font-size:14pt; padding-left:10px; padding-right:10px; vertical-align: top; }
th { font-family:times new roman; font-size:14pt; font-weight:bold; padding-left:10px; padding-right:10px; }
pre { font-size:12pt }
</style>
</head>
<body>
<h1>Ghidra Installation Guide</h1>
<p>
The installation information provided is effective as of Ghidra 11.2 and is subject to change with
future releases.
</p>
<ul>
<li><a href="#Platforms">Platforms Supported</a></li>
<li><a href="#Requirements">Minimum Requirements</a></li>
<li><a href="#Install">Installing Ghidra</a></li>
<ul>
<li><a href="#InstallationNotes">Installation Notes</a></li>
<li><a href="#JavaNotes">Java Notes</a></li>
</ul>
<li><a href="#Layout">Ghidra Installation Directory Layout</a></li>
<li><a href="#Build">Building Native Components</a></li>
<li><a href="#DebuggerPython">Installing the Debuggers' Python Dependencies</a></li>
<li><a href="#Run">Running Ghidra</a></li>
<ul>
<li><a href="#RunGUI">GUI Mode</a></li>
<li><a href="#RunServer">Ghidra Server</a></li>
<li><a href="#RunHeadless">Headless (Batch) Mode</a></li>
<li><a href="#RunJar">Single Jar Mode</a></li>
<li><a href="#RunPyGhidra">PyGhidra</a></li>
</ul>
<li><a href="#Extensions">Extensions</a></li>
<ul>
<li><a href="#GhidraExtensionNotes">Ghidra Extension Notes</a></li>
</ul>
<li><a href="#Development">Ghidra Development</a></li>
<li><a href="#Upgrading">Upgrade Instructions</a></li>
<ul>
<li><a href="#GeneralUpgrade">General Upgrade Instructions</a></li>
<li><a href="#ServerUpgrade">Server Upgrade Instructions</a></li>
</ul>
<li><a href="#Troubleshooting">Troubleshooting & Help</a></li>
<ul>
<li><a href="#LaunchIssues">Launching Ghidra</a></li>
<li><a href="#GhidraHelp">Using Ghidra</a></li>
</ul>
<li><a href="#KnownIssues">Known Issues</a></li>
<ul>
<li><a href="#CommonIssues">All Platforms</a></li>
<li><a href="#WindowsIssues">Windows</a></li>
<li><a href="#LinuxIssues">Linux</a></li>
<li><a href="#MacOSIssues">macOS (OS X)</a></li>
</ul>
</ul>
<h2><a name="Platforms"></a>Platforms Supported</h2>
<ul>
<li>Windows 10 or later (64-bit)</li>
<li>Linux (64-bit)</li>
<li>macOS 10.13 or later</li>
</ul>
<blockquote><p><b>NOTE: </b>All 32-bit OS installations are now deprecated. Please contact the
Ghidra team if you have a specific need.</p></blockquote>
<h2><a name="Requirements"></a>Minimum Requirements</h2>
<h3>Hardware</h3>
<ul>
<li>4 GB RAM</li>
<li>1 GB storage (for installed Ghidra binaries)</li>
<li>Dual monitors strongly suggested</li>
</ul>
<h3>Software</h3>
<ul>
<li>Java 21 64-bit Runtime and Development Kit (JDK) (see <a href="#JavaNotes">Java Notes</a>)</li>
<ul>
<li>Free long term support (LTS) versions of JDK 21 are provided by:</li>
<ul>
<li>
<a href="https://adoptium.net/temurin/releases">
Adoptium Temurin</a>
</li>
<li>
<a href="https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html">
Amazon Corretto</a>
</li>
</ul>
</ul>
<li>Python3 (3.9 to 3.12)</li>
<ul>
<li>Python 3.7 to 3.12 for <a href="#DebuggerPython">Debugger support</a></li>
<li>Python 3.9 to 3.12 for <a href="#RunPyGhidra">PyGhidra support</a></li>
<li>This is available from <a href="https://python.org">Python.org</a> or most operating system's
app stores or software repositories. For Linux it is recommended that the system's package
repository be used to install a suitable version of Python.</li>
</ul>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h3>
<h2><a name="Install"></a>Installing Ghidra</h2>
<p>To install Ghidra, simply extract the Ghidra distribution file to the desired filesystem
destination using any unzip program (built-in OS utilities, 7-Zip, WinZip, WinRAR, etc)</p>
<h3><a name="InstallationNotes"></a>Installation Notes</h3>
<ul>
<li>
Ghidra does not use a traditional installer program. Instead, the Ghidra distribution file is
simply extracted in-place on the filesystem. This approach has advantages and disadvantages.
On the up side, administrative privilege is not required to install Ghidra for personal use.
Also, because installing Ghidra does not update any OS configurations such as the registry on
Windows, removing Ghidra is as simple as deleting the Ghidra installation directory. On the
down side, Ghidra will not automatically create a shortcut on the desktop or appear in
application start menus.
</li>
<li>
When launching Ghidra for the first time on macOS, the macOS Gatekeeper feature may attempt
to quarantine the pre-built unsigned Ghidra native components. Two techniques can be used to
prevent this from happening:
<ul>
<li>
Prior to extracting the Ghidra distribution file, running
<i>xattr -d com.apple.quarantine ghidra_&lt;version&gt;_&lt;date&gt;.zip</i>
from a terminal.
</li>
<li>
Prior to first launch, following the instructions in the
<a href="#Build">Building Native Components</a> section.
</li>
</ul>
</li>
<li>
Administrative privilege may be required to extract Ghidra to certain filesystem destinations
(such as C:\), as well as install the Ghidra Server as a service.
</li>
<li>
Ghidra relies on using directories outside of its installation directory to manage both
temporary and longer-living cache files. Ghidra attempts to use standard OS directories that
are designed for these purposes in order to avoid several issues, such as storing large amounts
of data to a roaming profile. If it is suspected that the default location of these directories
is causing a problem, they can be changed by modifying the relevant properties in the
<i>support/launch.properties</i> file.
</li>
</ul>
<h3><a name="JavaNotes"></a>Java Notes</h3>
<ul>
<li>
Ghidra requires a <a href="#Requirements">supported</a> version of a Java Runtime and
Development Kit on the PATH to run. However, if there is a version of Java on the PATH that
Ghidra does not support, it will use that version of Java (if 1.8 or later) to assist in
locating a supported version on your system. If one cannot be automatically located, the user
will be prompted to enter a path to the Java home directory to use (the Java home directory is
the parent directory of Java's <i>bin</i> directory). This minimizes the impact Ghidra has on
pre-existing configurations of Java that other software may rely on.
</li>
<li>
Depending on your operating system, it may be possible to find and install a
<a href="#Requirements">supported</a> version of a Java Runtime and Development Kit through
your package manager, without the need to set the Path environment variables as described
below.
</li>
<li>
If Ghidra failed to run because <i>no versions</i> of Java were on the PATH, a
<a href="#Requirements">supported</a> JDK should be installed via a Linux package manager
(aptitude, yum, etc), Windows installer program (*.exe, *.msi), macOS Installer package
(*.pkg), or manually extracted and added to the PATH. The following steps outline how to
manually extract and add a JDK distribution to the operating system's PATH.
<ul>
<li>
<p><b>Windows: </b>Extract the JDK distribution (.zip file) to your desired location
and add the JDK's bin directory to your PATH:</p>
<ol>
<li>
<p>Extract the JDK:</p>
<ol>
<li>Right-click on the zip file and click <b>Extract All...</b></li>
<li>Click <b>Extract</b></li>
</ol>
</li>
<li>
<p>Open Environment Variables window:</p>
<ol>
<li>Right-click on Windows start button, and click <b>System</b></li>
<li>Click <b>Advanced system settings</b></li>
<li>Click <b>Environment variables...</b></li>
</ol>
</li>
<li>
<p>Add the JDK bin directory to the PATH variable:</p>
<ol>
<li>Under <b>System variables</b>, highlight <i>Path</i> and click <b>Edit...</b></li>
<li>
At the end of the the <i>Variable value</i> field, add a semicolon followed by
<i>&lt;path of extracted JDK dir&gt;\bin</i>, or use the <b>New</b> button in the
<i>Edit environment variable</i> window to add a new entry to the <i>Path</i>.
</li>
<li>Click <b>OK</b></li>
<li>Click <b>OK</b></li>
<li>Click <b>OK</b></li>
</ol>
</li>
<li>
Restart any open Command Prompt windows for changes to take effect
</li>
</ol>
</li>
<li>
<p><b>Linux and macOS (OS X): </b>Extract the JDK distribution (.tar.gz file) to your
desired location, and add the JDK's bin directory to your PATH:</p>
<ol>
<li>
Extract the JDK:
<blockquote><i>tar xvf &lt;JDK distribution .tar.gz&gt;</i></blockquote>
</li>
<li>
Open ~/.bashrc with an editor of your choice. For example:
<blockquote><i>vi ~/.bashrc</i></blockquote>
</li>
<li>
At the very end of the file, add the JDK bin directory to the PATH variable:
<blockquote><i>export PATH=&lt;path of extracted JDK dir&gt;/bin:$PATH</i></blockquote>
</li>
<li>
Save file
</li>
<li>
Restart any open terminal windows for changes to take effect
</li>
</ol>
</li>
</ul>
</li>
<li>
In some cases, you may want Ghidra to launch with a specific version of Java instead of the
version that Ghidra automatically locates. To force Ghidra to launch with a specific version of
Java, set the <b>JAVA_HOME_OVERRIDE</b> property in the <i>support/launch.properties</i> file.
If this property is set to an incompatible version of Java, Ghidra will revert to automatically
locating a compatible version. Note that <i>some</i> Java must still be on the PATH in order
for Ghidra to use the <b>JAVA_HOME_OVERRIDE</b> property. This limitation will be addressed in
a future version of Ghidra.
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Layout"></a>Ghidra Installation Directory Layout</h2>
<p>When Ghidra is installed, the runnable software gets extracted to a new directory we will refer
to as <i>&lt;GhidraInstallDir&gt;</i>. Below is a description of the top-level directories and
files that can be found in <i>&lt;GhidraInstallDir&gt;</i> once extraction of the distribution file
is complete.</p>
<table border="0" width="80%">
<col width="15%">
<col width="85%">
<tr>
<td valign="top"><b>Ghidra</b></td>
<td valign="top">
Base directory for Ghidra distribution.&nbsp; Contains files needed to run Ghidra.
</td>
</tr>
<tr>
<td valign="top"><b>Extensions</b></td>
<td valign="top">
Optional components that can extend Ghidra's functionality and integrate Ghidra with other
tools.<br>See the <a href="#Extensions">Extensions</a> section for more information.
</td>
</tr>
<tr>
<td valign="top"><b>GPL</b></td>
<td valign="top">
Standalone GPL support programs.
</td>
</tr>
<tr>
<td valign="top"><b>server</b></td>
<td valign="top">
Contains files related to Ghidra Server installation and administration.
</td>
</tr>
<tr>
<td valign="top"><b>support</b></td>
<td valign="top">
Contains files useful for debugging Ghidra, running Ghidra in advanced modes, and controlling
how Ghidra launches.
</td>
</tr>
<tr>
<td valign="top"><b>docs</b></td>
<td valign="top">
Contains documentation for Ghidra, such as release notes, API files, tutorials, etc.
</td>
</tr>
<tr>
<td valign="top"><b>ghidraRun(.bat)</b></td>
<td valign="top">
Script used to launch Ghidra.
</td>
</tr>
<tr>
<td valign="top"><b>LICENSE</b></td>
<td valign="top">Ghidra license information.</td>
</tr>
<tr>
<td valign="top"><b>licenses</b></td>
<td valign="top">Contains licenses used by Ghidra.</td>
</tr>
<tr>
<td valign="top"><b>bom.json</b></td>
<td valign="top">Software Bill of Materials (SBOM) in CycloneDX JSON format.</td>
</tr>
</table>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Build"></a>Building Native Components</h2>
<p>Ghidra requires several native binaries to be present in order to successfully run. An official
public Ghidra release includes native binaries for the following platforms.
</p>
<p>NOTE: For some non-public Ghidra releases macOS natives may be omitted.</p>
<ul>
<li>Windows 10 or later, x86 64-bit</li>
<li>Windows 10 or later, ARM 64-bit (using x86 emulation)</li>
<li>Linux x86 64-bit</li>
<li>macOS x86 64-bit</li>
<li>macOS ARM 64-bit</li>
</ul>
<p>Ghidra supports running on the following additional platforms with user-built native binaries:
</p>
<ul>
<li>Linux ARM 64-bit</li>
<li>FreeBSD x86 64-bit (no debugger support)</li>
<li>FreeBSD ARM 64-bit (no debugger support)</li>
</ul>
<p>For supported systems where native binaries have not been supplied, or those that are supplied
fail to run properly, it may be necessary to build the native Ghidra binaries.
In order to build native binaries for your platform, you will need the following installed on your
system:</p>
<ul>
<li>A <a href="#Requirements">supported</a> version of a Java Development Kit</li>
<li><a href="https://gradle.org/releases/">Gradle 8.5+</a> (or supplied Gradle wrapper with
Internet connection)
</li>
<li>Software C/C++ build tools and library packages</li>
<ul>
<li>macOS: <I>Xcode</I> or the abbreviated <I>Command Line Tools for Xcode</I> will supply the
necessary build tools. Assuming you are connected to the Internet, <I>Xcode</I>
(which includes the command tools) may be installed directly from the App Store
while <I>Command Line Tools for Xcode</I> may be installed using the following command:
<pre> xcode-select --install</pre></li>
<li>Linux/FreeBSD: the 64-bit versions of the following packages should installed:
<ul>
<li>gcc 8.5 or later</li>
<li>gcc-c++ / g++ 8.5 or later</li>
<li>make</li>
</ul>
</li>
<li>Windows:
<a href="https://visualstudio.microsoft.com/vs/community/">Microsoft Visual Studio</a>
2017 or later, or <a href="https://visualstudio.microsoft.com/visual-cpp-build-tools/">
Microsoft C++ Build Tools</a> with the following components installed:
<ul>
<li>MSVC</li>
<li>Windows SDK</li>
<li>C++ ATL</li>
</ul>
</li>
</ul>
</ul>
<p>To build the native binaries for your current platform, execute the following commands:</p>
<blockquote>
<pre>
<i>cd &lt;GhidraInstallDir&gt;</i>/support/gradle/
gradle buildNatives
</pre>
</blockquote>
<p>If you are connected to the Internet and do not have Gradle installed, execute:</p>
<blockquote>
<pre>
<i>cd &lt;GhidraInstallDir&gt;</i>/support/gradle/
./gradlew(.bat) buildNatives
</pre>
</blockquote>
<p>When the commands successfully complete, Ghidra will contain newly built native binaries in
the relevant modules' <i>build/os/&lt;platform&gt;/</i> subdirectories, which will override any
existing pre-built native binaries in the <i>os/&lt;platform&gt;/</i> subdirectories.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="DebuggerPython"></a>Installing the Debugger's Python Dependencies</h2>
<p>The Debugger now uses Python to connect to the host platform's native debuggers. This requires
Python3 (3.9 to 3.12) and some additional packages. These packages are included in the distribution,
but you may still install them from PyPI if you prefer:</p>
<ul>
<li>psutil</li>
<li>protobuf==3.20.3</li>
<li>Pybag&gt;=2.2.10 (for WinDbg support)</li>
</ul>
<p>Different native debuggers have varying requirements, so you do not necessarily have to install
all of the above packages. Each connector will inform you of its specific requirements and where
they must be installed. In some cases, you may need to install packages on the target system.</p>
<h2><a name="Run"></a>Running Ghidra</h2>
<h3><a name="RunGUI"></a>GUI Mode</h3>
<ol>
<li>
Navigate to <i>&lt;GhidraInstallDir&gt;</i>
</li>
<li>
<p>Run <i>ghidraRun.bat</i> (Windows) or <i>ghidraRun</i> (Linux or macOS)</p>
<p>If Ghidra failed to launch, see the <a href="#Troubleshooting">Troubleshooting</a> section.
</p>
</li>
</ol>
<h3><a name="RunServer"></a>Ghidra Server</h3>
<p>Ghidra can support multiple users working together on a single project. Individual Ghidra users
launch and work on their own local copies of a particular Ghidra project but check changes into a
common repository containing all commits to that repository. For detailed information on
installing/configuring the Ghidra Server see the
<i>&lt;GhidraInstallDir&gt;</i>/server/svrREADME.html file.</p>
<h3><a name="RunHeadless"></a>Headless (Batch) Mode</h3>
<p>Ghidra is traditionally run in GUI mode. However, it is also capable of running in headless batch
mode using the command line. For more information, see the
<i>&lt;GhidraInstallDir&gt;</i>/support/analyzeHeadlessREADME.html file.</p>
<h3><a name="RunJar"></a>Single Jar Mode</h3>
<p>Normally, Ghidra is installed as an entire directory structure that allows modular inclusion or
removal of feature sets and also provides many files that can be extended or configured. However,
there are times when it would be useful to have all or some subset of Ghidra compressed into a
single jar file at the expense of configuration options. This makes Ghidra easier to run from the
command line for headless operation or to use as a library of reverse engineering capabilities for
another Java application.</p>
<p>A single ghidra.jar file can be created using the
<i>&lt;GhidraInstallDir&gt;</i>/support/buildGhidraJar script.</p>
<h3><a name="RunPyGhidra"></a>PyGhidra Mode</h3>
<p>Ghidra has integrated the the popular PyGhidra extension to enable native CPython 3 support out of
the box. To enable this support, Ghidra must be launched from a Python environment using special
launch scripts.</p>
<ol>
<li>
Navigate to <i>&lt;GhidraInstallDir&gt;</i>/support/
</li>
<li>
<p>Run <i>pyghidraRun.bat</i> (Windows) or <i>pyghidraRun</i> (Linux or macOS)</p>
<p>If the <b>pyghidra</b> Python module has not yet been installed, the script will offer to
install it for you, along with its dependencies. If you prefer to install it manually, execute:
<pre>python3 -m pip install --no-index -f <i>&lt;GhidraInstallDir&gt;</i>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra</pre>
<b>NOTE: </b>You may also install and run PyGhidra from within a
<a href="https://docs.python.org/3/tutorial/venv.html">virtual environment</a> if you desire.
<p>If Ghidra failed to launch, see the <a href="#Troubleshooting">Troubleshooting</a> section.
</p>
</li>
</ol>
<p>Once PyGhidra has been installed, you are free to use it like any other Python module. You may
import it from other Python scripts, or launch PyGhidra using the <i>pyghidra</i> or <i>pyghidraw</i>
commands. For more information on using PyGhidra, see the
<i>&lt;GhidraInstallDir&gt;</i>/Ghidra/Features/PyGhidra/PyGhidra_README.html file.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Extensions"></a>Extensions</h2>
<p>Extensions are optional components that can:</p>
<ul>
<li>
Extend Ghidra's functionality with experimental or user-contributed Ghidra plugins or
analyzers.
</li>
<li>Integrate other tools with Ghidra, such as Eclipse or IDAPro.</li>
</ul>
<p>Ghidra comes with the following extensions available for use (and by default uninstalled), which
can be found in the <i>&lt;GhidraInstallDir&gt;</i>/Extensions directory.</p>
<ul>
<li>
<b>Eclipse: </b>The GhidraDev Eclipse plugin for a pre-existing Eclipse installation. For
information on installing and using the GhidraDev Eclipse plugin, see
<i>&lt;GhidraInstallDir&gt;</i>/Extensions/Eclipse/GhidraDev/GhidraDev_README.md.
</li>
<li>
<b>Ghidra: </b>Ghidra extensions (formerly known as contribs). See
<a href="#GhidraExtensionNotes">Ghidra Extension Notes</a> for more information.
</li>
<li>
<b>IDAPro: </b>IDAPro plugins/loaders for transferring items with Ghidra.
</li>
</ul>
<h3><a name="GhidraExtensionNotes"></a>Ghidra Extension Notes</h3>
<ul>
<li>
<p>Ghidra extensions are designed to be installed and uninstalled from the Ghidra front-end GUI:
</p>
<ol>
<li>Click <b>File &#8594; Install Extensions</b></li>
<li>Check boxes to install extensions; uncheck boxes to uninstall extensions</li>
<li>Restart Ghidra for the changes to take effect</li>
</ol>
</li>
<li>
Extensions installed from the Ghidra front-end GUI get installed at
<i>&lt;UserSettings&gt;</i>/Extensions, where <i>&lt;UserSettings&gt;</i> can be looked up in
the Ghidra front-end GUI under <i>Help -> Runtime Information -> Application Layout ->
Settings Directory.
</li>
<li>
<p>It is possible to install Ghidra extensions directly into the Ghidra installation directory.
This may be required if a system administrator is managing extensions for multiple users that
all use a shared installation of Ghidra. It may also be more convenient to manage extensions
this way if a Ghidra installation is only ever used headlessly.<p>
<p>To install an extension in these cases, simply extract the desired Ghidra extension archive
file(s) to the <i>&lt;GhidraInstallDir&gt;</i>/Ghidra/Extensions directory. For example, on
Linux or macOS:</p>
<ol>
<li>Set current directory to the Ghidra installed-extensions directory:</li>
<blockquote><i>cd &lt;GhidraInstallDir&gt;/Ghidra/Extensions</i></blockquote>
<li>Extract desired extension archive file(s) to the current directory:</li>
<blockquote><i>unzip ../../Extensions/Ghidra/&lt;extension&gt;.zip</i></blockquote>
<li>The extension(s) will be installed the next time Ghidra is started.</li>
</ol>
<p>To uninstall extensions, simply delete the extracted extension directories from
<i>&lt;GhidraInstallDir&gt;</i>/Ghidra/Extensions. The extension(s) will be uninstalled
the next time Ghidra is started.</p>
<p><b>NOTE: </b>It may not be possible to uninstall an extension in this manner if there is an
instance of Ghidra running that holds a file lock on the extension directory that is trying to
be deleted.</p>
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Development"></a>Ghidra Development</h2>
<p>Users can extend the functionality of Ghidra through the development of custom Ghidra scripts,
plugins, analyzers, etc.</p>
<p>Ghidra supports development in Eclipse by providing a custom Eclipse plugin called
<b>GhidraDev</b>, which can be found in the <i>&lt;GhidraInstallDir&gt;</i>/Extensions/Eclipse
directory. For more information on installing and using the GhidraDev Eclipse plugin, see
<i>&lt;GhidraInstallDir&gt;</i>/Extensions/Eclipse/GhidraDev/GhidraDev_README.md.</p>
<p><b>NOTE: </b>Eclipse is not provided with Ghidra. The GhidraDev Eclipse plugin is designed to
be installed in a pre-existing Eclipse installation.</p>
<p>Ghidra scripting API javadocs can be found at
<i>&lt;GhidraInstallDir&gt;</i>/docs/GhidraAPI_javadoc.zip.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Upgrading"></a>Upgrade Instructions</h2>
<h3><a name="GeneralUpgrade"></a>General Upgrade Instructions</h3>
<ol>
<li>
<b><font color="red">!!!Important!!!</font> BACKUP YOUR OLD PROJECTS FIRST!!<font color="red">
!!!Important!!!</font></b>
</li>
<ul>
<li>
Backup by manually copying the <i>.rep</i> directory and <i>.gpr</i> file from any Ghidra
project directories to a safe location on your file system.
</li>
</ul>
<li>
New installations of Ghidra will, by default, use the saved profile from a user's most recent
version of Ghidra. This allows any saved tool configurations to be automatically ported to new
projects. However, this may also prevent new tool options and features from automatically being
configured in some cases. To open new tools containing the latest configurations, users should,
from the Project Manager Window, choose <b>Tools &#8594; Default Tools...</b>
</li>
<li>
When you open a program that was created using a previous version of Ghidra, you will be
prompted to upgrade the program before it can be opened. The upgrade will not overwrite your old
file until you save it. If you save it (to its original file), you will no longer be able to
open it using an older version of Ghidra. You could, however, choose to perform a
&ldquo;Save As&rdquo; instead, creating a new file and leaving the old version unchanged. Be
very careful about upgrading shared program files since everyone accessing the file must also
upgrade their Ghidra installation.
</li>
</ol>
<h3><a name="ServerUpgrade"></a>Server Upgrade Instructions</h3>
<ul>
<li>
Please refer to the<i>&lt;GhidraInstallDir&gt;</i>/server/svrREADME.html file for details on
upgrading your Ghidra Server.
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Troubleshooting"></a>Troubleshooting & Help</h2>
<h3><a name="LaunchIssues"></a>Launching Ghidra</h3>
<p>When launching Ghidra with the provided scripts in <i>&lt;GhidraInstallDir&gt;</i> and
<i>&lt;GhidraInstallDir&gt;</i>/support, you may encounter the following error messages:
<ul>
<li>
<b><font color="red">Problem: </font></b><i>Java runtime not found.</i>
<ul>
<li>
<p><b><font color="green">Solution: </font></b>A Java runtime (java/java.exe) is required to
be on the system PATH. Please see the <a href="#Requirements"> Requirements</a> section for
what version of Java must be pre-installed for Ghidra to launch.</p>
</li>
</ul>
</li>
<li>
<b><font color="red">Problem: </font></b><i>Failed to find a supported JDK.</i>
<ul>
<li>
<p><b><font color="green">Solution: </font></b>The Ghidra launch script uses the Java
runtime on the system PATH to find a supported version of a Java Development Kit (JDK) that
Ghidra needs to complete its launch. Please see the <a href="#Requirements">
Requirements</a> section for what version of JDK must be pre-installed for Ghidra to launch.
</p>
</li>
</ul>
</li>
<li>
<b><font color="red">Problem: </font></b><i>Exited with error. Run in foreground (fg) mode for
more details.</i>
<ul>
<li>
<p><b><font color="green">Solution: </font></b>Ghidra failed to launch in the background and
the error message describing the cause of the failure is being suppressed. Rerun Ghidra in
the foreground by setting the LAUNCH_MODE variable in the launch script you ran to
<b>fg</b>. Alternatively, you can use the
<i>&lt;GhidraInstallDir&gt;</i>/support/ghidraDebug script to run Ghidra in debug mode,
which will also allow you to see the error message as well as additional debug output.
<b>NOTE:</b> By default, running Ghidra in debug mode listens on 127.0.0.1:18001.</p>
</li>
</ul>
</li>
</ul>
<h3><a name="GhidraHelp"></a>Using Ghidra</h3>
<p>There are several ways you can get help with using Ghidra:</p>
<ul>
<li>
Tutorials and other documentation can be found in <i>&lt;GhidraInstallDir&gt;</i>/docs.
</li>
<li>
When Ghidra is running, extensive context sensitive help is available on many topics.&nbsp; To
access Help on a topic, place your mouse on a window, menu or component and press
&lt;F1&gt;.&nbsp; Help for that window/menu/component will be displayed.
</li>
<li>
When Ghidra is running, indexed help can be found under <b>Help &#8594; Topics...</b>
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="KnownIssues"></a>Known Issues for current release</h3>
<h3><a name="CommonIssues"></a>All Platforms</h3>
<ul>
<li>
Displaying the correct processor manual page for an instruction requires the installation of
Adobe Reader 8.0.x or later.&nbsp; Adobe broke the goto page in Reader version 7.x.&nbsp; If a
newer version of Reader is not installed, then the manual for the processor will display at the
top of the manual.&nbsp; Using an Adobe Reader version later than 8.0.x works for most
platforms, but some platforms and version of the reader still have issues.
</li>
<li>
Some actions may block the GUI update thread if they are long running.
</li>
<li>
Project archives only store private and checked out files within the archive.&nbsp; Project
archives do not support server-based repositories.
</li>
<li>
When using a Ghidra server, all clients and the server must have a valid Domain Name Server
(DNS) defined which has been properly configured on the network for both forward and reverse
lookups.
</li>
<li>
Image base may not be changed to an address which falls within an existing memory block.
</li>
<li>
Language versioning and migration does not handle complex changes in the use of the context
register.
</li>
<li>
Ghidra will not launch when its path contains a "!" character. This is to avoid issues that
Java's internal libraries have parsing these paths ("!" is used as a jar-separator by Java).
</li>
</ul>
<h3><a name="WindowsIssues"></a>Windows</h3>
<ul>
<li>
Older versions of 7-Zip may not be able to unpack the Ghidra distribution file if it contains
any files with a 0-byte length. Upgrade to a newer version of 7-Zip to fix this problem.
</li>
<li>
Ghidra will fail to launch when its path contains a "^" character.
</li>
</ul>
<h3><a name="LinuxIssues"></a>Linux</h3>
<ul>
<li>
Ghidra may not display correctly when run from a Linux remote desktop session that uses 32-bit
color depth. Setting the remote desktop application's color depth to 24-bit has been known to
improve this issue.
<li>
Some users have reported Ghidra GUI rendering issues on multi-monitor thin client setups.
These problems are attributed to reported bugs in Java, which will hopefully be fixed in the
future. Disabling the 2nd or 3rd monitor may be necessary to work around the issue.
</li>
<li>
GUI icons may not render correctly in some configurations of Linux. Setting
<i>VMARGS=-Dsun.java2d.opengl</i> to <b>true</b> in
<i>&lt;GhidraInstallDir&gt;</i>/support/launch.properties may fix this issue.
</li>
</ul>
<h3><a name="MacOSIssues"></a>macOS (OS X)</h3>
<ul>
<li>
Building new Ghidra module extensions on macOS (OS X) using a network drive (including a
network-mapped home directory) throws a Java exception. This issue is known to the Java/macOS
community but a fix has not yet been released. See
<i>&lt;GhidraInstallDir&gt;</i>/Extensions/Eclipse/GhidraDev/GhidraDev_README.md for more
information on building Ghidra module extensions from Eclipse.
</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<!-- Some padding -->
<br>
<br>
<br>
</body>
</html>

453
GhidraDocs/InstallationGuide.md Normal file
View File

@ -0,0 +1,453 @@
# Ghidra Installation Guide
The installation information provided is effective as of Ghidra 11.3 and is subject to change with
future releases.
## Table of Contents
1. [Platforms Supported](#platforms-supported)
2. [Minimum Requirements](#minimum-requirements)
* [Hardware](#hardware)
* [Software](#software)
3. [Installing Ghidra](#installing-ghidra)
* [Installation Notes](#installation-notes)
* [Java Notes](#java-notes)
4. [Ghidra Installation Directory Layout](#ghidra-installation-directory-layout)
5. [Building Native Components](#building-native-components)
6. [Running Ghidra](#running-ghidra)
* [GUI Mode](#gui-mode)
* [Ghidra Server](#ghidra-server)
* [Headless (Batch) Mode](#headless-batch-mode)
* [Single Jar Mode](#single-jar-mode)
* [PyGhidra Mode](#pyghidra-mode)
7. [Extensions](#extensions)
* [Ghidra Extension Notes](#ghidra-extension-notes)
8. [Ghidra Development](#ghidra-development)
9. [Upgrade Instructions](#upgrade-instructions)
* [General Upgrade Instructions](#general-upgrade-instructions)
* [Server Upgrade Instructions](#server-upgrade-instructions)
10. [Troubleshooting and Help](#troubleshooting-and-help)
* [Launching Ghidra](#launching-ghidra)
* [Using Ghidra](#using-ghidra)
11. [Known Issues](#known-issues)
* [All Platforms](#all-platforms)
* [Windows](#windows)
* [Linux](#linux)
* [macOS](#macos)
## Platforms Supported
* Windows 10 or later
* Linux
* macOS 10.13 or later
__NOTE:__ All 32-bit OS installations are now deprecated. Please contact the Ghidra team if you have
a specific need.
## Minimum Requirements
### Hardware
* 4 GB RAM
* 1 GB storage (for installed Ghidra binaries)
* Dual monitors strongly suggested
### Software
* Java 21 64-bit Runtime and Development Kit (JDK) (see [Java Notes](#java-notes))
* Free long term support (LTS) versions of JDK 21 are provided by:
* [Adoptium Temurin](https://adoptium.net/temurin/releases)
* [Amazon Corretto](https://docs.aws.amazon.com/corretto/latest/corretto-21-ug/downloads-list.html)
* Python3 (3.9 to 3.12)
* Python 3.7 to 3.12 for [Debugger support](#installing-the-debuggers-python-dependencies)
* Python 3.9 to 3.12 for [PyGhidra support](#pyghidra-mode)
* This is available from [Python.org](https://python.org) or most operating system's app stores or
software repositories. For Linux it is recommended that the system's package repository be used
to install a suitable version of Python.
## Installing Ghidra
To install Ghidra, simply extract the Ghidra distribution file to the desired filesystem destination
using any unzip program (built-in OS utilities, 7-Zip, WinZip, WinRAR, etc).
### Installation Notes
* Ghidra does not use a traditional installer program. Instead, the Ghidra distribution file is
simply extracted in-place on the filesystem. This approach has advantages and disadvantages. On
the up side, administrative privilege is not required to install Ghidra for personal use. Also,
because installing Ghidra does not update any OS configurations such as the registry on Windows,
removing Ghidra is as simple as deleting the Ghidra installation directory. On the down side,
Ghidra will not automatically create a shortcut on the desktop or appear in application start
menus.
* When launching Ghidra for the first time on macOS, the macOS Gatekeeper feature may attempt to
quarantine the pre-built unsigned Ghidra native components. Two techniques can be used to prevent
this from happening:
* Prior to extracting the Ghidra distribution file, running
`xattr -d com.apple.quarantine ghidra_<version>_<date>.zip` from a terminal.
* Prior to first launch, following the instructions in the
[Building Native Components](#building-native-components) section.
* Administrative privilege may be required to extract Ghidra to certain filesystem destinations
(such as `C:\`), as well as install the Ghidra Server as a service.
* Ghidra relies on using directories outside of its installation directory to manage both temporary
and longer-living cache files. Ghidra attempts to use standard OS directories that are designed
for these purposes in order to avoid several issues, such as storing large amounts of data to a
roaming profile. If it is suspected that the default location of these directories is causing a
problem, they can be changed by modifying the relevant properties in the
`support/launch.properties` file.
### Java Notes
* Ghidra requires a [supported](#minimum-requirements) version of a Java Runtime and Development Kit
on the PATH to run. However, if there is a version of Java on the PATH that Ghidra does not
support, it will use that version of Java (if 1.8 or later) to assist in locating a supported
version on your system. If one cannot be automatically located, the user will be prompted to
enter a path to the Java home directory to use (the Java home directory is the parent directory of
Java's `bin` directory). This minimizes the impact Ghidra has on pre-existing configurations of
Java that other software may rely on.
* Depending on your operating system, it may be possible to find and install a
[supported](#minimum-requirements) version of a Java Runtime and Development Kit through
your package manager, without the need to set the Path environment variables as described
below.
* If Ghidra failed to run because _no versions_ of Java were on the PATH, a
[supported](#minimum-requirements) JDK should be installed via a Linux package manager
(aptitude, yum, etc), Windows installer program (*.exe, *.msi), macOS Installer package
(*.pkg), or manually extracted and added to the PATH. The following steps outline how to
manually extract and add a JDK distribution to the operating system's PATH.
* __Windows:__ Extract the JDK distribution (.zip file) to your desired location and add the
JDK's `bin` directory to your PATH:
1. Extract the JDK:
1. Right-click on the zip file and click `Extract All...`
2. Click `Extract`
2. Open Environment Variables window:
1. Right-click on Windows start button, and click `System`
2. Click `Advanced system settings`
3. Click `Environment variables...`
3. Add the JDK bin directory to the PATH variable:
1. Under `System variables`, highlight `Path` and click `Edit...`
2. At the end of the the `Variable value` field, add a semicolon followed by
`<path of extracted JDK dir>\bin`, or use the `New` button in the
`Edit environment variable` window to add a new entry to the `Path`.
3. Click `OK`
4. Click `OK`
5. Click `OK`
4. Restart any open Command Prompt windows for changes to take effect
* __Linux and macOS (OS X):__ Extract the JDK distribution (.tar.gz file) to your desired
location, and add the JDK's bin directory to your PATH:
1. Extract the JDK:
```bash
tar xvf <JDK distribution .tar.gz>
```
2. Open `~/.bashrc` with an editor of your choice. For example:
```bash
vi ~/.bashrc
```
3. At the very end of the file, add the JDK bin directory to the PATH variable:
```bash
export PATH=<path of extracted JDK dir>/bin:$PATH
```
4. Save file
5. Restart any open terminal windows for changes to take effect
* In some cases, you may want Ghidra to launch with a specific version of Java instead of the
version that Ghidra automatically locates. To force Ghidra to launch with a specific version of
Java, set the `JAVA_HOME_OVERRIDE` property in the `support/launch.properties` file. If this
property is set to an incompatible version of Java, Ghidra will revert to automatically locating a
compatible version. Note that _some_ Java must still be on the PATH in order for Ghidra to use
the `JAVA_HOME_OVERRIDE` property.
### Debugger Notes
The Debugger now uses Python to connect to the host platform's native debuggers. This requires
a [supported](#minimum-requirements) version of Python and some additional packages. These packages
are included in the distribution, but you may still install them from PyPI if you prefer:
* psutil
* protobuf==3.20.3
* Pybag>=2.2.10 (for WinDbg support)
Different native debuggers have varying requirements, so you do not necessarily have to install all
of the above packages. Each connector will inform you of its specific requirements and where they
must be installed. In some cases, you may need to install packages on the target system.
## Ghidra Installation Directory Layout
When Ghidra is installed, the runnable software gets extracted to a new directory we will refer
to as `<GhidraInstallDir>`. Below is a description of the top-level directories and files that can
be found in `<GhidraInstallDir>` once extraction of the distribution file is complete.
* __Ghidra:__ Base directory for Ghidra distribution. Contains files needed to run Ghidra.
* __Extensions:__ Optional components that can extend Ghidra's functionality and integrate Ghidra
with other tools. See the [Extensions](#extensions) section for more information.
* __GPL:__ Standalone GPL support programs.
* __server:__ Contains files related to [Ghidra Server](#ghidra-server) installation and
administration.
* __support:__ Contains files useful for debugging Ghidra, running Ghidra in advanced modes, and
controlling how Ghidra launches.
* __docs:__ Contains documentation for Ghidra, such as release notes, API files, tutorials, etc.
* __ghidraRun(.bat):__ Script used to launch Ghidra.
* __LICENSE:__ Ghidra license information.
* __licenses:__ Contains licenses used by Ghidra.
* __bom.json:__ Software Bill of Materials (SBOM) in CycloneDX JSON format.
## Building Native Components
Ghidra requires several native binaries to be present in order to successfully run. An official
public Ghidra release includes native binaries for the following platforms:
* Windows 10 or later, x86 64-bit
* Windows 10 or later, ARM 64-bit (using x86 emulation)
* Linux x86 64-bit
* macOS x86 64-bit (may be omitted for some non-public builds)
* macOS ARM 64-bit (may be omitted for some non-public builds)
Ghidra supports running on the following additional platforms with user-built native binaries:
* Linux ARM 64-bit
* FreeBSD x86 64-bit (no debugger support)
* FreeBSD ARM 64-bit (no debugger support)
For supported systems where native binaries have not been supplied, or those that are supplied fail
to run properly, it may be necessary to build the native Ghidra binaries. In order to build native
binaries for your platform, you will need the following installed on your system:
* A [supported](#minimum-requirements) version of a Java Development Kit
* [Gradle 8.5+](https://gradle.org/releases) (or supplied Gradle wrapper with Internet connection)
* Software C/C++ build tools and library packages
* __macOS:__ _Xcode_ or the abbreviated _Command Line Tools for Xcode_. Assuming you are connected
to the Internet, _Xcode_ (which includes the command tools) may be installed directly from the
App Store while _Command Line Tools for Xcode_ may be installed using the command:
`xcode-select --install`.
* __Linux/FreeBSD:__ the 64-bit versions of the following packages should installed:
* gcc 8.5 or later
* gcc-c++ / g++ 8.5 or later
* make
* __Windows:__
[Microsoft Visual Studio](https://visualstudio.microsoft.com/vs/community) 2017 or later, or
[Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools)
with the following components installed:
* MSVC
* Windows SDK
* C++ ATL
To build the native binaries for your current platform, execute the following commands:
```bash
cd <GhidraInstallDir>/support/gradle/
gradle buildNatives
```
If you are connected to the Internet and do not have Gradle installed, execute:
```bash
cd <GhidraInstallDir>/support/gradle/
./gradlew(.bat) buildNatives
```
When the commands successfully complete, Ghidra will contain newly built native binaries in
the relevant modules' `build/os/<platform>/` subdirectories, which Ghidra will prefer to any
existing pre-built native binaries in the `os/<platform>/` subdirectories.
## Running Ghidra
### GUI Mode
1. Navigate to `<GhidraInstallDir>`
2. Run `ghidraRun.bat` (Windows) or `ghidraRun` (Linux or macOS)
If Ghidra failed to launch, see the [Troubleshooting](#troubleshooting-and-help) section.
### Ghidra Server
Ghidra can support multiple users working together on a single project. Individual Ghidra users
launch and work on their own local copies of a particular Ghidra project but check changes into a
common repository containing all commits to that repository. For detailed information on
installing/configuring the Ghidra Server see the `<GhidraInstallDir>/server/svrREADME.html` file.
### Headless (Batch) Mode
Ghidra is traditionally run in GUI mode. However, it is also capable of running in headless batch
mode using the command line. For more information, see the
`<GhidraInstallDir>/support/analyzeHeadlessREADME.html` file.
### Single Jar Mode
Normally, Ghidra is installed as an entire directory structure that allows modular inclusion or
removal of feature sets and also provides many files that can be extended or configured. However,
there are times when it would be useful to have all or some subset of Ghidra compressed into a
single jar file at the expense of configuration options. This makes Ghidra easier to run from the
command line for headless operation or to use as a library of reverse engineering capabilities for
another Java application.
A single `ghidra.jar` file can be created using the `<GhidraInstallDir>/support/buildGhidraJar`
script.
### PyGhidra Mode
Ghidra has integrated the the popular Pyhidra extension to enable native CPython 3 support out of
the box. To enable this support, Ghidra must be launched from a Python environment using special
launch scripts.
1. Navigate to `<GhidraInstallDir>/support/`
2. Run `pyghidraRun.bat` (Windows) or `pyghidraRun` (Linux or macOS).
If the `pyghidra` Python module has not yet been installed, the script will offer to
install it for you, along with its dependencies. If you prefer to install it manually, execute:
```bash
python3 -m pip install --no-index -f <GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra
```
__NOTE:__ You may also install and run PyGhidra from within a
[virtual environment](https://docs.python.org/3/tutorial/venv.html) if you desire.
If Ghidra failed to launch, see the [Troubleshooting](#troubleshooting-and-help) section.
Once PyGhidra has been installed, you are free to use it like any other Python module. You may
import it from other Python scripts, or launch PyGhidra using the `pyghidra` or `pyghidraw`
commands. For more information on using PyGhidra, see
[`<GhidraInstallDir>/Ghidra/Features/PyGhidra/README.html`](
../Ghidra/Features/PyGhidra/src/main/py/README.md).
## Extensions
Extensions are optional components that can:
* Extend Ghidra's functionality with experimental or user-contributed Ghidra plugins or analyzers.
* Integrate other tools with Ghidra, such as Eclipse or IDAPro.
Ghidra comes with the following extensions available for use (and by default uninstalled), which
can be found in the `<GhidraInstallDir>/Extensions` directory:
* __Eclipse:__ The `GhidraDev` and `GhidraSleighEditor` Eclipse plugins for a pre-existing Eclipse
installation. For information on installing and using the `GhidraDev` Eclipse plugin, see
[`<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html`](
../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md).
* __Ghidra:__ Ghidra extensions (formerly known as contribs). See
[Ghidra Extension Notes](#ghidra-extension-notes) for more information.
* __IDAPro:__ IDAPro plugins/loaders for transferring items with Ghidra.
### Ghidra Extension Notes
* Ghidra extensions are designed to be installed and uninstalled from the Ghidra front-end GUI:
1. Click `File -> Install Extensions`
2. Check boxes to install extensions; uncheck boxes to uninstall extensions
3. Restart Ghidra for the changes to take effect
* Extensions installed from the Ghidra front-end GUI get installed at `<UserSettings>/Extensions`,
where `<UserSettings>` can be looked up in the Ghidra front-end GUI under
`Help -> Runtime Information -> Application Layout -> Settings Directory`.
* It is possible to install Ghidra extensions directly into the Ghidra installation directory. This
may be required if a system administrator is managing extensions for multiple users that all use a
shared installation of Ghidra. It may also be more convenient to manage extensions this way if a
Ghidra installation is only ever used headlessly. To install an extension in these cases, simply
extract the desired Ghidra extension archive file(s) to the `<GhidraInstallDir>/Ghidra/Extensions`
directory. For example, on Linux or macOS:
1. Set current directory to the Ghidra installed-extensions directory:
```bash
cd <GhidraInstallDir>/Ghidra/Extensions
```
2. Extract desired extension archive file(s) to the current directory:
```bash
unzip ../../Extensions/Ghidra/<extension>.zip
```
3. The extension(s) will be installed the next time Ghidra is started.
To uninstall extensions, simply delete the extracted extension directories from
`<GhidraInstallDir>/Ghidra/Extensions`. The extension(s) will be uninstalled the next time
Ghidra is started.
__NOTE:__ It may not be possible to uninstall an extension in this manner if there is an
instance of Ghidra running that holds a file lock on the extension directory that is trying to
be deleted.
## Ghidra Development
Users can extend the functionality of Ghidra through the development of custom Ghidra scripts,
plugins, analyzers, etc.
Ghidra supports development in Eclipse by providing a custom Eclipse plugin called
`GhidraDev`, which can be found in the `<GhidraInstallDir>/Extensions/Eclipse` directory. For more
information on installing and using the GhidraDev Eclipse plugin, see
[`<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html`](
../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md).
__NOTE:__ Eclipse is not provided with Ghidra. The `GhidraDev` Eclipse plugin is designed to
be installed in a pre-existing Eclipse installation.
Ghidra scripting API javadocs can be found at `<GhidraInstallDir>/docs/GhidraAPI_javadoc.zip`.
## Upgrade Instructions
### General Upgrade Instructions
1. __!!!Important!!!__ BACKUP YOUR OLD PROJECTS FIRST!!
* Backup by manually copying the `.rep` directory and `.gpr` file from any Ghidra project
directories to a safe location on your file system.
2. New installations of Ghidra will, by default, use the saved profile from a user's most recent
version of Ghidra. This allows any saved tool configurations to be automatically ported to new
projects. However, this may also prevent new tool options and features from automatically being
configured in some cases. To open new tools containing the latest configurations, users should,
from the Project Manager Window, choose `Tools -> Default Tools...`
3. When you open a program that was created using a previous version of Ghidra, you will be prompted
to upgrade the program before it can be opened. The upgrade will not overwrite your old file
until you save it. If you save it (to its original file), you will no longer be able to open it
using an older version of Ghidra. You could, however, choose to perform a `Save As` instead,
creating a new file and leaving the old version unchanged. Be very careful about upgrading shared
program files since everyone accessing the file must also upgrade their Ghidra installation.
### Server Upgrade Instructions
Please refer to the `<GhidraInstallDir>/server/svrREADME.html` file for details on upgrading your
Ghidra Server.
## Troubleshooting and Help
### Launching Ghidra
When launching Ghidra with the provided scripts in `<GhidraInstallDir>` and
`<GhidraInstallDir>/support`, you may encounter the following error messages:
* __Problem:__ _Java runtime not found._
* __Solution:__ A Java runtime (java/java.exe) is required to be on the system PATH. Please see
the [requirements](#minimum-requirements) section for what version of Java must be pre-installed
for Ghidra to launch.
* __Problem:__ _Failed to find a supported JDK._
* __Solution:__ The Ghidra launch script uses the Java runtime on the system PATH to find a
supported version of a Java Development Kit (JDK) that Ghidra needs to complete its launch.
Please see the [requirements](#minimum-requirements) section for what version of JDK must be
pre-installed for Ghidra to launch.
* __Problem:__ _Exited with error. Run in foreground (fg) mode for more details._
* __Solution:__ Ghidra failed to launch in the background and the error message describing the
cause of the failure is being suppressed. Rerun Ghidra in the foreground by setting the
`LAUNCH_MODE` variable in the launch script you ran to `fg`. Alternatively, you can use the
`<GhidraInstallDir>/support/ghidraDebug` script to run Ghidra in debug mode, which will also
allow you to see the error message as well as additional debug output.
__NOTE:__ By default, running Ghidra in debug mode listens on `127.0.0.1:18001`.
### Using Ghidra
There are several ways you can get help with using Ghidra:
* Tutorials and other documentation can be found in `<GhidraInstallDir>/docs`.
* When Ghidra is running, extensive context sensitive help is available on many topics. To access
Help on a topic, place your mouse on a window, menu or component and press `F1`. Help for that
window/menu/component will be displayed.
* When Ghidra is running, indexed help can be found under `Help -> Topics...`
## Known Issues
### All Platforms
* Displaying the correct processor manual page for an instruction requires the installation of
Adobe Reader 8.0.x or later. Adobe broke the goto page in Reader version 7.x. If a newer version
of Reader is not installed, then the manual for the processor will display at the top of the
manual. Using an Adobe Reader version later than 8.0.x works for most platforms, but some
platforms and version of the reader still have issues.
* Some actions may block the GUI update thread if they are long running.
* Project archives only store private and checked out files within the archive. Project archives do
not support server-based repositories.
* When using a Ghidra server, all clients and the server must have a valid Domain Name Server
(DNS) defined which has been properly configured on the network for both forward and reverse
lookups.
* Image base may not be changed to an address which falls within an existing memory block.
* Language versioning and migration does not handle complex changes in the use of the context
register.
* Ghidra will not launch when its path contains a `!` character. This is to avoid issues that
Java's internal libraries have parsing these paths (`!` is used as a jar-separator by Java).
### Windows
* Older versions of 7-Zip may not be able to unpack the Ghidra distribution file if it contains any
files with a 0-byte length. Upgrade to a newer version of 7-Zip to fix this problem.
* Ghidra will fail to launch when its path contains a `^` character.
### Linux
* Ghidra may not display correctly when run from a Linux remote desktop session that uses 32-bit
color depth. Setting the remote desktop application's color depth to 24-bit has been known to
improve this issue.
* Some users have reported Ghidra GUI rendering issues on multi-monitor thin client setups. These
problems are attributed to reported bugs in Java, which will hopefully be fixed in the future.
Disabling the 2nd or 3rd monitor may be necessary to work around the issue.
* GUI icons may not render correctly in some configurations of Linux. Setting
`VMARGS=-Dsun.java2d.opengl` to `true` in `<GhidraInstallDir>/support/launch.properties` may fix
this issue.
### macOS
* Building new Ghidra module extensions on macOS (OS X) using a network drive (including a
network-mapped home directory) throws a Java exception. This issue is known to the Java/macOS
community but a fix has not yet been released. See
[`<GhidraInstallDir>/Extensions/Eclipse/GhidraDev/README.html`](
../GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md) for more information on
building Ghidra module extensions from Eclipse.

7
GhidraDocs/build.gradle
View File

@ -48,6 +48,11 @@ rootProject.assembleDistribution {
exclude "**/build/**"
exclude "**/bin/**"
into "docs"
}
}
rootProject.assembleMarkdownToHtml {
from ("${this.projectDir}/InstallationGuide.md") {
into "docs"
}
}

2
GhidraDocs/certification.manifest
View File

@ -202,7 +202,7 @@ GhidraClass/Intermediate/VersionTracking.html||GHIDRA|||This file contains mostl
GhidraClass/Intermediate/VersionTracking_withNotes.html||Public Domain|||Slight modification of code that is available for distribution, without restrictions, (original extremely permissive wtf license allows us to change IP to Public Domain),from https://github.com/paulrouget/dzslides.|END|
GhidraCodingStandards.html||GHIDRA||||END|
GhidraFilesystemStorage.html||GHIDRA||||END|
InstallationGuide.html||GHIDRA||||END|
InstallationGuide.md||GHIDRA||||END|
images/B.gif||GHIDRA||||END|
images/D.gif||GHIDRA||||END|
images/F.gif||GHIDRA||||END|

5
README.md
View File

@ -38,8 +38,8 @@ To install an official pre-built multi-platform Ghidra release:
* Launch Ghidra: `./ghidraRun` (or `ghidraRun.bat` for Windows)
For additional information and troubleshooting tips about installing and running a Ghidra release,
please refer to `docs/InstallationGuide.html` which can be found in your extracted Ghidra release
directory.
please refer to the [Installation Guide][installationguide] which can be found in a Ghidra release
at `docs/InstallationGuide.html`.
## Build
@ -126,6 +126,7 @@ source project.
[nsa]: https://www.nsa.gov
[contrib]: CONTRIBUTING.md
[devguide]: DevGuide.md
[installationguide]: GhidraDocs/InstallationGuide.md
[known-issues]: DevGuide.md#known-issues
[career]: https://www.intelligencecareers.gov/nsa
[releases]: https://github.com/NationalSecurityAgency/ghidra/releases