EMF Compare/Contributor Guide
Developing on EMF Compare requires the use of Eclipse 3.5 (Galileo) at least, though it is possible to use the latest releases as well. It can be obtained through the Eclipse download page. The easiest way to set up your environment is to download the Eclipse Modeling Tools bundle since it will already contain most of our dependencies, except for Guava.
All of the following can be obtained through the simultaneous release's update site. From the Eclipse you've installed, use the Help > Install New Software... menu. In the dialog that pops up, locate the update site of your release (it should be labelled Eclipse <name of release> Repository). The list that loads below will contain the necessary projects that you just have to install.
We'll go through how to obtain them separately.
EMF Compare depends on version 10 of google's Guava library. It can be installed from the Orbit update site. Do note that EMF Compare is not compatible with version 11 or higher of Guava.
EMF Compare heavily relies on EMF and requires version 2.5 at least. We recommend using the SDK so as to have access to the sources as well. Get it from the EMF downloads page.
Checking out the code
EMF Compare is now using the git infrastructure, you should clone the repository:
git clone git://git.eclipse.org/gitroot/emfcompare/org.eclipse.emf.compare.git
EMF Compare is currently undergoing a massive overhaul : the master branch is the future "2.0" version. It does compile, but the code it offers is not fully functional yet. The 1.3 branch however only compiles on a "Juno" (eclipse 3.8/4.2) platform : our papyrus support can no longer be compiled on an inferior target. Yes, that makes for a big mess.
The core of EMF Compare, and the only things you really need to have in your workspace to compile a functional model comparison support, is the following set of plugins for the 1.3 branch.
(o.e.e.c stands for "org.eclipse.emf.compare") :
o.e.e.c o.e.e.c.diff o.e.e.c.diff.edit o.e.e.c.logical o.e.e.c.logical.ui o.e.e.c.match o.e.e.c.ui
The unit tests can also be imported without trouble :
If you need the diagram comparison support, you can import :
o.e.e.c.diagram o.e.e.c.diagram.ecoretools o.e.e.c.diagram.edit o.e.e.c.diagram.ui
The repository is split in two parts :
- plugins which contains the actual product
Depending on what you want to do you might want to import in your workspace only the projects contained in the plugins directory or also the packaging ones.
Developping EMF Compare patches or code
Every new feature or major change should be documented in a short specification, the template is available here
The EMF Compare team uses Checkstyle with its own set of rules in order to have an homogeneous code style throughout the plugins and features.
The Eclipse plugin for Checkstyle can be downloaded on sourceforge. Once installed, it will be automatically applied to all existing EMF Compare plugins as they are already configured to use it. New projects can use the same set of rule :
- Right-click on the project which has to be checked through Checkstyle and select "Properties".
- In the "Checkstyle" category, go to the "Local Checkstyle configuration" tab
- Hit "New" and select "project-relative configuration" from the "type" drop down menu. Set the name of this configuration as you see fit ("EMF Compare" for example) and click the "Open..." button for the localisation.
- Browse to "org.eclipse.emf.compare/codeStyle" and select EMFCompareCheckstyleConfiguration.xml. Select "Ok" twice to end this wizard.
- Go back to the "General" tab, then tick "Activate Checkstyle on this project"
- In the drop-down below, select the configuration you just created, the click OK to close the properties dialog.
- That's it : your project will now go through the EMF Compare Chekstyle rules on each compilation.
Note that Checkstyle errors are not considered fatal compilation errors : you can still run code with checkstyle errors. Nearly each of EMF Compare check is set to report an error though, as we always try and comply to these rules.
At first, most of the checkstyle errors that will be reported will probably be formatting errors : you can configure your formatter to use EMF Compare configuration to avoid these.
- Click on Window => Preferences
- Browse to the "Java => Code Style => Formatter" category and click on the "Import" button
- Browse to the "<workspace>/org.eclipse.emf.compare/codeStyle" directory and select "EMFCompareformatter.xml"
- hit Ok twice to close the preferences dialog
Your formatter will now comply to EMF Compare code style. Hitting ctrl+shift+F in a java editor will format your class to follow this style.
Note that all EMF Compare plugins are already configured to make use of this formatter
EMF Compare is built against Java 1.5 : usage of the JDK 1.6 API will result in build errors and should be avoided.
We try our best to ensure downward compatibility towards Eclipse Europa, as such we use the following as our target platform :
The target platform is added both UML2 and Subversive for maintenance of the examples and the subversive integration feature
The target platform can be set through the preference page accessible via Window => Preferences => Plug-in Development => Target Platform. More information on how to set a target platform for development can be found in the Eclipse help.
The EMF Compare development team uses the target platform augmented with the M6 EMF Compare build to maintain API compatibility. Checks for API breakages and evolutions are set per project and committed alongside them. All of these settings are still soft and don't ensure full API compatibility for now, they will be changed for strict API maintenance as soon as EMF Compare 1.0 is released.