Jump to: navigation, search

Difference between revisions of "EMF Compare/User Guide"

(Creating a model)
 
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{EMF_Compare}}
+
This page has moved to http://www.eclipse.org/emf/compare/documentation/latest/user/user-guide.html
  
= Getting Started  =
+
[[Category:EMF Compare/Archive]]
 
+
== Installing EMF Compare  ==
+
 
+
'''Marketplace Client'''
+
 
+
Using the bundled Eclipse marketplace client you can install EMF Compare in one click. Just type "emf compare", click on search, and then on install.
+
 
+
 
+
[[Image:Marketplace.png]]
+
 
+
'''Update Site'''
+
 
+
EMF has been part of the Eclipse release train since Galileo, you can install it using the following update sites, depending on your platform. '''Note''' that the following are not meant to be visited in your internet browser; they must be pasted in the ''Help > Install New Software'' dialog of your Eclipse, as p2 repositories.
+
 
+
  http://download.eclipse.org/releases/galileo
+
  http://download.eclipse.org/releases/helios
+
  http://download.eclipse.org/releases/indigo
+
  http://download.eclipse.org/releases/juno
+
 
+
Please note that the EMF Compare development team does its best to maintain downward compatibility towards Galileo (Eclipse 3.5). Following is the compatibility chart :
+
{| border="1"
+
|-
+
! EMF Compare
+
! Eclipse 3.2 - EMF 2.2
+
! Eclipse 3.3 - EMF 2.3
+
! Eclipse 3.4 - EMF 2.4
+
! Eclipse 3.5 - EMF 2.5
+
! Eclipse 3.6 - EMF 2.6
+
! Eclipse 3.7 - EMF 2.7
+
! Eclipse 3.8 - EMF 2.8
+
|-
+
| 0.7
+
| style="text-align:center; background:green; color:white" | OK
+
|
+
|
+
|
+
|
+
|
+
|
+
|-
+
| 0.8
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|
+
|
+
|
+
|
+
|-
+
| 1.0
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|
+
|
+
|-
+
| 1.1
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|-
+
| 1.2
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|-
+
| 1.3
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|-
+
| bgcolor="#cccccc" | 2.0
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:red; color:white" | KO
+
| style="text-align:center; background:green; color:white" |OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
| style="text-align:center; background:green; color:white" | OK
+
|}
+
 
+
An empty cell indicates that the compatibility hasn't been tested for a particular combination.
+
 
+
== Usage ==
+
 
+
Once installed, you can compare your files (locally or from any Version Control System) as usual using the '''compare with''' menu.
+
 
+
[[Image:EMFC Compare With.png|center]]
+
 
+
=== Sample Use Case ===
+
 
+
With the following, we'll follow the life cycle of a metamodel describing a very basic library as it evolves separately in different branches. This will allow us to give more concrete examples of how EMF Compare can be used, and how it can help you.
+
 
+
==== Creating a model ====
+
 
+
For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations.
+
 
+
The name of our sample project will be "library". It contains a single folder "model" containing two models :
+
* library_Types.uml will contain our primitive types,
+
* library.uml will contain our actual model.
+
 
+
The two models will be commited to our git clone. The whole thing looks like this :
+
 
+
[[Image:EMF Compare Use Setup.png]]
+
 
+
The model itself is a very simple library. Graphically speaking :
+
 
+
[[Image:EMF Compare Use Model.png]]
+
 
+
Now that this initial model file has been committed, we'd like to improve it a little. For example :
+
* Add an ''alias'' property to the ''Writer'' class,
+
* Add a new ''History'' Category,
+
* Rename the ''pages'' property of ''Book'' into ''length''.
+
 
+
Our model now looks like this :
+
 
+
[[Image:EMF Compare Use Model Changed.png]]
+
 
+
But how do we know exactly what changed? Let's compare this with the file from the Git Index :
+
 
+
[[Image:EMF Compare Use Compare 1.png]]
+
 
+
This will open a comparison editor that initially looks like the following :
+
 
+
[[Image:EMF Compare Use Compare 2.png]]
+
 
