diff --git a/DevGuide.md b/DevGuide.md index 0f24924f53..1d6fc18f89 100644 --- a/DevGuide.md +++ b/DevGuide.md @@ -87,14 +87,19 @@ prevent specific tasks from running: gradle buildGhidra -x ip ``` -## PyGhidra +## PyGhidra Development 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): +To prepare PyGhidra for development and/or debugging, first execute the following gradle task: +``` +gradle prepPyGhidra +``` +This sets up a Python virtual environment at `build/venv/`, and installs an editable PyGhidra +module (and its dependencies) into it. 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..._ @@ -106,27 +111,7 @@ well as the typing/stub information. From Eclipse (with PyDev installed): 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 - variable prior to running your Gradle task: `LC_MESSAGES=en_US.UTF-8` - -## Offline Development Environment -Sometimes you may want to move the Ghidra repository to an offline network and do development there. -These are the recommended steps to ensure that you not only move the source repository, but all -downloaded dependencies as well: - -1. `gradle -I gradle/support/fetchDependencies.gradle` -2. `gradle -g dependencies/gradle prepdev` -3. Move ghidra directory to different system -4. `gradle -g dependencies/gradle buildGhidra` (on offline system) - -**NOTE**: The `-g` flag specifies the Gradle user home directory. The default is the `.gradle` -directory in the user’s home directory. Overriding it to be inside the Ghidra repository will -ensure that all maven central dependencies that were fetched during the `prepdev` task will be moved -along with the rest of the repo. - -## Developing GhidraDev Eclipse Plugin +## GhidraDev Eclipse Plugin Development 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 @@ -144,6 +129,21 @@ preferences, and under _Target Platform_, activate _/Eclipse GhidraDevPlugin/Ghi See [Building GhidraDev](GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md#building) for instructions on how to build the GhidraDev plugin. +## Offline Development Environment +Sometimes you may want to move the Ghidra repository to an offline network and do development there. +These are the recommended steps to ensure that you not only move the source repository, but all +downloaded dependencies as well: + +1. `gradle -I gradle/support/fetchDependencies.gradle` +2. `gradle -g dependencies/gradle prepdev` +3. Move ghidra directory to different system +4. `gradle -g dependencies/gradle buildGhidra` (on offline system) + +**NOTE**: The `-g` flag specifies the Gradle user home directory. The default is the `.gradle` +directory in the user’s home directory. Overriding it to be inside the Ghidra repository will +ensure that all maven central dependencies that were fetched during the `prepdev` task will be moved +along with the rest of the repo. + ## Running tests To run unit tests, do: ``` @@ -354,11 +354,18 @@ We also provide out-of-the-box QEMU integration via GDB. When submitting help tickets and pull requests, please tag those related to the debugger with "Debugger" so that we can triage them more quickly. +## 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/master/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 diff --git a/Ghidra/Features/PyGhidra/build.gradle b/Ghidra/Features/PyGhidra/build.gradle index 54e535a222..216131e5d5 100644 --- a/Ghidra/Features/PyGhidra/build.gradle +++ b/Ghidra/Features/PyGhidra/build.gradle @@ -86,8 +86,9 @@ task installGhidraStubs(type: Exec) { } } -// Install PyGhidra in editable mode to the development virtual environment -task installEditablePyGhidra(type: Exec) { +// Prepares PyGhidra for development by installing it in editable mode to the development virtual +// environment +task prepPyGhidra(type: Exec) { dependsOn("installJPype") dependsOn("installGhidraStubs") @@ -98,8 +99,4 @@ task installEditablePyGhidra(type: Exec) { doFirst { commandLine "$PYTHON3_VENV", "-m", "pip", "install", "-e", "src/main/py", "--no-index", "-f", "$dir" } -} - -if (findPython3(false)) { - rootProject.prepDev.dependsOn installEditablePyGhidra -} +} \ No newline at end of file diff --git a/README.md b/README.md index dbaa9407fe..433c70caa4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # Ghidra Software Reverse Engineering Framework - Ghidra is a software reverse engineering (SRE) framework created and maintained by the [National Security Agency][nsa] Research Directorate. This framework includes a suite of full-featured, high-end software analysis tools that enable users to analyze compiled code on a @@ -22,7 +21,6 @@ cybersecurity tools for NSA to help protect our nation and its allies, consider [career with us][career]. ## Security Warning - **WARNING:** There are known security vulnerabilities within certain versions of Ghidra. Before proceeding, please read through Ghidra's [Security Advisories][security] for a better understanding of how you might be impacted. @@ -35,14 +33,14 @@ To install an official pre-built multi-platform Ghidra release: `ghidra___.zip` which can be found under the "Assets" drop-down. Downloading either of the files named "Source Code" is not correct for this step. * Extract the Ghidra release file -* Launch Ghidra: `./ghidraRun` (or `ghidraRun.bat` for Windows) +* Launch Ghidra: `./ghidraRun` (`ghidraRun.bat` for Windows) + - or launch [PyGhidra][pyghidra]: `./support/pyGhidraRun` (`support\pyGhidraRun.bat` for Windows) For additional information and troubleshooting tips about installing and running a Ghidra release, please refer to the [Installation Guide][installationguide] which can be found in a Ghidra release at `docs/InstallationGuide.html`. ## Build - To create the latest development build for your platform from this source repository: ##### Install build tools: @@ -119,7 +117,7 @@ gradle prepdev eclipse buildNatives When Eclipse finishes building the projects, Ghidra can be launched and debugged with the provided **Ghidra** Eclipse *run configuration*. -For more detailed information on developing Ghidra, please read the [Developer Guide][devguide]. +For more detailed information on developing Ghidra, please read the [Developer Guide][devguide]. ## Contribute If you would like to contribute bug fixes, improvements, and new features back to Ghidra, please @@ -143,3 +141,4 @@ source project. [master]: https://github.com/NationalSecurityAgency/ghidra/archive/refs/heads/master.zip [security]: https://github.com/NationalSecurityAgency/ghidra/security/advisories [ghidradev]: GhidraBuild/EclipsePlugins/GhidraDev/GhidraDevPlugin/README.md +[pyghidra]: Ghidra/Features/PyGhidra/README.md diff --git a/gradle/root/venv.gradle b/gradle/root/venv.gradle index 4178c83386..2074e671de 100644 --- a/gradle/root/venv.gradle +++ b/gradle/root/venv.gradle @@ -34,7 +34,3 @@ task createPythonVirtualEnvironment(type: Exec) { args "-m", "venv", venvDir, "--copies" } } - -if (findPython3(false)) { - rootProject.prepDev.dependsOn createPythonVirtualEnvironment -}