Skip to content

Commit

Permalink
GP-0: Some README.md and DevGuide.md updates for PyGhidra and VSCode
Browse files Browse the repository at this point in the history
  • Loading branch information
ryanmkurtz committed Jan 3, 2025
1 parent 20285e2 commit a1f243e
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 8 deletions.
29 changes: 25 additions & 4 deletions DevGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Environment
* Primary Language: [Java][java]
* Secondary Languages: [C++][cpp], [Sleigh][sleigh], [Jython][jython]
* Secondary Languages: [C++][cpp], [Sleigh][sleigh], [Python 3][python] [Jython 2.7][jython]
* Integrated Development Environment: [Eclipse][eclipse]
* Build System: [Gradle][gradle]
* Source Control: [Git][git]
Expand Down Expand Up @@ -62,7 +62,7 @@ Build Javadoc:
gradle createJavadocs
```

Build Python3 packages for the Debugger:
Build Python3 packages for PyGhidra and the Debugger:
```
gradle buildPyPackage
```
Expand All @@ -87,6 +87,25 @@ prevent specific tasks from running:
gradle buildGhidra -x ip
```

## PyGhidra
The supported way to develop and debug PyGhidra is with the _[PyDev][pydev]_ plugin for Eclipse.
When PyDev is installed and configured, several new Eclipse run configurations will appear that
enable running and debugging PyGhidra from both _GUI_ and _Interpreter_ modes.

When you perform a `gradle prepdev`, a Python virtual environment gets setup at `build/venv/`. PyDev
should be pointed at this virtual environment so it has access to the editable PyGhidra module, as
well as the typing/stub information. From Eclipse (with PyDev installed):

1. _Settings -> PyDev -> Interpreters -> Python Interpreter_
2. Click _New..._
3. Click _Browse for python/pypy exe_
4. Choose `build/venv/bin/python3`
5. Enter a value for _Interpreter Name_
6. Check _Select All_ and press _OK_
7. Click the _Prefined_ tab, and then _New..._
8. Choose `build/typestubs/pypredef`
9. Click _Apply and Close_

## 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
Expand All @@ -111,10 +130,10 @@ along with the rest of the repo.
Developing the GhidraDev Eclipse plugin requires the
_Eclipse PDE (Plug-in Development Environment)_, which can be installed via the Eclipse marketplace.
It is also included in the _Eclipse IDE for RCP and RAP Developers_. To generate the GhidraDev
Eclipse projects, execute:
Eclipse projects and prepare the necessary dependencies, execute:

```
gradle eclipse -PeclipsePDE
gradle prepGhidraDev eclipse -PeclipsePDE
```

Import the newly generated GhidraDev projects into an Eclipse that supports this type of project.
Expand Down Expand Up @@ -345,8 +364,10 @@ When submitting help tickets and pull requests, please tag those related to the
[java]: https://dev.java
[cpp]: https://isocpp.org
[sleigh]: https://htmlpreview.github.io/?https://github.com/NationalSecurityAgency/ghidra/blob/master/GhidraDocs/languages/index.html
[python]: https://www.python.org
[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
Expand Down
12 changes: 8 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,10 +87,14 @@ For issues building, please check the [Known Issues][known-issues] section for p
### User Scripts and Extensions
Ghidra installations support users writing custom scripts and extensions via the *GhidraDev* plugin
for Eclipse. The plugin and its corresponding instructions can be found within a Ghidra release at
`Extensions/Eclipse/GhidraDev/` or at [this link][ghidradev].

**NOTE:** The *GhidraDev* plugin for Eclipse only supports developing against fully built
Ghidra installations which can be downloaded from the [Releases][releases] page.
`Extensions/Eclipse/GhidraDev/` or at [this link][ghidradev]. Alternatively, Visual Studio Code may
be used to edit scripts by clicking the Visual Studio Code icon in the Script Manager.
Fully-featured Visual Studio Code projects can be created from a Ghidra CodeBrowser window at
_Tools -> Create VSCode Module project_.

**NOTE:** Both the *GhidraDev* plugin for Eclipse and Visual Studio Code integrations only support
developing against fully built Ghidra installations which can be downloaded from the
[Releases][releases] page.

### Advanced Development
To develop the Ghidra tool itself, it is highly recommended to use Eclipse, which the Ghidra
Expand Down

0 comments on commit a1f243e

Please sign in to comment.