Installing Kermeta Development Environment
Document Actions
The following document is dedicated to people who would like to contribute to the development of Kermeta.
You can also browse the developer documentation here : https://www.kermeta.org/documents/dev/
Requirements:
- Java 1.5
- Eclipse 3.4.x
- EMF 2.3.x
- ANTLR
plugin from http://antlreclipse.sourceforge.net/updates/ update site
and checkout org.eclipse.gymnast.runtime.core project from emfatic_projects in kermeta cvs(both needed in order to update kermeta textual syntax) - Topcased 1.x.x (if you want to develop the graphical editor)
A simple way for getting Eclipse + EMF + Topcased: download the "toolkit-rcp" bundle of Topcased at: http://gforge.enseeiht.fr/frs/?group_id=7
- log4j and apache.commons.logging plugins (retrieve them using http://www.kermeta.org/update/ which has some dependencies to it into the official eclipse update site)
NOTE : a dedicated eclipse package is available for all platforms, that contains all the required plugins. Get is from http://www.kermeta.org/integration_build/base_packages/ .
Getting the Kermeta projects from SVN
Way 1:
Please refer to the following page for how to get the Kermeta projects from SVN : http://gforge.inria.fr/scm/?group_id=32
To get all the kermeta projects by the hand, set the modulename to "kermeta_projects". To get them from Eclipse, you need to know how to configure the CVS repository in Eclipse (use the configuration details from the gforge site as well) (see the tutorial about configuring eclipse for the forge)
In order to correctly compile the source, in additions to the eclipse projects from kermeta_projects you need to retrieves some projects from :
- emfatic_projects (if you don't need to modify kermeta textual syntax, only org.eclipse.gymnast.runtime.core is needed)
- Traceability_projects
- log4j_projects (the *.slf4j)
- utilities_projects
- registration_projects
- devsupport_projects (antlr2)
Way 2:
You can easily obtain the Kermeta source code in your workspace using
a Team Project Set File. You can get the one available *.psf file
to quickly set up a workspace with the Kermeta projects fetched from SVN that you'll need to get started: https://gforge.inria.fr/scm/viewvc.php/trunk/TeamProjectSets/registered_users/?root=kermeta
Getone of the psf file corresponding to your need (connection kind, minimal or full kermeta)
If your web browser save these files with a *.html, *.htm, *.xml extension, you should replace it by hand by *.psf.
From File > Import/Export... simply select 'Team Project Set' from
the Import list, navigate to the file, and you're done.
With https conenction type, you need to use "anonsvn" as user name and password or your GForge login and password during the check out of the plugins.
With svn+ssh connection type, you need to use your login and your ssh private key. (see the Gforge FAQ for how setting up ssh key)
Compile your kermeta installation
Once, checked out, the source might not directly compile
you need to do some more steps :
- in the project org.antlr.antlr2, run the unjar_build.xml ant script, and refresh the project
- in the project org.kermeta.slf4j.eclise, run the unjar_build.xml ant script, and refresh the project
Modify and run the Kermeta platform via the runtime workbench (Run... > Eclipse Application)
Run your new Kermeta platform:
1. you must create a "Run configuration" (eclipse toolbar "Run ...") of kind of "Eclipse Application".
2. run this configuration
Note: that is recommended to increase the allocation of the JVM memory througth the Eclipse preferences like that: -Xmx256M
2. in the "Plug-ins" tab you must click on the radio button named "Choose plug-ins and fragments to launch from the list"
3. click on the checkbox in front of the plug-in named "fr.irisa.triskell.kermeta.model" to unselect it4. run this configuration)
Modify Kermeta:
Each time you modify the java code in any of the projects fr.irisa.triskell.kermeta.io or .interpreter or .model, you need to recompile them before launching Kermeta platform in a runtime workbench, as explained in the above paragraph, since all the kermeta plugins/projects are related to each other through those .jars.
Modify the framework:
When you modify the framework we must regenerate it thanks to the ANT file: dist_n_deploy_build.xml:
- set the location parameter from the eclipse.home property in the ANT file: dist_n_deploy_build.xml from the project: fr.irisa.triskell.kermeta.framework
- set parameters in the uri.map file from the project: fr.irisa.triskell.kermeta.io
- run the previous ANT file: dist_n_deploy_build.xml
- refresh the project: fr.irisa.triskell.kermeta.io
The framework is also generated and deployed in your workspace !
The following instructions are deprecated
Configure the Eclipse workspace and prepare kermeta projects
Once
you have checked out the projects in Eclipse, a few configuration
actions will be necessary to make your projects compile correctly.
Getting EMF libraries
So, first, you need to get the EMF libraries, in order to link each Kermeta project to them.
1. One way to proceed is this one :
- Go to the project fr.irisa.triskell.kermeta.model, and then to the conf directory.
- Get and open the xml file “emf_libraries_linux.user_librairies” or "emf_libraries_windows.user_libraries" according to your OS; modify the paths where the required ecore libraries are located (the directory of the eclipse plugin is specific to your initial installation of eclipse):
<archive path="/local/Programs/eclipse-3.1.1/plugins/org.eclipse.emf.common_2.1.0.jar"/>
- Once you've done that, go to the Window menu > Preferences > Java > Build path > User libraries
- Click on the Import button and then browse your file system to get your customized emf_libraries_<OS>.user_libraries
2. You can also do it using the Eclipse user interface :
- Go to Windows menu > Preferences > Java > Build path > User libraries
- Create a new (New... button) library and call it "emf_libraries"
- Select Add Jars... button, and browse your Eclipse installation directory to get and add, successively, in plugins folder :
- org.eclipse.emf_<version_number>.jar
- org.eclipse.emf.common_<version_number>.jar
- org.eclipse.emf.ecore_<version_number>.jar
- org.eclipse.emf.ecore.xmi_<version_number>.jar
N.B.: After that, if the label "(unbound)" appears close to an emf_libraries, then you must check its configuration like that: right-click on the emf_libraries > Configure ... > You must click on the checkbox in front of the emf_libraries. You must make this operation for all packages that need of the emf_libraries.
Getting ThirdParty libraries
Our Kermeta projects have a few other dependencies with libraries, that you will find in the fr.irisa.triskell.kermeta project and in the fr.irisa.triskell.kermeta.framework project, in lib/thirdparty/ directory. Mainly, you will need to get from this place :
- junit.jar (JUnit 3.8.1) to be able to run the test suites located in the kermeta projects.
- log4j.jar, used to display verbose messages in runtime-workbench mode.
Compile the Kermeta projects
To be sure that Eclipse will be able to run properly the
Kermeta plugins with a new runtime workbench (Eclipse application), you
should also recompile and refresh all your projects.
- Each Kermeta project -- except the model project, unless you have to modify Kermeta metamodel -- has to be compiled and archived in a specific order -- because they are interdependent --, which is:
- fr.irisa.triskell.kermeta.io
- fr.irisa.triskell.kermeta.interpreter
- fr.irisa.triskell.kermeta.framework
- To compile each project, you have to launch the ant files called deploy_n_build.xml (sometimes called dist_n_deploy_build.xml) and located in all the Kermeta projects that you got from the cvs : it will recompile, archive and copy all the .jars of the projects where needed.
- The source recompilation should be done automatically if you configured your eclipse accordingly - Build Automatically/Refresh options in the preferences).
- After
that, you might also update your plugin classpaths, since Eclipse
sometimes does not do it automatically, and in that case it sometimes
leads to misconfigured plugins. To do so, you have to select any of
your plugin.xml file, right click PDE Tools > Update ClassPath...
and select the necessay plugins of Kermeta to update (namely,
fr.irisa.triskell.kermeta, fr.irisa.triskell.kermeta.runner,
fr.irisa.triskell.kermeta.texteditor). If errors appear, than, maybe
the plugins need a little update....
- Particular cases:
- for the project fr.irisa.triskell.kermeta.model : normally, you don't have to modify it and to recompile/archive it. But in specific cases, if you need to recompile this project because you made modifications on the kermeta metamodel, please read the readme.txt file to build correctly this project.