GEMOC Studio Documentation
Language workbench user guide

^[15]

The debug step information is the information that indicates to the engine when it can suspend/resume/step/break in a model execution.

The information provided here will typically drive the Debug view (the stack of step frames) and the Timelines.

Debug step information used by the views in the Debug perspective are driven by the engine kind.

If the language uses the Java engine (see Section 1, “Make a sequential executable language”), then this is the annotation @Step that drives the places where the execution can suspend and the stack of steps in the Debug view.

If the language uses the CCSLJava engine (see Section 2, “Make a concurrent executable language”), then this is every call to a DSA (defined by event in the ECL file) that can suspend.

^[16]

Debug RunTime Data information used by the views in the Debug perspective are driven by the declaration of which data in the model can change during the model execution with regard to the part of the model that do not change.

Basically, this means that the elements in ecore of the language that can change during the execution must be annotated with aspect annotation.

The elements tagged with this will be treated as mutable and used by the various part of the studio when deployed in the modeling workbench. This includes for example the Variables view, the MultiDimentional timeline view, the trace, …​

Figure 5. Model debug RTD using aspect annotation in k3fsm.ecore.

Figure 5, “Model debug RTD using aspect annotation in k3fsm.ecore.” shows a basic usage of this annotation on the example K3FSM Example and its effect on the Variables view and Multidimentional Timeline view in Figure 6, “Aspect annotation effect in Modeling workbench.”.

Figure 6. Aspect annotation effect in Modeling workbench.

^[17]

The multidimentional trace is a mechanism that enables some extra feature in the debugger in the Modeling workbench. This turns the debugger into an omniscient debugger with forward/backward features and advanced visualization of data changes in the model.

This feature can be enabled by using the generator on top of the xdsml project and generate the Trace Addon Project.

^[18]

The debug layer is an extension on top of a graphical editor defined with Sirius (See Section 3.2, “Defining a Concrete Syntax with Sirius” for more details about Sirius.) which represents the current instruction and provides commands to enable/disable breakpoints. This layer is activated when the model is executed in Debug mode.

This section covers the debug representation creation wizard and the technical implementation details. Technical implementation details are only useful for advanced use case and troubleshooting.

2.1.1. The debug representation wizard

This wizard creates a layer to represent the current instruction and add commands in order to manage breakpoints and launch a simulation in debug mode. This is a default implementation, it can be customized to represent runtime data for instance. The customization uses the Sirius description definition, see the Sirius Specifier Manual for more details. The wizard presents three ways to implement this layer:

• Create a debug diagram description
• Extend an existing diagram description
• Add a debug layer to an existing diagram description

2.1.1.1. Create a debug diagram description

It creates a diagram representation with a default debug layer. The representation does not depend on another representation. A typical use case is a language where the runtime data representation is too far from the language graphical syntax.

2.1.1.2. Extend an existing diagram description

It creates a diagram representation with a default debug layer that extends an existing representation. This allows to have a debug layer based on the representation of the language concrete syntax. The language concrete syntax can be deployed without the debug representation. A typical use case is the reuse of an existing diagram definition that you cannot modify by yourself. For instance if you want to use UML, you can reuse the UML Designer.

You can select any diagram description.

And then define the new diagram description which extends the one you previously selected.

2.1.1.3. Add a debug layer to an existing diagram description

It creates a default debug layer in an existing diagram representation. This should be used if you are also in charge of the language concrete syntax.

In this case, you can only select a diagram description from the workspace.

2.1.2. Implementation details

Implementation details are for advanced use and troubleshooting. It explains how the implementation works behind the scene. There are two main elements covered here : the debugger services class and the debug layer itself.

2.1.2.1. Debugger services

The debugger services class is use to tell which representations should be activated and refreshed during debug (see the getRepresentationRefreshList() method). It also provides a method to know if an element of the diagram is the current instruction. This is provided by the isCurrentInstruction() method.

Important

The line res.add(new StringCouple("DD_or_RN", "LAYER_ID")); indicates which layers are part of the "debug" animation. Ie. if these layers must be activated automatically and updated when an execution is in debug mode.

The way to indicate the layer depends on how you have created the layer:

• in case of a single odesign with all layers in a single viewpoint:

  • the first String DD_or_RN is the id of the Diagram Description
  • the second String LAYER_ID is the id of the Layer

• in case of a diagram extension:

  • the first String DD_or_RN is the Representation Name of the Diagram Extension (do not confuse with the Name !!)
  • the second String LAYER_ID is the id of the Layer

2.1.2.2. Debug layer

The default debug layer adds action to start the simulation in debug mode and to toggle breakpoints (1). When a breakpoint exists for an element of the diagram, a visual feedback is displayed according to the breakpoint state (2). The current instruction is also highlighted in yellow by default (3).

This is a default debug layer, it can be customized to fit your needs. The customization use the Sirius description definition, see the Sirius Specifier Manual for more details.

^[20]

The Sirius editor defined Section 3.2, “Defining a Concrete Syntax with Sirius” can also be extended in order to present the RunTime Data during a model execution.

A good design consists in creating a dedicated layer that would be enabled on every execution in both Debug mode and Run mode.

The design principles are similar to the one used in Section 2.1, “Define a debug representation and commands for Sirius”. It can add either new diagram or new layers on top of existing diagrams in order to display the domain specific RunTime Data. Additionally, a service is registered in order to activate the layer when starting the execution and trigger refresh event during the execution.

^[21]

GEMOC offers an API to develop Engine Addons. These addons have access to the engine execution context, the model and its runtime data. As they are refreshed during the execution, they are convenient to provide many services including animated UI for representing the model.

For example, they will easily connect to a dedicated Eclipse view.

Tip

An Engine addon may be generic and apply to any language, but it can also be language specific. In that case, you should prefer to add its code in the project containing the dsl file of the language and declare it in the plugin.xml.

This way, the addon will be available only for this specific language.

Figure 7. Add language specific Engine Addon on DSL

See Section 1.1, “Developing new Addons” for technical detail about addon implementation.

^[22]

A designer of the DSA code (see Make language executable) can also call a dedicated GUI (for example opening an AWT, Swing, SWT window) and then populate it during the execution. In order to not freeze the general UI of the engine, the GUI must start in another thread. This thread can be initialized during the model initialization method of the engine (The initialization may differ depending on the engine see Section 1.2, “Defining the initialization function” or Section 2.1.4, “Defining the initialization function”).

ECL specification is the starting point toward exploration. In this specification we define events associated with the actions of the DSA and also events associated with the DSE events. On these event bindings we apply the MoccML relations of the MoC Library to schedule the events. A finite state space of a system uses such scheduling constraints and therefore a configuration file to target an exhaustive exploration tool must be generated:

T1 transformation generates a configuration file to later target exhaustive exploration or simulation tools. T1 takes as input the ECL mapping definition between the DSL and the MoCCML to generate a transformation T2 describing transformation rules that will be used to produce the processes for the DSL related functions and data (DSA) and the behavioral processes corresponding to the MoCCML constraints.

T1 is automatically generated from ecl model and results are stored in mtl-gen folder.

However to execute T1 manually right-click on the ECL file → Exhaustive Exploration → Generate ClockSystem transformation from ECL model as illustrated in figure Figure 9, “Using T1 Tranformation”.T2 is generated in the repository <mtl-gen>.

Figure 9. Using T1 Tranformation