Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "VIATRA2/UseCases/DebuggingAndVisualisation"

(The VIATRA Console)
(Extending the VIATRA Console with new commands)
 
(2 intermediate revisions by the same user not shown)
Line 60: Line 60:
  
 
=== Extending the VIATRA Console with new commands ===
 
=== Extending the VIATRA Console with new commands ===
 +
 +
The VIATRA Console can be extended with new commands easily using the <code>org.eclipse.viatra2.gui.consoleCommandProvider</code> extension point. You need to provide two components:
 +
* a command implementation class, implementing the <code>IVIATRAConsoleCommandProvider</code> interface
 +
* a command factory that adds your command classes to the system
 +
 +
See a few simple, self-explanatory examples below:
 +
 +
==== MANIFEST.MF ====
 +
 +
  Require-Bundle:
 +
  org.eclipse.viatra2.gui;bundle-version="3.1.0",
 +
 +
==== Command implementation ====
 +
 +
  import org.eclipse.viatra2.frameworkgui.views.console.commands.IVIATRAConsoleCommandProvider;
 +
  public class YourCommand implements IVIATRAConsoleCommandProvider {
 +
  public void executeCommand(IFramework fw, List<String> parameters) {
 +
    /* implementation */
 +
  }
 +
  /* displayed in the list of commands generated by the >>listcommands<< built-in command */
 +
  public String getCommandSignature() {
 +
    return "functionName(someParameter)";
 +
  }
 +
  public String getDescription() {
 +
    return "...";
 +
  }
 +
  public String getHelpText() {
 +
    return "...";
 +
  }
 +
  }
 +
 +
