Many updates to the Development Guide

DevGuide.md

@@ -1,25 +1,54 @@
-# Developer's Guide: Getting Started
+# Developer's Guide 
+
+## Catalog of Dependencies
+
+The following is a list of dependencies, in no particular order.
+This guide includes instructions for obtaining each of these at the relevant step(s).
+You may not need all of these, depending on which portions you are building or developing.
+
+* JDK 11 - We test and build using OpenJDK 11.0.2.
+* Eclipse - It must support JDK 11. Eclipse 2018-12 or later should work. Other IDEs may work, but we have not tested them.
+* Gradle 5.0 - Later versions may work, but you'll need to modify our version check.
+* A C/C++ compiler - We use Visual Studio 2017 on Windows, GCC on Linux, and Xcode (Clang) on macOS.
+* Git - We use git-bash on Windows. Most Linux distros have git in their repos. Xcode provides git on macOS.
+* Bash - This is moot on Linux and macOS. On Windows, we use MinGW. This may be distributed with Git for Windows.
+* Bison and Flex - We use MinGW on Windows. Most Linux distros have these in their reposs. Xcode provides these for macOS.
+* dex2jar
+* AXMLPrinter2
+* HFS Explorer 0.21
+* Yet Another Java Service Wrapper 12.12 - Only to build Ghidra package.
+* Eclipse PDE - Only for the GhidraDev plugin.
+* Eclipse CDT 8.6.0 - Only for the GhidraDev plugin
+* PyDev 6.3.1 - Only for the GhidraDev plugin
+
+There are many others automatically downloaded by Gradle from Maven Central and Bintray JCenter when building and/or setting up the development environment.
+
+## Install Development and Build Tools
+
+If you're on Windows, install Git.
+You may also need to install MinGW.
+Many of the commands given below must be executed in Bash.
 
 Install OpenJDK 11 and make sure it's the default java.
 
-Install a version of Eclipse with good support for Java 11.
+Install Eclipse.
-Eclipse 2018-12 or later should work.
+You can launch Eclipse with any JRE/JDK, but you'll need to ensure Eclipse knows about your JDK 11 installation.
-Technically, you can launch with any JRE/JDK, but it's up to you ensure OpenJDK 11 is properly configured in Eclipse.
+In Eclipse, select Window -> Prefereces (Eclipse -> Preferences on macOS), then navigate to Java -> Installed JREs, and ensure a JDK 11 is configured.
 
-Install Gradle 5.0, add it to your `PATH`, and ensure it is launched using OpenJDK 11.
+Install Gradle, add it to your `PATH`, and ensure it is launched using JDK 11.
-Other versions of Gradle may work, but they have not been tested.
 
-## Setup Repositories
+## Setup Source and Dependency Repositories
 
-Of course, you may choose any directory for your working copy, but these instructions will assume you have cloned the repo to `~/git`.
+You may choose any directory for your working copy, but these instructions will assume you have cloned the source to `~/git/ghidra`.
 Be sure to adjust the commands to match your chosen working directory if different than suggested:
 
 ```bash
+mkdir ~/git
 cd ~/git
 git clone git@github.com:NationalSecurityAgency/ghidra.git
 ```
 
-Ghidra's build uses artifact named as available in Maven Central and Bintray JCenter, when possible.
+Ghidra's build uses artifacts named as available in Maven Central and Bintray JCenter, when possible.
 Unfortunately, in some cases, the artifact or the particular version we desire is not available.
 So, in addition to mavenCentral and jcenter, you must configure a flatDir-style repository for manually-downloaded dependencies.
 
@@ -37,7 +66,7 @@ allprojects {
 }
 ```
 
-You should also create the `~/flatRepo` folder to hold the manually-downloaded dependencies:
+Create the `~/flatRepo` folder to hold the manually-downloaded dependencies:
 
 ```bash
 mkdir ~/flatRepo
@@ -85,13 +114,24 @@ cp csframework.jar hfsx_dmglib.jar hfsx.jar iharder-base64.jar ~/flatRepo/
 ## Import Gradle Project
 
 If you want just to build Ghidra, you may skip ahead to Building Ghidra.
-Import Ghidra into Eclipse using the integrated BuildShip plugin.
+Otherwise, import Ghidra into Eclipse using the integrated BuildShip plugin.
+Select File -> Import, expand Gradle, and select "Existing Gradle Project."
+Select the root of the source repo as the root Gradle project.
 Be sure to select Gradle 5.0, or point it at your local installation.
-Other IDEs should work, but we have not tested with them.
 You may see build path errors until the environment is properly prepared, as described below.
 
-*Alternatively*, you may have Gradle generate the Eclipse projects (`gradle eclipse`) and import those instead.
+*Alternatively*, you may have Gradle generate the Eclipse projects and import those instead.
 This is the way to go if you'd prefer not to activate Gradle's BuildShip plugin.
