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

GP-0: Converting GhidraSleighEditor docs to Markdown

Browse Source
This commit is contained in:
Ryan Kurtz 2024-10-25 10:59:31 -04:00
parent 6a7bdfe105
commit fbbb875a9f
5 changed files with 265 additions and 291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
GhidraBuild/EclipsePlugins/GhidraSleighEditor/certification.manifest
View File

@ -28,10 +28,9 @@ ghidra.xtext.sleigh.ui/src/ghidra/xtext/sleigh/ui/outline/SleighOutlineTreeProvi
ghidra.xtext.sleigh.ui/src/ghidra/xtext/sleigh/ui/quickfix/SleighQuickfixProvider.xtend||GHIDRA||||END|
ghidra.xtext.sleigh/.launch/Generate Sleigh (sleigh) Language Infrastructure.launch||GHIDRA||||END|
ghidra.xtext.sleigh/.launch/Launch Runtime Eclipse.launch||GHIDRA||||END|
ghidra.xtext.sleigh/GhidraSleighEditor_README.html||GHIDRA||||END|
ghidra.xtext.sleigh/META-INF/MANIFEST.MF||GHIDRA||||END|
ghidra.xtext.sleigh/README.md||GHIDRA||||END|
ghidra.xtext.sleigh/build.properties||GHIDRA||||END|
ghidra.xtext.sleigh/build_README.txt||GHIDRA||||END|
ghidra.xtext.sleigh/plugin.xml||GHIDRA||||END|
ghidra.xtext.sleigh/src/ghidra/xtext/sleigh/GenerateSleigh.mwe2||GHIDRA||||END|
ghidra.xtext.sleigh/src/ghidra/xtext/sleigh/Sleigh.xtext||GHIDRA||||END|

201
GhidraBuild/EclipsePlugins/GhidraSleighEditor/ghidra.xtext.sleigh/GhidraSleighEditor_README.html
View File

