Debugger

MPS provides a special language for creating run configurations for languages generated into java – jetbrains.mps.baseLanguage.runConfigurations. Those run configurations are able to start under debugger automatically. For more information, refer to Run configurations for languages generated into java.

When one views variables and fields in a variable view, one may want to define one's own way to show certain values. For instance, collections could be shown as a collection of elements rather than as an ordinary object with all its internal structure.

For creating custom viewers MPS has jetbrains.mps.debugger.java.customViewers language.

The jetbrains.mps.debugger.java.customViewers language enables one to write one's own viewers for data of certain form.

A main concept of customViewers language is a custom data viewer. It receives a raw java value (an objects on stack) and returns a list of so-called watchables. A watchable is a pair of a value and its label (a string which categorizes a value, for example, whether a value is a method, a field, an element, a size, and so on) Labels for watchables are defined in custom watchables container. Each label could be assigned an icon.

The viewer for a specific type is defined in a custom viewer root. In the following table custom viewer parts are described:

Custom Viewers language introduces two new types: watchable list and watchable.

This is the custom viewer specification for java.util.Map.Entry class:

And here we see how a map entry is displayed in debugger view:

tip

Note that the JDT-tools solution must be imported into your plugin solution in order to compile your custom viewers.

This section describes how to specify which nodes require to save some additional information in trace .info file (like information about positions text, generated from the node, visible variables, name of the file the node was generated into, and so on). trace.info files contain information allowing to connect nodes in MPS with generated text. For example, if a breakpoint is hit, java debugger tells MPS the line number in source file and to get the actual node from this information MPS uses information from trace .info files.

Specifically, trace.info files contain the following information:

• position information: name of text file and position in it where the node was generated;

• scope information: for each "scope" node (such that has some variables, associated with it and visible in the scope of the node) – names and ids of variables visible in the scope;

• unit information: for each "unit node" (such that represent some unit of a language, for example a class in java) – name of the unit the node is generated into.

Concepts TraceableConcept, ScopeConcept and UnitConcept of language jetbrains.mps.lang.traceable are used for that purpose. To save some information into trace.info file, user should derive from one of those concepts and implement the specific behavior method. The concepts are described in the table below.

Concept	Description	Behavior method to implement	Example
TraceableConcept	Concepts for which location in text is saved and for which breakpoints could be created.	getTraceableProperty – some property to be saved into trace.info file.
ScopeConcept	Concepts which have some local variables, visible in the scope.	getScopeVariables – variable declarations in the scope.
UnitConcept	Concepts which are generated into separate units, like classes or inner classes in java.	getUnitName – name of the generated unit.

trace.info files are created on the last stage of generation – while generating text. So the described concepts are only to be used in languages generated into text. The entries are filled in automatically, whenever a TraceableConcept , ScopeConcept or UnitConcept are being generated through a reduction rule.

When automatic tracing is impossible, the $TRACE$ macro can be used in order to match the desired input node of a concept from language.high with the generated code explicitly.

To specify how breakpoints are created on various nodes, root breakpoint creators is used. This is a root of concept BreakpointCreator from jetbrains.mps.debugger.api.lang language. The root should be located in the language plugin model. It contains a list of BreakpointableNodeItem, each of them specify a list of concept to create breakpoint for and a method actually creating a breakpoint. jetbrains.mps.debugger.api.lang provides several concepts to operate with debuggers, and specifically to create breakpoints. They are described below.

• DebuggerReference – a reference to a specific debugger, like java debugger;

• CreateBreakpointOperation – an operation which creates a location breakpoint of specified kind on a given node for a given project;

• DebuggerType – a special type for references to debuggers.

On the following example breakpoint creators node from baseLanguage is shown.

In order to provide more complex filtering behavior, instead of a plain complex list breakpoint creators can use isApplicable function. There is an intention to switch to using this function.