==== Command Factory ====
 +
 +
  import org.eclipse.viatra2.frameworkgui.views.console.commands.IVIATRAConsoleCommandProviderFactory;
 +
  public class YourCommandFactory implements IVIATRAConsoleCommandProviderFactory {
 +
  public List<IVIATRAConsoleCommandProvider> getProviders(IFramework fw) {
 +
    ArrayList<IVIATRAConsoleCommandProvider> ps = new ArrayList<IVIATRAConsoleCommandProvider>();
 +
    ps.add(new YourCommand());
 +
    return ps;
 +
  }
 +
 +
==== plugin.xml ====
 +
 +
  <extension point="org.eclipse.viatra2.gui.consoleCommandProvider">
 +
  <commandProviderFactory
 +
    class="sample.YourCommandFactory">
 +
  </commandProviderFactory>
 +
  </extension>
  
 
== Model Space Visualisation and Debugging ==
 
== Model Space Visualisation and Debugging ==

Latest revision as of 12:10, 7 September 2010

Transformation Debugging in VIATRA2

The VIATRA2 framework does not contain a dedicated debugger, but there are other features that can be used to support debugging. These are:

  • Output rules
  • The VIATRA Console
    • Undoable Transformations
    • Executing Single Rules
  • Model Space Visualisation

Output rules

The print and println rules can be used to output the value of any selected transformation program variable to the output. A typical use would be to output the matches of the precondition in the action part of a graph transformation rule:

gtrule rule(in Token) = {
  precondition find token(Token)
  action {
     println(Token);
  }
}

The VIATRA Console

The VIATRA framework provides a VIATRA2 Console view that is capable of displaying the messages of the framework, and allowing the execution of commands. By default the debug messages are disabled because of their possible large number - it is only recommended to turn it on while it is explicitely needed. Furthermore, the display of "debug", "info", "warning" and "error" messages can be turned on-off using the toggle buttons on the top right part of the toolbar of the VIATRA Console view. The red X button is used to clear the contents of the console buffer.

The commands of the console can be listed used the listcommands code together with a short description. Console commands can take an arbitrary number of parameters, which need to be separated by commas for invocation.

The Console supports command name auto-completion (in the text input field on the bottom may be used to enter commands), by using the tab key. Additionally, the console features a command history (press the UP and DOWN arrow keys in the command entry field) for convenience.

VIATRA2 UseCases Console.png

Executing transformations and single rules

Transformations may be invoked using the runmachine. As the first parameter, you need to supply the fully qualified ID of the machine (namespace and name, separated with dots; as it is displayed in the VIATRA2 Model Spaces view), and a semicolon-separated list of parameter name=value pairs (if the machine's main rule takes parameters). An example:

 runmachine(notions.transformer,Model=notions.model.01_preliminaries;Target=latex.model)
 > runmachine([notions.transformer, Model=notions.model.01_preliminaries;Target=latex.model])

The console will echo a parsed version of your command as the first feedback line of execution.

During debugging, a transformation developer may need to run only a single ASM rule of the transformation program, instead of the entire machine. The runrule allows executing a single rule of the transformation on the current model space, the parametrization is the same as for runmachine

Undoable Transformations

When you execute a transformation program from the user interface of VIATRA2, it may change the model space (although these changes are not automatically saved). However, during transformation development, it is a common need to execute the same transformation program on the same model, so it is useful to be able to revert the changes after a transformation has been executed.

To achieve this, the runmachineundoable and runruleundoable commands can execute ASM machines or a single ASM rule in a way that the undotransaction command can undo all of their changes. This technique speeds up the debugging process by eliminating the need to close and re-open model spaces.

An example interaction sequence may look like this:

 runmachineundoable(notions.transformer,Model=notions.model.01_preliminaries)
 > runmachineundoable([notions.transformer, Model=notions.model.01_preliminaries])
 [info] Entity successfully interpreted.
 [info] Trigger engine: A transactional operation ended in the system.
 [info] Transformation engine ran for 61 milliseconds.
 [info] Transformation transaction ID: TRANS_4
 
 undotransaction(TRANS_4)
 > undotransaction([TRANS_4])
 [info] Trigger engine: A transactional operation ended in the system.

In this sequence, we first execute the "notions.transformer" transformation (using an input parameter mapping where the "Model" parameter takes the value of "notions.model.01_preliminaries") in an undoable transaction, and then undo this transaction to ensure that the state of the model space is restored to its original (before the transformation was executed).

Command scripts

The VIATRA Console has the ability to save a history of executed commands into line-delimited textual files ("command scripts"), by calling the savecommandscript built-in command. These scripts can be later loaded and automatically executed, by the executecommandscript built-in command. You can use this facility as a light-weight batch execution environment for e.g. importing models (nativeimport), executing rules or transformations (runmachine) etc.

Extending the VIATRA Console with new commands

The VIATRA Console can be extended with new commands easily using the org.eclipse.viatra2.gui.consoleCommandProvider extension point. You need to provide two components:

* a command implementation class, implementing the IVIATRAConsoleCommandProvider interface
* a command factory that adds your command classes to the system

See a few simple, self-explanatory examples below:

MANIFEST.MF

 Require-Bundle:
  org.eclipse.viatra2.gui;bundle-version="3.1.0",

Command implementation

 import org.eclipse.viatra2.frameworkgui.views.console.commands.IVIATRAConsoleCommandProvider;
 public class YourCommand implements IVIATRAConsoleCommandProvider {
  public void executeCommand(IFramework fw, List<String> parameters) {
   /* implementation */ 
  }
  /* displayed in the list of commands generated by the >>listcommands<< built-in command */
  public String getCommandSignature() {
   return "functionName(someParameter)";
  }
  public String getDescription() {
   return "...";
  }
  public String getHelpText() {
   return "...";
  }
 }

Command Factory

 import org.eclipse.viatra2.frameworkgui.views.console.commands.IVIATRAConsoleCommandProviderFactory;
 public class YourCommandFactory implements IVIATRAConsoleCommandProviderFactory {
  public List<IVIATRAConsoleCommandProvider> getProviders(IFramework fw) {
   ArrayList<IVIATRAConsoleCommandProvider> ps = new ArrayList<IVIATRAConsoleCommandProvider>();
   ps.add(new YourCommand());
   return ps;
  }

plugin.xml

 <extension point="org.eclipse.viatra2.gui.consoleCommandProvider">
  <commandProviderFactory
    class="sample.YourCommandFactory">
  </commandProviderFactory>
 </extension>

Model Space Visualisation and Debugging

The model space visualisation component can be used to view a part of the model space as a graph, and it also reacts to changes of the model space: when a displayed model element changes (e.g. after the execution of a rule it is deleted), the changes are immediately reflected on the visualisation (e.g. the related node is deleted).

It is important to note that the model space visualisation component only helps to understand the actual state of the model space, but it does not contain any option to alter it.

Back to the top