@ -1,201 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>GhidraSleighEditor 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>GhidraSleighEditor README</h1>
<p>GhidraSleighEditor makes developing and modifying Ghidra Sleigh processor modules much more enjoyable by providing a modern
day context sensitive editor with syntax highlighting, navigation, context sensitive error notation, quick fixes, and more. The
editor is built with the excellent XTEXT DSL framework within Eclipse.
</p>
<p>The information provided in this document is effective as of Ghidra Sleigh Editor 1.0.0 and is subject to
change with future releases.</p>
<ul>
<li><a href="#MinimumRequirements">Minimum Requirements</a></li>
<li><a href="#Install">Installing</a></li>
<ul>
<li><a href="#InstallpreBuilt">Installation pre-build editor in Eclipse</a></li>
<li><a href="#Building">Building Eclipse Sleigh Editor</a></li>
</ul>
<li><a href="#Uninstall">Uninstalling</a></li>
<li><a href="#Upgrade">Upgrading</a></li>
<li><a href="#Features">Sleigh Editor Features</a></li>
<ul>
<li><a href="#Hilite">Syntax Highlighting</a></li>
<li><a href="#Validate">Validation</a></li>
<li><a href="#QuickFix">QuickFix</a></li>
<li><a href="#Hover">Hover</a></li>
<li><a href="#References">Find References</a></li>
<li><a href="#Rename">Renaming</a></li>
<li><a href="#Format">Code Formating</a></li>
</ul>
<li><a href="#ChangeHistory">Change History</a></li>
</ul>
<h2><a name="MinimumRequirements"></a>Minimum Requirements</h2>
<ul>
<li>Eclipse 2019-3 with DSL and XTEXT 2.17 or later</li>
<li>Ghidra 9.0 or later</li>
</ul>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Install"></a>Installing GhidraSleighEditor</h2>
<p>GhidraSleighEditor is installed manually into Eclipse and should be installed by anyone interested in working with
processor module sleigh specifications. The Sleigh Editor must be manually installed in Eclipse. In the future the extension
may be installed automatically along with the GhidraDev Eclipse plugin when setting up Eclipse for Ghidra scripting and plugin development.</p>
<h3><a name="InstallpreBuilt"></a>Install pre-Built</h3>
<p>GhidraSleighEditor 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 GhidraSleighEditor zip file from <i>&lt;GhidraInstallDir&gt;</i>/Extensions/Eclipse/GhidraSleighEditor/
</li>
<li>Click <b>OK</b> (name field can be blank)</li>
<li>Check <b>Ghidra</b> category (or <b>Ghidra Sleigh Editor</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>Click <b>Install anyway</b></li>
<li>Click <b>Restart Now</b></li>
</ol>
<h3><a name="Building"></a>Building Eclipse Sleigh Editor</h3>
<ol>
<p>To build the Sleigh Editor, follow the instructions in ghidra/DevGuide.md to setup eclipse
for development. Then follow the directions in
<i>ghidra/GhidraBuild/EclipsePlugins/GhidraSleighEditor/ghidra.xtext.sleigh/build_README.txt</i>.</p>
</ol>
<h2><a name="Uninstall"></a>Uninstalling</h2>
<p>GhidraSleighEditor 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 Ghidra Sleigh Editor</li>
<li>Click <b>Uninstall...</b></li>
<li>Select Ghidra Sleigh Editor</li>
<li>Click <b>Finish</b></li>
<li>Click <b>Restart Now</b></li>
</ol>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Upgrade"></a>Upgrading</h2>
<p> GhidraSleighEditor can be upgraded the same way it was initially installed.</p>
<p>(<a href="#top">Back to Top</a>)</p>
<h2><a name="Features"></a>Sleigh Editor Features</h2>
<p>The Ghidra Sleigh Editor provides a variety of features one would expect in any modern IDE to make viewing, modifying, debugging,
and creating Sleigh processor specifications as painless as possible.
Once installed, any .sinc or .slaspec file that is edited will be brought up in the sleigh editor.</p>
<p>The editor provides the following capabilities:</p>
<ul>
<li><a name="Hilite"></a>Syntax Highlighting</li>
<ul>
<p>Keywords, Tokens, Sub-constructor names, Comments, Instruction Formats, Strings, Variables, and more can be colorized to make
the sliegh specification more readable. In the <b>Window &#8594; Preferences &#8594; Sleigh</b> preferences panel, the color and font style can be changed
for any sleigh file tokens.</p>
</ul>
<li><a name="Validate"></a>Validation</li>
<ul>
<p>The structure of a sleigh file while fairly simple can lend itself to errors when using a straight text editor. The editor understands
the syntax and all constructs of a sleigh file. Instead of waiting for the sleigh compiler to produce an error, many but not all syntax
errors can be caught and displayed with a red error marker.</p>
<p>The editor validates the definition of variables including locals.
Though legal in the sleigh compiler, it has been found that not declaring local variables leads to
errors that are not be caught by the sleigh compiler. For example, assigning to a variable 'ro' when the actual register name is 'r0' may go
unnoticed. All local variables must be defined with with the 'local' keyword or with an initial ':size'.</p>
<p>Warnings on duplicate names of tokens is marked in yellow. Complex matching patterns such as <i>'!='&nbsp&nbsp'&lt'&nbsp&nbsp'&gt'</i> are warnings as well. Using
comparison matching operators can cause the generated .sla file to be much larger than necessary. Comparison matching should really never be used on any
tokens that are bigger than a few bits as the number of match cases generated will be large. Their use is unavoidable in some cases.<p>
<p>There are some artificial enforcements in the editor that, while valid sleigh syntax, cause the syntax to be unparsable. Because the sleigh
Domain Specific Language (DSL) is a context sensitive grammer, as well as using define-like pre-processing expansion, the editor only allows define
<b>$()</b> variables at certain locations where a single token would reside. The most common flagged error is embedding a connecting '&' in a define and then
using it an a match pattern:
<ul>
<p><b>:MOV ax, bx is t1=1 $(BadDefine) {}</b> is not allowed, and instead should be <b>:MOV ax, bx is t1=1 & $(GoodDefine) {}</b>.</p>
</ul>
</ul>
<li><a name="QuickFix"></a>QuickFix</li>
<ul>
<p>Some simple syntax errors can be fixed quickly with QuickFix suggestions. Pressing Crtl-1 on an error will bring up available quick-fixes.</p>
<li>Undefined local variable - insert 'local' or the ':size" form if the size can be detected.</li>
<li>Undefined user pcodeop - can insert a user pcodeop definition for an unknown identifier</li>
<li>Undefined macro - can insert a macro definition for an unknown identifier</li>
<li>Add token field definition - for an unknown token in the match pattern</li>
</ul>
<p>More quick-fixes may be added in the future. Please note quickfixes can be slow on large files such as the AARCH64.</p>
<li><a name="Hover"></a>Hover</li>
<ul>
<p>There are many constructs in a sleigh file that, when hovered over, will display additional information. This is especially useful for tokens to get their
size without having to navigate to the token field definition. More hovers will be added.<p>
<li>Sub-Constructors will display all the defined sub-constructors with the same name.</li>
<li>Token field definitions will display their size, and if attached, the set of registers.</li>
<li>Registers display their size.</li>
<li>Numeric values will display in Hex, Binary, and Decimal.</li>
<li>$(Defines) display all the possible defines for the name, since the actual define used can't be known.</li>
</ul>
<li><a name="Navigate"></a>Navigation</li>
<p>If you have edited a sleigh processor specification in a regular text editor, you will appreciate the forward and backward navigation supported on
various variable name use and their associated definition. Navigation is supported on sub-constructor names, field token names, registers, macros names, local variables, define names, and user
define pcodeop's.</p>
<p>Navigate by pressing <b>&ltF3&gt</b> on a variable, using the forward/backward navigation arrows, or my favorite the &lt-* that will navigate
back to the last edit location.<p>
<li><a name="References"></a>Find References</li>
<p>Instead of keyword searching, the editor provides a find all uses of a variable. Each found use is listed in a search window with the text of the line where it is used displayed.
Each found location can also be navigated to by double clicking on the found reference.</p>
<p>Use the editor popup menu <b>Find References</b> action.</p>
<li><a name="Rename"></a>Renaming</li>
<p>The name of variables can be very important, and instead of doing a search and replace on a string, the editor can refactor a name and change all other uses of that name. The name
is even changed in other .sinc and .slaspec files.<p>
<p>Use the editor popup menu <b>Rename Element</b> action.</p>
<li><a name="Format"></a>Code Formating</li>
<p>Sleigh files can get large and messy during development. Instead of paying much attention to format, or trying to format by hand you can use the Source Format action.
Common constructs are lined up, for example the token definitions will find the longest token and line up all other tokens and their definition. All sub-constructors of the
same name will be lined up on the 'is' keyword, the match pattern, and the semantic definitions. All constructors 'is' keywords will be generally lined up based on the longest
print peice for each constructor. Statements will also be indented consistently. Multi-line attach definitions will have each entry lined up.
Formatting can be restricted to a selection of lines to stop formatting from entirely re-formatting carefully formatted files.
Additional formatting may be added in the future, and the formatter may become more configurable in the future.<p>
<p>Use the editor popup menu <b>Source &#8594; Format</b> action.</p>
</ul>
<h2><a name="ChangeHistory"></a>Change History</h2>
<p><u><b>1.0.0</b>:</u> Initial release in Ghidra 9.1</p>
<p>(<a href="#top">Back to Top</a>)</p>
<!-- Some padding -->
<br>
<br>
<br>
</body>
</html>

258
GhidraBuild/EclipsePlugins/GhidraSleighEditor/ghidra.xtext.sleigh/README.md Normal file
View File

@ -0,0 +1,258 @@
# GhidraSleighEditor Eclipse Plugin
GhidraSleighEditor makes developing and modifying Ghidra Sleigh processor modules much more
enjoyable by providing a modern day context sensitive editor with syntax highlighting, navigation,
context sensitive error notation, quick fixes, and more. The editor is built with the excellent
XTEXT DSL framework within Eclipse.
The information provided in this document is effective as of Ghidra Sleigh Editor 1.0.0 and is
subject to change with future releases.
## Table of Contents
1. [Change History](#change-history)
2. [Minimum Requirements](#minimum-requirements)
3. [Installing](#installing)
4. [GhidraSleighEditor Features](#ghidrasleigheditor-features)
* [Syntax Highlighting](#syntax-highlighting)
* [Validation](#validation)
* [QuickFix](#quickfix)
* [Hover](#hover)
* [Find References](#find-references)
* [Renaming](#renaming)
* [Code Formating](#code-formatting)
5. [Uninstalling](#uninstalling)
6. [Upgrading](#upgrading)
7. [Building](#building)
## Change History
__1.0.2:__
* Added `lzcount` to grammar
* Fixed cpool invalid error, and added test for cpool arguments
__1.0.1:__
* Added support for new endian tag on `define token` definitions
* Bug fix for `@if "!="` comparison
* Added `popcount` to grammar
__1.0.0:__
* Initial release
## Minimum Requirements
* Eclipse 2019-3 with DSL and XTEXT 2.17 or later
## Installing
GhidraSleighEditor is installed manually into Eclipse and should be installed by anyone interested
in working with processor module sleigh specifications. The GhidraSleighEditor must be manually
installed in Eclipse. In the future the extension may be installed automatically along with the
GhidraDev Eclipse plugin when setting up Eclipse for Ghidra scripting and plugin development.
GhidraSleighEditor can be installed into an existing installation of Eclipse the same way most
Eclipse plugins are installed. From Eclipse:
1. Click `Help -> Install New Software...`
2. Click `Add...`
3. Click `Archive...`
4. Select GhidraSleighEditor zip file from
`<GhidraInstallDir>/Extensions/Eclipse/GhidraSleighEditor/`
5. Click `OK` (name field can be blank)
6. Check `Ghidra` category (or `Ghidra Sleigh Editor` entry)
7. Click `Next`
8. Click `Next`
9. Accept the terms of the license agreement
10. Click `Finish`
11. Click `Install anyway`
12. Click `Restart Now`
## GhidraSleighEditor Features
The Ghidra Sleigh Editor provides a variety of features one would expect in any modern IDE to make
viewing, modifying, debugging, and creating Sleigh processor specifications as painless as possible.
Once installed, any `.sinc` or `.slaspec` file that is edited will be brought up in the sleigh
editor.
The editor provides the following capabilities:
### Syntax Highlighting
Keywords, Tokens, Sub-constructor names, Comments, Instruction Formats, Strings, Variables, and more
can be colorized to make the sliegh specification more readable. In the
`Window -> Preferences -> Sleigh` preferences panel, the color and font style can be changed for any
sleigh file tokens.
### Validation
The structure of a sleigh file while fairly simple can lend itself to errors when using a straight
text editor. The editor understands the syntax and all constructs of a sleigh file. Instead of
waiting for the sleigh compiler to produce an error, many but not all syntax errors can be caught
and displayed with a red error marker.
The editor validates the definition of variables including locals. Though legal in the sleigh
compiler, it has been found that not declaring local variables leads to errors that are not be
caught by the sleigh compiler. For example, assigning to a variable `ro` when the actual register
name is `r0` may go unnoticed. All local variables must be defined with with the `local` keyword or
with an initial `:size`.
Warnings on duplicate names of tokens is marked in yellow. Complex matching patterns such as
`'!=' '<' '>'` are warnings as well. Using comparison matching operators can cause the generated
.sla file to be much larger than necessary. Comparison matching should really never be used on any
tokens that are bigger than a few bits as the number of match cases generated will be large. Their
use is unavoidable in some cases.
There are some artificial enforcements in the editor that, while valid sleigh syntax, cause the
syntax to be unparsable. Because the sleigh Domain Specific Language (DSL) is a context sensitive
grammer, as well as using define-like pre-processing expansion, the editor only allows define
`$()` variables at certain locations where a single token would reside. The most common flagged
error is embedding a connecting `&` in a define and then using it an a match pattern:
`:MOV ax, bx is t1=1 $(BadDefine) {}` is not allowed, and instead should be
`:MOV ax, bx is t1=1 & $(GoodDefine) {}`.
### QuickFix
Some simple syntax errors can be fixed quickly with QuickFix suggestions. Pressing `Crtl-1` on an
error will bring up available quick-fixes:
* _Undefined local variable_ - insert `local` or the `:size` form if the size can be detected.
* _Undefined user pcodeop_ - can insert a user pcodeop definition for an unknown identifier
* _Undefined macro_ - can insert a macro definition for an unknown identifier
* _Add token field definition_ - for an unknown token in the match pattern
More quick-fixes may be added in the future. Please note quickfixes can be slow on large files such
as the AARCH64.
### Hover
There are many constructs in a sleigh file that, when hovered over, will display additional
information. This is especially useful for tokens to get their size without having to navigate to
the token field definition. More hovers will be added.
* Sub-Constructors will display all the defined sub-constructors with the same name.
* Token field definitions will display their size, and if attached, the set of registers.
* Registers display their size.
* Numeric values will display in Hex, Binary, and Decimal.
* `$(Defines)` display all the possible defines for the name, since the actual define used can't be
known.
### Navigation
If you have edited a sleigh processor specification in a regular text editor, you will appreciate
the forward and backward navigation supported on various variable name use and their associated
definition. Navigation is supported on sub-constructor names, field token names, registers, macros
names, local variables, define names, and user define pcodeop's.
Navigate by pressing `F3` on a variable, using the forward/backward navigation arrows, or my
favorite the `<-*` that will navigate back to the last edit location.
### Find References
Instead of keyword searching, the editor provides a find all uses of a variable. Each found use is
listed in a search window with the text of the line where it is used displayed. Each found location
can also be navigated to by double clicking on the found reference.
Use the editor popup menu `Find References` action.
### Renaming
The name of variables can be very important, and instead of doing a search and replace on a string,
the editor can refactor a name and change all other uses of that name. The name is even changed in
other `.sinc` and `.slaspec` files.
Use the editor popup menu `Rename Element` action.
### Code Formatting
Sleigh files can get large and messy during development. Instead of paying much attention to format,
or trying to format by hand you can use the Source Format action. Common constructs are lined up,
for example the token definitions will find the longest token and line up all other tokens and their
definition. All sub-constructors of the same name will be lined up on the `is` keyword, the match
pattern, and the semantic definitions. All constructors `is` keywords will be generally lined up
based on the longest print peice for each constructor. Statements will also be indented
consistently. Multi-line attach definitions will have each entry lined up. Formatting can be
restricted to a selection of lines to stop formatting from entirely re-formatting carefully
formatted files. Additional formatting may be added in the future, and the formatter may become more
configurable in the future.
Use the editor popup menu `Source -> Format` action.`
## Uninstalling
GhidraSleighEditor can be uninstalled as follows from Eclipse:
1. Click `Help -> About Eclipse`
* For macOS, `Eclipse -> About Eclipse`
2. Click `Installation Details`
3. Select Ghidra Sleigh Editor
4. Click `Uninstall...`
5. Select Ghidra Sleigh Editor
6. Click `Finish`
7. Click `Restart Now`
## Upgrading
GhidraSleighEditor can be upgraded the same way it was initially installed.
## Building
The GhidraSleighEditor is currently built from Eclipse and distributed with Ghidra manually.
Ideally we will use Gradle one day, but we aren't there yet. We do rely on `gradle prepDev` to
generate the Eclipse project and build GhidraSleighEditor's dependencies though, hence the
build.gradle file.
__NOTE:__ Only "Eclipse IDE for Java and DSL Developers" has the ability to do the below
instructions. The following instructions assume that you are using this version of Eclipse.
It is also suggested that you use the "Eclipse IDE for Java and DSL Developers" if you will
use the GhidraSleighEditor. You can build the GhidraSleighEditor installation zip with the XTEXT
runtime in the plugin. The XTEXT runtime was not included in the distribution build because it would
have added 80Meg.
Importing GhidraSleighEditor Eclipse projects (they are deactivated by default):
1. Uncomment the line in `settings.gradle` that includes the GhidraSleighEditor project.
2. Run `gradle eclipse -PeclipseDSL` to generate the GhidraSleighEditor Eclipse projects.
3. From Eclipse, `File -> Import -> General -> Existing Projects into Workspace`.
4. From the ghidra repo, import all "Eclipse GhidraSleighEditor *" projects.
Generating all Sleigh XTEXT generated files:
1. Open "Eclipse SleighEditor" project.
2. Navigate to the file `src -> ghidra.xtext.sleigh -> GenerateSleigh.mwe2`
3. __NOTE:__ The following will download a jar file from the internet (not from NSA) unless you
pre-download.
1. Download the file http://download.itemis.com/antlr-generator-3.2.0-patch.jar
2. Put the file in `ghidra/GhidraBuild/EclipsePlugins/SleighEditor/ghidra.xtext.sleigh`
3. Rename the file to `.antlr-generator-3.2.0-patch.jar`
4. From the popup menu `RunAs -> MWE2 Workflow`
* Files in xtend-gen and src-gen will be created
5. If there are any red bookmarks on any of the Eclipse Sleigh* projects,
* Select all the Eclipse Sleigh* projects, and refresh from the popup menu
* The project should rebuild, and there should be no red Problem errors
Try out the Sleigh Editor
1. Navigate to the `Eclipse SleighEditor` and chose `RunAs -> Eclipse Runtime`
2. Add a sleigh processor module
1. `File -> NewJavaProject...`
* Uncheck default location and navigate to a processor in `Ghidra/Processors/<X>`
* The project be automatically named `<X>`
* Finish
* Cancel Module creation
* Navigate to a `<X>/data/languages/<file>.sinc` or `<file>.slaspec`
* On the popup asking to convert to an XTEXT project, choose "Yes"
2. -OR-
* Drop a `.slaspec` or `.sinc` file from the file browser on eclipse
* This is good for quick viewing, however navigation across files may not work.
Optional: Changing version number (GhidraSleighEditor is versioned independently of Ghidra):
1. Open `feature.xml` in the GhidraSleighEditor Feature project.
2. In the "Overview" tab, update the "Version" field to `x.y.z.qualifier` and save.
3. Open `category.xml` in the GhidraSleighEditor Feature project.
4. Highlight `ghidra.xtext.sleigh.editor (x.y.z.qualifier)`, and click "Remove".
5. Highlight `ghidra.xtext.sleigh.editor`, and click "Add Feature".
6. Select `ghidra.ghidradev (x.y.z.qualifer)`, click "OK", and save.
7. Update "Change History" section of this document if necessary.
Optional: Including the XTEXT runtime
You can include the XTEXT runtime or redist module in the .zip file which will negate the need to
have Eclipse with the DSL in the Eclipse into which the Eclipse Sleigh Editor is installed to run.
1. Navigate to the ghidra.xtext.sleigh.feature
2. bring up the feature.xml with the Feature Manager Editor (dbl-click on it).
3. Go to the Included Features tab
4. Add...
5. Filter by `redist` and add `org.eclipse.xtext.redist`
Creating an installation zip file to install in Eclipse:
1. Do a `gradle prepDev` to ensure GhidraSleighEditor's dependencies are up-to-date.
2. `File -> Export -> Plug-in Development -> Deployable plugins and fragments`
3. Select `Archive file` and choose a directory to save it to. Name it
`GhidraSleighEditor-x.y.z.zip`.
4. In the "Options" tab make sure things look like this:
* Export source: UNCHECKED
* Package as individual JAR archives: CHECKED
* Generate p2 repository: CHECKED
* Categorize repository: CHECKED
* Qualifier replacement: CHECKED + clear field so default is used
* Save as Ant script: UNCHECKED
* Allow for binary cycles in target platform: CHECKED
* Use class files compiled in the workspace: UNCHECKED
5. Finish

9
GhidraBuild/EclipsePlugins/GhidraSleighEditor/ghidra.xtext.sleigh/build.gradle
View File

@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@ -72,7 +72,10 @@ rootProject.assembleDistribution {
include 'GhidraSleighEditor*.zip'
into "Extensions/Eclipse/GhidraSleighEditor/"
}
from ("${this.projectDir}/GhidraSleighEditor_README.html") {
}
rootProject.assembleMarkdownToHtml {
from ("${this.projectDir}/README.md") {
into "Extensions/Eclipse/GhidraSleighEditor/"
}
}

85
GhidraBuild/EclipsePlugins/GhidraSleighEditor/ghidra.xtext.sleigh/build_README.txt
View File

@ -1,85 +0,0 @@
The Ghidra Sleigh Editor for Eclipse is currently built from Eclipse and checked into the bin repo.
Ideally we will use Gradle one day, but we aren't there yet. We do rely on Gradle prepDev to generate
the Eclipse project and build GhidraSleighEditor's dependencies though, hence the build.gradle file.
Required: Eclipse IDE with Java and DSL version 2019-03 or later, XTEXT 2.17 or later.
The following instructions assume that you have setup Eclipse.
It is also suggested that you use the Eclipse IDE with DSL extensions already installed if you will
use the GhidraSleighEditor. You can build the GhidraSleighEditor installation zip with the XTEXT runtime
in the plugin. The XTEXT runtime was not included in the distribution build because it would
have added 80Meg.
Importing GhidraSleighEditor Eclipse projects (they are deactivated by default):
1) Uncomment the line in settings.gradle that includes the GhidraSleighEditor project.
2) Run "gradle eclipse -PeclipseDSL" to generate the GhidraSleighEditor Eclipse projects.
3) From Eclipse, File --> Import --> General --> Existing Projects into Workspace
4) From the ghidra repo, import all "Eclipse GhidraSleighEditor *" projects.
Generating all Sleigh XTEXT generated files:
1) open "Eclipse SleighEditor" project
2) navigate to the file src --> ghidra.xtext.sleigh --> GenerateSleigh.mwe2
3) NOTE: the following will download a jar file from the internet (not from NSA)
unless you pre-download.
3a) Download the file http://download.itemis.com/antlr-generator-3.2.0-patch.jar
3b) Put the file in ghidra/GhidraBuild/EclipsePlugins/SleighEditor/ghidra.xtext.sleigh
3c) Rename the file to .antlr-generator-3.2.0-patch.jar
3) From the popup menu RunAs --> MWE2 Workflow
- Files in xtend-gen and src-gen will be created
4) If there are any red bookmarks on any of the Eclipse Sliehg* projects,
- Select all the Eclipse Sleigh* projects, and refresh from the popup menu
- The project should rebuild, and there should be no red Problem errors
Try out the Sleigh Editor
1) Navigate to the 'Eclipse SleighEditor' and chose RunAs --> Eclipse Runtime
2) Add a sleigh processor module
2a) File --> NewJavaProject...
- Uncheck default location and navigate to a processor in Ghidra/Processors/<X>
- The project be automatically named <X>
- Finish
- Cancel Module creation
- Navigate to a <X>/data/languages/<file>.sinc or <file>.slaspec
- On the popup asking to convert to an XTEXT project, choose "Yes"
2b) -OR-
- drop a .slaspec or .sinc file from the file browser on eclipse
- this is good for quick viewing, however navigation across files may not work.
Optional: Changing version number (GhidraSleighEditor is versioned independently of Ghidra):
1) Open feature.xml in the GhidraSleighEditor Feature project.
2) In the "Overview" tab, update the "Version" field to x.y.z.qualifier and save.
3) Open category.xml in the GhidraSleighEditor Feature project.
4) Highlight ghidra.xtext.sleigh.editor (x.y.z.qualifier), and click "Remove".
5) Highlight ghidra.xtext.sleigh.editor, and click "Add Feature".
6) Select ghidra.ghidradev (x.y.z.qualifer), click "OK", and save.
7) Update GhidraDev_README.html "Change History" section if necessary.
Optional: Including the XTEXT runtime
You can include the XTEXT runtime or redist module in the .zip file which will negate the need
to have Eclipse with the DSL in the Eclipse into which the Eclipse Sleigh Editor is installed to run.
1) Navigate to the ghidra.xtext.sleigh.feature
2) bring up the feature.xml with the Feature Manager Editor (dbl-click on it).
3) Go to the Included Features tab
4) Add...
5) Filter by 'redist' and add org.eclipse.xtext.redist
Creating an installation zip file to install in Eclipse:
1) Do a Gradle prepDev to ensure GhidraDev's dependencies are up-to-date.
2) File --> Export --> Plug-in Development --> Deployable plugins and fragments
4) Select "Archive file" and choose a directory to save it to. It must end up in
ghidra.bin/GhidraBuild/Eclipse/GhidraDev/. Name it GhidraDev-x.y.z.zip.
5) In the "Options" tab make sure things look like this:
- Export source: UNCHECKED
- Package as individual JAR archives: CHECKED
- Generate p2 repository: CHECKED
- Categorize repository: CHECKED
- Qualifier replacement: CHECKED + clear field so default is used
- Save as Ant script: UNCHECKED
- Allow for binary cycles in target platform: CHECKED
- Use class files compiled in the workspace: UNCHECKED
6) Finish