---++ Debugging Stratego in Spoofax Projects
Spoofax supports debugging of Stratego code used in the implementation of the various editor services.
The Stratego debugger re-uses the Eclipse Debug Perspective
making debugging Stratego code similair to debugging Java code.

Debugging can be enabled/disabled per project as it has a negative impact on the performance.
The debugger has to be enabled for two components: (1) enable debug instrumentation in the ant build file and 
(2) enable the debug mode for the runtime.

Currently, debugging support is only available in the nightly builds of Spoofax, use http://spoofax.org/update/nightly as the Eclipse Update site.

---+++ Enable Debug Instrumentation

First, to enable debug instrumentation add a file called <tt>.debugmode</tt>
in the project directory.
Adding this file will make sure the project is build with debug information.

Second, change the provider in the Builders.esv file from <tt>ctree</tt> to <tt>jar</tt>.

And third, change the "all" ant target from
<pre>
&lt;target name="all" depends="spoofaximp.default"/&gt;
</pre>
to
<pre>
&lt;target name="all" depends="spoofaximp.default.jar"/&gt;
</pre>

Now rebuild the project.
After a succesful build the <tt>trans-debug</tt> directory contains the stratego files 
from the <tt>trans</tt> directory instrumented with debug information.
The instrumented stratego files are compiled to a jar file that is located in the <tt>include</tt> directory.


---+++ Enable Debug Runtime

Although the project is build with debug information the debug mode still has to be enabled.
It is wise to only enable debug mode when it is really needed as it has a huge impact on the performance.
Disabling debug mode will still instrument the stratego code, but any breakpoints are ignored.

Select a DSL file (probably in the test directory of the project).
Select _Enable debug mode_ from the _Transform_ menu to enable stratego debugging for this Spoofax project.

http://strategoxt.org/pub/Spoofax/DebugStratego/enable-debug-mode-menu.png

Sometimes the project will rebuild. 
Check if the debug mode was actually enabled by clicking on the _Transform_ menu, the _Enable debug mode_ menu item should have changed to _Disable debug mode_.
If not select the _Enable debug mode_ menu item again.

Now open a stratego file and set a breakpoint.

http://strategoxt.org/pub/Spoofax/DebugStratego/breakpoint-in-editor.png

When this breakpoint is hit Eclipse switches to the Debug View and the execution is suspended.

http://strategoxt.org/pub/Spoofax/DebugStratego/debug-view-overview.png

The variables window shows the available variables, the current term (<tt>*current*</tt>) and the names of the dynamic rules that are available (<tt>*dynamic rules*</tt>).

http://strategoxt.org/pub/Spoofax/DebugStratego/variables.png

Also, you can control the execution of the program with Step Into (F5), Step Over (F6), Step Return (F7) and Resume (F8).

http://strategoxt.org/pub/Spoofax/DebugStratego/execution-control.png


-- Main.RickyLindeman - 22 Jun 2011