+
There are three main areas of interest in this editor.
+
# Displays a structured list of the differences detected between the current version of the model and the version that lies in the Git Index.
+
# This will react to the selections in (1) and display the ''left'' side of this comparison. As a rule of thumb, the ''left'' is the ''local'' version of the model. In this example, ''left'' will then be the version we have modified in our workspace. This is originally empty, more on this section in the example just below.
+
# As above, this will react to selections in (1), but this time it will display the ''right'' side of the comparison. This is generally the ''remote'' version of the model; the version to which we've compared ours. In this case, this will represent the version of the model as it is in the Git Index. This is originally empty, more on this section in the example just below.
+
 
+
As stated above, (2) and (3) are initially empty. These two panels are there to display more information about the differences detected between our models. Let's select one of the differences displayed in (1) :
+
 
+
[[Image:EMF Compare Use Compare 3.png]]
+
 
+
# We've selected the difference corresponding to the addition of attribute '''alias''' in the class '''Writer'''. A double-click on this difference updated our two panes below.
+
# '''alias''' has been added to the properties of Class '''Writer'''. In the model, this corresponds to a change to the reference ''ownedAttributes'' of the ''Writer'' Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context.
+
# This displays all values of the reference outlined in (2) as they are in the ''left'' model. This is where we see the new value, '''alias''' outlined.
+
# As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).
+
# This panel displays all values of the reference outlined in (4) as they are in the ''right'' model. In here, we see the location of '''alias''' outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the ''right'' : it is a version located on a repository and is thus non-editable.
+
 
+
This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes.
+
 
+
==== Branching ====
+
 
+
Now, we'd like to create a new feature for our library : we'd like clients to be able to borrow our books. We'll branch our repository in order to create this new feature and name this new branch ''borrowables'' :
+
 
+
[[Image:EMF Compare Use Compare 4.png]]
+
 
+
Starting right away, we add the necessary new concepts to our model to represent the possibility of lending books. We "may" later need to have more than books to be lendable, so let's make a ''Borrowable'' interface to hold this concept. We'll also need a ''Person'' class, as well as a new data type to represent the person's birth date :
+
 
+
[[Image:EMF Compare Use Compare 5.png]]
+
 
+
In a tree viewer, our models now look like (highlighted in red, the concepts we added with this step) :
+
 
+
[[Image:EMF Compare Use Compare 6.png]]
+
 
+
However, while we are working on our ''borrowables'' branch, the ''master'' branch may still evolve : other people on the project might be adding new concepts of their own, or we could be switching to the main branch for a high priority fix ourselves. Let's imagine that two features have been added since we branched our repository. First, someone needed to have the library hold not only Books, but also Magazines. Second, we needed the publication date of our Books and magazines to be recorded.
+
 
+
The first of these two commits will add the following concepts to our ''master'' branch's model :
+
 
+
[[Image:EMF Compare Use Compare 7.png]]
+
 
+
While the second only adds a primitive type and a property :
+
 
+
[[Image:EMF Compare Use Compare 8.png]]
+
 
+
==== Merge ====
+
 
+
If you have followed to this point, we now have two diverging branches, ''master'' and ''borrowables'' which both hold a different version of our ''library.uml'' model. Here is how these two models look like at this point :
+
 
+
{| border="1" cellpadding="5" cellspacing="0" align="center"
+
|-
+
! align="center" | Master
+
! align="center" | Borrowables
+
|-
+
| [[Image:EMF Compare Use Compare Master.png|center]]
+
| [[Image:EMF Compare Use Compare 5.png|center]]
+
|}
+
 
+
== User Interface  ==
+
 
+
The main points of interest are highlighted in the following picture :
+
 
