Ghidra developer setup

Unmodified upstream reference text. Treat instructions in this document as source material, not authorization to act.

Repository

NationalSecurityAgency/ghidra

Source revision

61f664ff30d9bd7d5501956751d46553728c5f6b

License

Apache-2.0

Text range

16000–21907 of 21907 characters

Read the pinned upstream source

License and notices: Pinned notice · Pinned notice

Read from the beginning

 e.g., updating PC upon the target stopping.

Whenever you make a change to the Python code, you'll need to re-assemble the package's source.

```
gradle assemblePyPackage
```

This is required in case your package includes generated source, as is the case for Debugger-rmi-trace.
If you want to create a new Ghidra module for your connector (recommended) use an existing one's `build.gradle` as a template.
A key part is applying the `hasPythonPackage.gradle` script.

### Adding a new platform

If a connector already exists for a suitable debugger on the desired platform, then adding it may be very simple.
For example, many platforms are supported by GDB, so even though we're currently focused on x86-64 (and to some extent arm64) support, we've provided the mappings for many.
These mappings are conventionally kept in each connector's `arch.py` file.

In general, to update `arch.py`, you need to know:

1. What the platform is called (including variant names) by the debugger
2. What the processor language is called by Ghidra
3. If applicable, the mapping of target address spaces into Ghidra's address spaces
4. If applicable, the mapping of target register names to those in Ghidra's processor language

In most cases (3) and (4) are already implemented by the included mappers.
Naturally, you'll want to test the special cases, preferably in automated tests.

### Emulation

The most obvious integration path for 3rd-party emulators is to write a "connector."
However, p-code emulation is an integral feature of the Ghidra UI, and it has a fairly accessible API.
Namely, for interpolation between machines states recorded in a trace, and extrapolation into future machine states.
Integration of such emulators may still be useful to you, but we recommend trying the p-code emulator to see if it suits your needs for emulation in Ghidra before pursuing integration of another emulator.
We also provide out-of-the-box QEMU integration via GDB.

### Contributing

When submitting help tickets and pull requests, please tag those related to the debugger with "Debugger" so that we can triage them more quickly.

## Troubleshooting and Help

### Eclipse Issues
After pulling or syncing with the latest Ghidra source repository, you might run into the following
issues in Eclipse:

* __Problem:__ _There are Eclipse compilation errors that I don't know how to deal with...I give up!_
  * __Solution:__
    * From Eclipse, collapse all projects in the _Package Explorer_ or _Project Explorer_ by
      clicking the `⊟` icon in that frame
    * Locate any projects in the _Package Explorer_ or _Project Explorer_ that have little `?` icons
      on them (these projects should no longer be in source control)
    * Right-click on __only them__, and then click _Delete_.
    * __CHECK__ the _"Delete project contents on disk"_ checkbox.
    * Click _OK_ (confirm git does not contain any new unstaged files for delete)
    * Select all projects in the _Package Explorer_ or _Project Explorer_
    * Right-click on them, and then click _Delete_ (this may not work if projects are not collapsed)
    * Leave _"Delete project contents on disk"_ checkbox __UNCHECKED__
    * Click _OK_.  You should now have an empty _Package Explorer_ or _Project Explorer_.
    * `gradle -I gradle/support/fetchDependencies.gradle`
    * `gradle prepdev cleanEclipse eclipse buildNatives`
    * From Eclipse, _File -> Import..._
    * _General | Existing Projects into Workspace_
    * Select root directory to be your downloaded or cloned ghidra source repository
    * Check _"Search for nested projects"_
    * Click _Finish_
    
    This should get Eclipse back to a fresh state. There should never be a need to re-clone the
    repository.

* __Problem:__ _The Ghidra run configurations (launchers) are missing_.
  * __Solution:__
    The Ghidra run configurations are kept under source control in various modules' `.launch/` 
    directories (i.e., `Ghidra/Features/Base/.launch/`). As long as the corresponding module 
    project is imported into Eclipse (i.e., `Features Base`), the run configurations should be
    available in Eclipse under _Run -> Run Configurations_.  If they aren't there and the 
    projects are imported, try closing and reopening Eclipse. 
    
    __NOTE:__ Sometimes you have to launch Ghidra via the _Run -> Run Configurations..._ window one
    time for the run configuration to show up under the favorites menu in the main Eclipse button 
    bar.
    
    __NOTE:__ Never address missing run configurations by manually importing them via _File -> 
    Import... -> Run/Debug -> Launch Configurations._ This avoids the real issue and will 
    inevitably result in duplicate run configurations showing up one day, which can cause
    additional confusion.

## Known Issues
* There is a known issue in Gradle that can prevent it from discovering native toolchains on Linux 
  if a non-English system locale is being used. As a workaround, set the following environment 
  variable prior to running your Gradle task: `LC_MESSAGES=en_US.UTF-8`
* If the Ghidra build is only finding versions of Python that do not have access to `pip`, it may
  be necessary to perform the build from a Python [virtual environment][venv].

[java]: https://dev.java
[cpp]: https://isocpp.org
[sleigh]: https://htmlpreview.github.io/?https://github.com/NationalSecurityAgency/ghidra/blob/stable/GhidraDocs/languages/index.html
[python]: https://www.python.org
[venv]: https://docs.python.org/3/tutorial/venv.html
[jython]: https://www.jython.org
[eclipse]: https://www.eclipse.org/downloads/
[pydev]: https://www.pydev.org
[gradle]: https://gradle.org
[git]: https://git-scm.com
[apache]: https://www.apache.org/licenses/LICENSE-2.0
[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
[ghidra-data]: https://github.com/NationalSecurityAgency/ghidra-data
[DbgGuide]: DebuggerDevGuide.md

End of document.

Search documentation