Chapter 3. Interpreting a Kermeta code

Chapter 3. Interpreting a Kermeta code
Prev		Next

Kermeta workbench allows to interpret and run your Kermeta code in several ways.

3.1. Using a Run configuration

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.

Figure 3.1. Run menu

	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.

Figure 3.2. Kermeta run configuration - main tab

Two optional 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 "fsm::Main"
@mainOperation "mainloadFSM"

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
	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.

Figure 3.3. Run shortcut to run configuration on the kmt files

The operation arguments field allow you to pass some strings as parameters of the operation you are launching.

In this sample screenshot, the FSM take a string as teh path to the file that will be loaded and simulated.

In addtion to this simple scenario, 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.
specify additional entries in the interpreter classpath that must be taken into while running this kermeta code. This is needed if you use "extern" call to your own jars.

	Tip
	If you specify the kermeta project u=in the run configuration and if this project is an eclipse plugin, then the interpreter will automatically take this plugin and all its dependencies into account in tha classpath.

3.2. Run the interpreter with a Java command line

You can run Kermeta interpreter from the command line. For this you need to run the java class org.kermeta.interpreter.api.RunCommandLine which is available in fr.irisa.triskell.kermeta.interpreter plugin. The RunCommandLine class allows to pass the name of: the Kermeta source file, and optionally the name of the class and the operation to run.

	Note
	The package org.kermeta.interpreter.api provides different facades in order to run a Kermeta program with the interpreter from a java program. You can either have a look to the document Deploying Kermeta code manual or you may also have a look into class `RunCommandLine` to see how it was implemented.

The interpreter command line is available in two main forms : as a set of eclipse plugin (it is available with all kermeta version deployed in Eclipse, or as a standalone jar (see Kermeta download page for the various distributions).

The standalone bundle is available in two version : all in one jar (typically kermeta_standalone_full_1.3.0.jar), or only kermeta in the main jar (typically kermeta_standalone_no_thirdparty_in_main_jar.1.3.0.zip. In this second version, the thirdparty jar aren't included.

Depending wether you use the standalone jars or the jar embedded in eclipse, the process will be more or less simple. The simpliest is to use the standalone version because you don't need to deal with the classpath.

java -jar kermeta_standalone.jar  -U ecore_mdk/add_observer.kmt -C pattern::AddObserver -O main 
         input_models/needs_observer.ecore output_models/ Compteur Afficheur

	This sample launches the file `add_observer.kmt` and will start the operation `main` of the class `pattern::AddObserver`.
	This sample kermeta programs takes 4 strings as parameters.

Example 3.1. Simpliest use of the standalone version on the command line

3.2.1. Command line options

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 useful to solve some model loading troubles)

Other values on the command line will be passed as string to the operation

java -jar kermeta_standalone.jar  -P -U ../ModelEngineeringCourse/transfo/add_observer.kmt -C pattern_macros::Main -O main 
        -K lib/framework.km ../models/needs_observer.ecore Compteur Afficheur

	This sample launches the file `add_observer.kmt` and will start the operation `main` of the class `pattern_macros::Main`.
	forces the interpreter to use a specific framework.km instead of the one inside the jar.
	This sample kermeta programs takes 3 strings as parameters.

Example 3.2. Example of a kermeta program called with the standalone version on the command line

3.2.2. About the URI map

When you run a kermeta program outside of Eclipse, the uri of type platform:// are not resolved since this is the role of Eclipse to resolve them. So, when running outiside of Eclipse, you need to help this resolution.

The resolution can be done using a map, whenever it find the key, it will replace it with the associated value. Like that you can transform platform:/plugin/ into a physical location in your disk.

With RunCommandLine.java, this is the option -U which allow to specify a file that contains the mapping.

This uri map file uses the syntax of java properties files.

Example of uri.map file which maps some platform:// urls into file:// urls

#Typical uri.map file
"platform:/plugin/"   "file:/C:/eclipse3.4/eclipse/workspace_head/"
"platform:/resource/" "file:/C:/eclipse3.4/eclipse/workspace_head/"
"kconf:/loader/"      "file:/C:/eclipse3.4/eclipse/workspace_head/org.kermeta.io.loader/instances/"

This special uri is used by kermeta to retrieve the folder instances in the plugin org.kermeta.io.loader. Kermeta intepreter cannot work correctly without it.

Another easy way (not detailed here) would be to retrieve one of the standalone versions and run it from eclipse.

	Tip
	With this map mechanism, you can also translate the platform uris into jar protocol. This protocol allows to search within a jar. for example, `jar:file:/my.jar!/src/kermeta/framework.km` opens the file `my.jar` and pick the file named `framework.km` into the subfolder `src/kermeta` in the jar.

3.2.3. Run the eclipse version of the interpreter in eclipse

In this section we focus on calling the interpreter embedded in an eclipse installation.

	Note
	This is quite an advanced use case recommanded only for people who understand how eclipse files are organized and can manually create a classpath to retreive the various jar in eclipse installation.

From eclipse, you create a Java application LaunchConfiguration that will run the interpreter with your Kermeta file.

Figure 3.4. Java run configuration main tab

Be careful, you must select "Include external jars when searching for a main class".

Figure 3.5. Java run configuration arguments

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 fr.irisa.triskell.kermeta.model plugin.

Exemple add the following in the VM arguments box: -Dkermeta.log4j.configurationfile.name= "../../plugins/fr.irisa.triskell.kermeta.model_1.3.0/kermeta_log4j_configuration.xml"

The classpath must be carefully set using the jar of Kermeta, the jar of Ecore and of emf.

Figure 3.6. Java run configuration classpath (using the interpreter jars in the texteditor)

	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.

Prev		Next
Chapter 2. The Text Editor	Home	Chapter 4. Compiling a kermeta code into java