+
[[Image:CompareUI.png|center|EMF Compare's basic user interface]]
+
 
+
# Overview of the differences detected between the given two (or three) models.
+
# First version of the compared models.
+
# Second version of the compared models.
+
# This button will only be visible in the case of three-way comparisons (for example, comparing with a remote repository). It will make a third version of the compared model (the common ancestor of the two others) visible in the interface.
+
# This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.
+
# This button will allow you to filter some differences out of the view according to a set predicate. For example, filtering out all "Additions" or "Moves".
+
# Allows you to merge all non conflicting differences (left to right, or right to left) at once.
+
# Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left).
+
# Allows you to navigate through the detected differences.
+
 
+
= Features =
+
 
+
== Handling Conflicts  ==
+
 
+
PENDING
+
 
+
== Grouping Differences  ==
+
 
+
This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides three distinct grouping strategies :
+
[[Image:EMF Compare Groups Choice.png]]
+
 
+
; Default : Do not try and group differences together, display them as they were detected.
+
[[Image:EMF Compare Groups Default.png]]
+
; By Kind : Group differences by their kind (''additions'', ''deletions'', ''moves'', ''changes'').
+
[[Image:EMF Compare Groups Kind.png]]
+
; By Metaclass : Group difference according to the metaclass of the object on which they were detected.
+
[[Image:EMF Compare Groups Metaclass.png]]
+
 
+
PENDING UPDATE, this is a demo displaying EMF Compare 1.3
+
[http://www.eclipse.org/emf/compare/doc/features/videos/Groups/groups.htm Demo]
+
 
+
PENDING : New grouping strategies can be provided to EMF Compare through extension points.
+
 
+
== Filtering Differences  ==
+
 
+
This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides five distinct filters :
+
[[Image:EMF Compare Filters Choice.png]]
+
 
+
; Changed Elements : Filter out all differences of type '''CHANGE'''. Disabled by default.
+
; Added Elements : Filter out all differences of type '''ADD'''. Disabled by default.
+
; Removed Elements : Filter out all differences of type '''DELETE'''. Disabled by default.
+
; Moved Elements : Filter out all differences of type '''CHANGE'''. Disabled by default.
+
; Resource Mappings : Filter out all resource mappings from the view. Enabled by default.
+
 
+
PENDING UPDATE, this is a demo displaying EMF Compare 1.3
+
[http://www.eclipse.org/emf/compare/doc/features/videos/Filters/filters.htm Demo]
+
 
+
PENDING : New filters can be provided to EMF Compare through extension points.
+
 
+
== Text Attribute Comparison  ==
+
 
+
Differences made into ''String''-typed attributes can be compared and merged directly as text from the compare interface through a simple right-click on the difference.
+
 
+
[[Image:EMF Compare Text Compare.png]]
+
 
+
PENDING UPDATE, this demo displays EMF Compare 1.3
+
[http://www.eclipse.org/emf/compare/doc/features/videos/Text%20compare/textCompare.htm Demo]
+
 
+
== Graphical Comparison  ==
+
 
+
PENDING UPDATE
+
 
+
Since the 1.2 release EMF compare provides the ability to compare models with graphical modelers.
+
 
+
Have a look on the following demos :
+
 
+
[http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html [Demo : Comparing Ecore files with diagrams]]
+
 
+
[[http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html Demo : Comparing UML files with diagrams]]
+
 
+
[[Image:Diag comp diff.png]]
+
 
+
== Logical Model  ==
+
 
+
EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF ''control'' action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a ''genmodel'' file (that depends on its underlying ''ecore'' file) :
+
 
+
[[Image:EMF Compare Logical Compare Action.png]]
+
 
+
EMF Compare will actually consider both files when comparing :
+
 
+
[[Image:EMF Compare Logical Compare Result.png]]
+
 
+
PENDING UPDATE
+
[http://www.eclipse.org/emf/compare/doc/features/videos/LogicalModels/LogicalModels.html Demo]
+
 
+
== UML Specialization  ==
+
 
+
PENDING
+
 
+
[http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm [Demo : Specific support to encapsulate profiles and stereotypes diffs]]
+
 
+
= Other Materials  =
+
 
+
*[http://www.eclipse.org/emf/compare/doc/features/videos/index.html Videos of 2011 new features]
+
*[[EMF Compare/CompareUMLPapyrusAPI|Specification and Documentation about the comparison of UML diagrams]]
+
 
+
[[Category:EMF Compare]]
+

Latest revision as of 10:53, 5 March 2014

This page has moved to http://www.eclipse.org/emf/compare/documentation/latest/user/user-guide.html