Accès à l'intranetBuild date: 9-February-2007
$Date: 2007/01/24 13:40:51 $
Table of Contents
Kermeta is distributed with a workbench that provides many .
Current features in v0.4.0 are:
Text editor
Outline view
Problems view
Ecore Model Editor (provided by Eclipse/EMF)
Execution with an interpreter
Debugger
Transformations to and from Kermeta. (especially to Ecore)
Other helper transformations like Ecore merge
Dedicated Graphic editor
Class TouchNavigator (alpha version in release 0.1.1
Help system
Useful features needing the installation of an external tool:
Class diagram Ecore Model editor. This feature is provided by EclipseUML (Omondo) (a community edition is available)
Planned features:
Seamless integration of Java code
Object TouchNavigator
Here is a screenshot of a typical Kermeta workbench.
![[Warning]](http://www.kermeta.org/docs/html.single/KerMeta-UI-UserGuide/gfx/admonitions/warning.gif) | Warning |
|---|---|
| Kermeta is an evolving software and despite that we put a lot of attention to this document, it may contain errors or not conform to the latest version. If you find any error or have some information that improves this document, please send it to us using the bugtracker in the forge: http://gforge.inria.fr/tracker/?group_id=32 Last check: v0.4.0 |
Nowadays a textual editor is not just an editable document. Many informations have been provided to the user in order to get improved editing performances. It is quite common to find textual editor with coloring syntax, auto-completion and outline. These three items working together usually makes a good textual editor. That is the reason why the Kermeta platform provides such an editor. Below, you can find the global view of the Kermeta editor.
To develop faster and faster, some nice helpfull tools now are usual. One of them is the auto-completion. According to a context, a list of item will be proposed. Using the arrows key and the carriage return key, you can select quickly and easily the item you want. The important thing is that, the list of item is calculated in order to only propose some relevant items. The figure below shows the auto-completion for "stdio" which is a special class in Kermeta (as System for Java). The typed point makes the system think that you want to call a method on "stdio". Then all the callable methods are proposed and you can choose one of them.
![[Note]](http://www.kermeta.org/docs/html.single/KerMeta-UI-UserGuide/gfx/admonitions/note.gif) | Note |
|---|---|
| The usual <ctrl>+<space> keyboard shortcut is used to access the code completion |
The outline is a strucutral view of your program. Code is not visible in this view, but the structure that is to say packages, classes, attributes and methods are visible in a tree hierarchy. Usually the outline position is on the top right side of the Eclipse's window. You can get advantages of the outline, when your program reaches a big size and when it is difficult to get a good visibility on the program's strucutre. Browsing the outline is much more faster than browsing the file. Moreover, clicking on an item (packages, classes, attributes or methods) brings you to that item in the file.
sort features : The content of the outline is sorted alphabetically.
Flatten inheritance : Show package hierachy
Display all the features of your classes. The inherited features are displayed using a specific icon set.
Show imported types : Show all the classes that are declared using the require statement in this file.
| Note |
|---|---|
| The Flatten inheritance also display the features of the Object class as all the Kermeta classes inherit from it. |
| Warning |
|---|---|
| The "Show imported types" feature works on a per file basis and then it only shows the features declared using the require statement in this file and NOT all the files in your project. |
The textual editor is used to display extra pieces of information than simple text. In the figure below, a parsing error is reporting because of the semicolon which is not allowed in the language. The nice is thing is that in the Eclipse's problems view, just by double clicking on an error opens the errored file and make the cursor focusing on the correct line.
Kermeta is meant an executable language. So, we may want to debug programs because of their complexity. It is possible because Kermeta platform includes a debugger. Like in a Java style, some breakpoints can be added to the program by right clicking on the grey line at the left of the editor (as in the figure below). The breakpoint will be added in front of the selected line. Afterwards, when running the debugger, the program will halt at every breakpoint it goes through. At this moment, you will be able to have a look at the variables' value and run step by step or step into some methods.
Kermeta workbench allows to run your Kermeta code in several ways.
For those who already know how to run Java applications, this is a similar approach but for Kermeta files.
You'll need to create a new run configuration from the
"Run/Run..." menu.
![[Caution]](http://www.kermeta.org/docs/html.single/KerMeta-UI-UserGuide/gfx/admonitions/caution.gif) | Caution |
|---|---|
| The run menu is available only with some perspectives. If you don't see the run menu, switch to the Kermeta perspective. |
In the dialog, you selects the file, the main class and the main operation that must be run.
Search buttons will help you to find these elements in your files.
| Caution |
|---|---|
| The search button may not work properly if your file contains errors. |
Two annotations in your Kermeta code allow you to save time while creating run configurations. The @mainClass and @mainOperation are used to fill field when creating a new configuration.
Ex:
@mainClass "automaton::Derterminization" @mainOperation "main"
Then, once you have your configuration, you can run it by all the
means provided by Eclipse. Ie. "Run Last Launched", "
Run History", ... available in the menus or in the
toolbars.
![[Tip]](http://www.kermeta.org/docs/html.single/KerMeta-UI-UserGuide/gfx/admonitions/tip.gif) | Tip |
|---|---|
A shortcut allows you to quickly start a Kermeta run configuration. It is available in the popup menu of *.kmt files. The "
Run As/Kermeta App
" button runs an existing configuration and the "
Run As/Run...
" button opens the configuration dialog.
|
The operation arguments field allow you to pass some strings as parameters of the operation you are launching.
Optionnaly, in the common Tab of the Kermeta run configuration, you can:
save your configuration in a file, so you can share it with other users: in "Common" tab button "Shared file"
specify where the stdio outputs must be sent. Typically, this can be in the Eclipse console or in a file.
It is possible to run a Kermeta program from ant using the RunCommandLine.java from a java task.
You'll have to correctly set the classpath and the argument
[Give more details on that]
| Warning |
|---|---|
| This method need to know precisely which jar you use. If you update any of the required plugins (kermeta, emf, ecore , ...) the directory containing the jar will change because eclipse uses the version number as part of the directory name. You'll have to manually change your ant file in order to reflect the update. |
The Interpreter provides different facades in order to run a Kermeta program. The RunCommandLine class allows to pass the name of: the Kermeta source file, and optionnaly the name of the class and the opertation to run.
You can create a Java application LaunchConfiguration that will run the interpreter with your Kermeta file.
Be careful, you must select "Include external jars when searching for a main class".
The output level of interpreter traces can be set using a log4j configuration file. The concrete file to use is set by the java property "kermeta.log4j.configurationfile.name". A sample of log4j configuration file is located in the textEditor plugin.
Exemple add the following in the VM arguments box: -Dkermeta.log4j.configurationfile.name= "../../plugins/fr.irisa.triskell.kermeta.texteditor_0.0.4/kermeta_log4j_configuration.xml"
The classpath must be carefully set using the jar of Kermeta, the jar of Ecore and of emf.
| Tip |
|---|---|
| This RunCommandLine class or one of its sibling can also be used by any of your java programs.For more information please see the Javadoc reference of RunCommandLine. |
| Warning |
|---|---|
| This method need to know precisely which jar you use. If you update any of the required plugins (kermeta, emf, ecore , ...) the directory containing the jar will change because eclipse use the version number as part of the directory name. You'll have to manually change to ant file in order to reflect the update. |
The command line needs several options to run properly a kermeta program.
.
-C : (takes 1 argument) Qualified name of the class to run
ex: myPackage::MyClass
Note that it will not instanciate the class (ie. self will return void)
-H : (takes 0 argument) Display the help
-T : (takes 0 argument) Run as a test suite
-P : (takes 0 argument) Display Profiling info
-K : (takes 1 argument) Location for kermeta standard unit(framerwork.km) (KermetaUnit.STD_LIB_URI variable)
-O : (takes 1 argument) Name of the operation to run
-U : (takes 1 argument) URI of the unit file that must be loaded
-M : (takes 1 argument) Indicate a file containing URI_MAP (This is usefull to solve some model loading troubles)
Other values on the command line will be passed as string to the operation
Exemple of arguments for a kermeta program:
-P -U ../ModelEngineeringCourse/transfo/add_observer.kmt -C pattern_macros::Main -O main -K lib/framework.km ../models/needs_observer.ecore Compteur Afficheur
When you run a kermeta program outside of Eclipse, the uri of type platform:// are not correctly resolved.
This option allow to specify a file that contains mapping to help to resolve those uri.
This uri map file uses the syntax of java properties files.
Exemple of uri.map file which maps some platform:// urls into file:// urls
# "platform:/plugin/fr.irisa.triskell.kermeta/" "file:/C:/eclipse3.0.2/eclipse/plugins/fr.irisa.triskell.kermeta_0.0.16/" "platform:/resource/fr.irisa.triskell.kermeta/" "file:/C:/eclipse3.0.2/eclipse/workspace/fr.irisa.triskell.kermeta/"
Since v0.1.0 Kermeta has a debugger. As any debugger, it proposes breakpoints step over, step into, run, resume, visualization of variables, etc
A debugger offers users the possibility to interprete Kermeta's programs step by step, or stopping programs at one moment to check the the programs' state. Above you can see the global view of the editor.
During programs execution, you may want to know variables' values. For that purpose, you can use the watch view which displays all the variables accessible in the current context and their values. Moreover you can browse those vaiables to have a deeper look inside variables.
A frame is a context environment for a call method. That means that for each method call, you have access to its context that is to say the variables values. Obviously, it is strongly related to the watch view. Clicking on one frame modifies the watch view. The frame view is also nice to follow the execution. For instance, in the figure above, we know that the run method has called the step method which has called the fire method.
When debugging, you surely want to know which line of code is executed. That is the reason why the Kermeta text editor is displayed with the outline. The current line of code is colored in green as in the following figure. This green line is moving to the next instruction depending your action.
There are three kind of actions you can execute:
F5 : pressing the F5 key makes the debugger entering in the current operation.
F6 : pressing the F6 key makes the debugger stepping to the next operation.
F8 : pressing the F8 key makes the debugger executing all the operations to the next breakpoint, if there is some one.
| Note |
|---|---|
A nice feature is that you can add or remove breakpoints to your Kermeta file during debugging. |
The current help and many other documentation are available in the Eclipse Help system of your Eclipse installation: open Help -> Help Contents
| Tip |
|---|---|
| Alternatively, an online version of all those documents is available at http://www.kermeta.org/documents |
The workbench provides several additional tools available directly on the files using the popup menu.
Export functions: On ecore file you can export it into a KM (kermeta program in xmi format) or in kmt (Kermeta program using its textual syntax). As the ecore model may not be valid, the wizard provides some quick fixes. Those quick fixes will for example detect and propose a default solution for multiple operations with the same name.
Merge function: You can merge several ecore files, simply select them and click "merge". Its algorithm is base on the names of the packages and classes.
Register/Unregister EPackages function: You can register or unregister in the EMF registry the EPackages defined in an Ecore model, simply select them and right-click "Register" or "Unregister".
From a kmt files you can export it to an ecore file. Each of the kermeta notion that don't have a specific representation in ecore are stored into ecore annotations that will allow to roundtrip back to kermeta.
The kmt file can also be exported into its model version (ie. Into a XMI file conformant to kermeta metamodel). This is usefull as this process also typecheck the model and thus allow to save some time when loading other file wich rely on the km version rather than the kmt version.
From a km files you can export it to an ecore file. Each of the kermeta notion that don't have a specific representation in ecore are stored into ecore annotations that will allow to roundtrip back to kermeta.
You can also prettyprint this model representation of a kermeta program into the textual representation of this program.
For many of those transformations, the wizard will propose you to store the traceability informations.
This is a special metamodel that stores a link between the sources elements and the target element so you can reuse it later. For example, it will help the debugger to retreive the correct line in the text version of the source file even if you are running the km version.
This metamodel is very generic and can be used for any model.
The Kermeta Graphical Editor is a view of the Kermeta model as a class diagram. It is generated with the tool "Topcased". The file containing the presentation informations is a *.kmdi. The *.kmdi is associated with a *.km file. The *.kmdi and *.km files must be in the same folder.
We can open it, simply select and right-click "Open with / Kermeta class diagram"
In order to create a Kermeta class diagram you have 2 ways.
Create a class diagram and the Kermeta model from scratch. Select the project or the folder where you want create the class diagram and right-click "New / Other / Kermeta / New Kermeta class diagram". Change the model name if you want.
Create a class diagram from an existing Kermeta model. Select the existing km file and right-click "New / Other / Kermeta / New Kermeta class diagram".
The Kermeta Class TouchNavigator is a view that dynamically focuses on the element you are viewing in the editor or the outline.
With its damping animation, it proposes an original way to navigate and analyse your metamodel classes.
>The color depends on the distance to the selected node.
Back and Forward button allow to navigate the history of seleted nodes.
It provides several lens for smarter vizualisation. For exemple you can zoom, rotate, set the locality (ie. How much nodes you display at once depending on the distance to the selection) or use the hyperbolic lens (Ie. Change the edge length depending on the distance).
If you leave your mouse over a class, it shows its documentation.
| Tip |
|---|---|
| It is in alpha stage, feel free to notify us what you found interresting or not in this view. |
This Editor is provided by Eclipse in EMF.
Since Kermeta metamodel is an extension of EMOF, it is possible to use this editor to edit Kermeta programs.
This based on the Ecore2Kermeta and Kermeta2Ecore transformations.
With the Ecore representation of your program, you can use the Ecore Model editor (from Eclipse\EMF) or any other Ecore tool (for example Omondo.graphic editor)
This is described with more details in the EMF tutorial: http://www.kermeta.org/docs/html.single/KermetaEMFTutorial/
| Tip |
|---|---|
| This section contains many useful information about how to use the Kermeta workbench. |
Keyboard shortcut | Action |
|---|---|
<CTRL>+<SPACE> | Pertinent code completion. This work for both in sevral places in the code. |
[TODO check with the platform tip and tricks page which eclipse shortcut correctly work with Kermeta editor]