+From the project root:
+
+```bash
+gradle eclipse
+```
+
+Select File -> Import, expand General, and select "Existing Projects into Workspace."
+Select the root of the source repo, and select "Search for nested projects."
+Select all, and Finish.
+You may see build path errors until the environment is properly prepared, as described below.
 
 ## Prepare the Environment
 
@@ -100,7 +140,7 @@ From the project root, execute:
 ```bash
 gradle prepDev -x yajswDevUnpack
 ```
-The `prepDev` tasks primarily include generating some source, indexing our online help, and unpacking some dependencies.
+The `prepDev` tasks primarily include generating some source, indexing our built-in help, and unpacking some dependencies.
 Regarding `yajswDevUnpack`, please see the relevant sections on GhidraServer below.
 For now, we exclude the unpack task.
 
@@ -110,7 +150,7 @@ Optionally, to pre-compile all the language modules, you may also execute:
 gradle sleighCompile
 ```
 
-Refresh the Gradle project in Eclipse.
+Refresh the projects in Eclipse.
 You should not see any errors at this point, and you can accomplish many development tasks.
 However, some features of Ghidra will not be functional until further steps are taken.
 
@@ -118,7 +158,7 @@ However, some features of Ghidra will not be functional until further steps are
 
 Some of Ghidra's components are built for the native platform.
 We currently support Linux, macOS, and Windows 64-bit x86 systems.
-Others should be possible, but we do not support them.
+Others should be possible, but we do not test on them.
 
 #### decompile
 
@@ -139,7 +179,7 @@ gradle decompileOsx64Executable
 On Windows:
 
 ```cmd
-gradlew decompileWin64Executable
+gradle decompileWin64Executable
 ```
 
 #### demangler_gnu
@@ -160,7 +200,7 @@ gradle demangler_gnuOsx64Executable
 On Windows:
 
 ```cmd
-gradlew demangler_gnuWin64Executable
+gradle demangler_gnuWin64Executable
 ```
 
 #### sleigh
@@ -184,12 +224,16 @@ gradle sleighOsx64Executable
 On Windows:
 
 ```cmd
-gradlew sleighWin64Executable
+gradle sleighWin64Executable
 ```
 
 ## Run Ghidra from Eclipse
 
-To run or debug Ghidra from Eclipse, use the provided launcher.
+To run or debug Ghidra from Eclipse, use the provided launch configuration (usually under the "Run" or "Debug" buttons).
+If the launcher does not appear, it probably has not been marked as a favorite.
+Click the dropdown next to the "Run" button and select "Run Configurations."
+Then expand "Java Application" on the left to find the "Ghidra" launcher.
+
 
 # Building Ghidra
 
@@ -198,9 +242,8 @@ To build the full Ghidra distribution, you must also build the GhidraServer.
 ## Get Dependencies for GhidraServer
 
 Building the GhidraServer requires "Yet another Java service wrapper" (yajsw) version 12.12.
-Note that building the full Ghidra package requires building the GhidraServer.
 Download `yajsw-stable-12.12.zip` from their project on www.sourceforge.net, and place it in a directory named:
-`ghidra.bin/Ghidra/Features/GhidraSerer/`:
+`ghidra.bin/Ghidra/Features/GhidraSerer/`. Note that `ghidra.bin` must be a sibling of `ghidra`:
 
 ```bash
 cd ~/Downloads   # Or wherever
@@ -240,9 +283,8 @@ To test it, unzip it where you like, and execute `./ghidraRun`.
 
 Some features of Ghidra require the curation of rather extensive data bases.
 These include the Data Type Archives and Function ID Databases, both of which require collecting header files and libraries for the relevant SDKs and platforms.
-Much of this work is done by hand, and the results are simply copied into the build.
+Much of this work is done by hand.
-We intend to document these procedures as soon as we can.
+Until this process is documented, those artifacts can be extracted from an official distribution and combined with your build output.
-In the meantime, those artifacts can always be extracted from our binary release.
 
 ## Building Data Type Archives
 
@@ -257,15 +299,20 @@ TODO
 First, install the Eclipse Plugin Development Environment (PDE).
 By default, the GhidraDev project is excluded from the build.
 To enable it, uncomment it in `settings.gradle`.
+
+```bash
+${EDITOR:-vi} settings.gradle
+```
+
 You will need some additional runtime dependencies:
 
 ## Get Dependencies for GhidraDev
 
 Building the GhidraDev plugin for Eclipse requires the CDT and PyDev plugins for Eclipse.
 Download `cdt-8.6.0.zip` from The Eclipse Foundation, and place it in a directory named:
-`ghidra.bin/GhidraBuild/EclipsePlugins/GhidraDev/buildDependencies/`.
+`ghidra.bin/GhidraBuild/EclipsePlugins/GhidraDev/buildDependencies/`. Note that
 `ghidra.bin` must be a sibling of `ghidra`.
-To respect the CDT project's resources, you will need to download the file using a browser, or at the very least, locate a suitable mirror on your own:
+To respect the Eclipse Project's resources, you may need to download the file using a browser, or at the very least, locate a suitable mirror on your own:
 
 ```bash
 cd ~/Downloads   # Or wherever