jGRASP Plugin for Eclipse

The jGRASP Plugin for Eclipse brings the jGRASP viewers and viewer canvas to the Eclipse Java debugger.



Requirements

The plugin is compatible with Eclipse Neon or higher. The Java development tools (JDT) must be installed.

The plugin runs on Windows and macOS. We are working on Linux compatibility but so far it is not clear if this will be possible. Do not install the current version on Linux as using it will cause lock-ups.


Notes

At this early stage, there may be frequent updates. Use "Help" > "Check for Updates" to check more often than normal (once per week is the default).

Some features on macOS are limited (see Features below) due to Eclipse bug 538818. If you are familiar with the inner workings of SWT on macOS, any help with a fix or work-around for this bug would be appreciated.


Installation

To install the plugin, in Eclipse go to "Help" > "Install New Software...". On the "Work with" line at the top, hit the "Add..." button. Enter the location https://www.jgrasp.org/eclipse_plugin . Hit the "Add" button on the dialog.

"jGRASP" should appear in the available software dialog. Select it and hit "Next", "Next", accept the license agreement and hit "Finish". Accept the restart dialog.


Features and Use

With the plugin installed, a "jGRASP" menu will appear on the menu bar. From there you can open a viewer canvas, change settings (currently just the font scale for all plugin UI), copy the jGRASP example files, and open jGRASP help items.

Buttons for opening a viewer canvas , "run in canvas" , and autostep/autoresume mode will also appear on the main toolbar. These allow the canvas to be used in a "movie" mode that runs automatically through steps or breakpoints. This is useful for understanding code and for debugging.

To use the jGRASP viewers, you must either set a breakpoint in your program and use the "Debug" toolbar button or "Run" > "Debug" menu item. Alternately, the jGRASP "run in canvas" toolbar item or menu item will start the debugger and stop at the first line of main().

Depending on how you installed Eclipse, step filtering may be on or off by default. You will most likely not want to step into Java library code. To turn on filtering, under "Preferences" "Java / Debug / Step Filtering", check "Use Step Filters" and check each of the defined filters in the list. Beware of accidentally turning off the "Use Step Filters" toolbar button (looks like the Eclipse "Step In" button but with a double arrow).

The details panes for the debug Variables tab, Expressions tab, hover variable window, and "Inspect" window will display a jGRASP viewer for the variable in place of the default view. Due to the SWT_AWT bridge bug mentioned above, on macOS, only the hover variable view will display a viewer. The Variables tab and Expressions tab will show a simple view with a handle that may be used to drag out a viewer (this may be dropped on a viewer canvas or dropped anywhere else to launch a stand-alone viewer), and the "Inspect" window will show the default view.

On Windows, variables in the Variables tab and expressions in the Expressions tab can be dragged directly onto a viewer canvas. On macOS, they can be dragged using the handles ( for primitives, for references) that appear in the details pane when a variable or expression is selected.

On the variables context (right click) menu, "View by Name (jGRASP)" and "View by Value" (jGRASP)" will appear. These will open a viewer tied to either the name (variables tree path expression in Variables tab, expression in Expressions tab) of the variable, or the primitive or object value of the variable respectively.

For information on features of the jGRASP viewers and viewer canvas, see the documentation and linked videos on this website. We highly recommend viewing our Viewer Canvas YouTube video.


Future Plans

Possible support for use of the plugin on Linux.

Viewers for SWT classes will be added for those classes that would benefit.

An extension point will be created so that user and third-party viewers can be added as plugins.

The jGRASP "Interactions" and "Workbench" features will be added.