Skip to main content
Jump to: navigation, search

Difference between revisions of "EMFIncQuery/DeveloperDocumentation/DevEnvironment"

(Undo revision 401592 by Harmath.incquerylabs.com (talk))
 
(23 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Prerequisites  ==
+
= Setup =
  
*Eclipse Modeling Tools 3.7, 3.8 or 4.2 distribution
+
Choose one of the following options:
**Other Eclipse distributions might work as well, but this contains EMF-related plug-ins
+
**Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.2 Juno)
+
*Xtext and Xtend 2.3
+
**Earlier versions will not work
+
**Currently install 2.3 from <nowiki> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ </nowiki>
+
**Known issue: [https://bugs.eclipse.org/bugs/show_bug.cgi?id=398809 EMF-IncQuery does not work with the upcoming Xtext/Xtend 2.4 version]
+
*EGit (and JGit) - required components for downloading source from Git
+
**Available from Eclipse Juno update site: <nowiki>http://download.eclipse.org/releases/juno </nowiki>
+
**Version 1.1 is not recommended - it often throws exceptions during usage
+
  
== Downloading IncQuery source projects from Git  ==
+
== Manual ==
  
The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select eitherclone URLs listed. However, if you want to use the committer account, you have to use the ssh url.  
+
=== Prerequisites  ===
 +
 
 +
* Eclipse Modeling Tools 3.7, 3.8, 4.2, 4.3, 4.4 or 4.5 distribution
 +
** Other Eclipse distributions might work as well, but this contains EMF-related plug-ins
 +
** Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.4 and 4.5)
 +
* Xtext SDK 2.8
 +
** Xtext update site<nowiki> http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ </nowiki>
 +
** Other versions of Xtext are not supported
 +
** This also requires a current version of EMF (2.10)
 +
* [[Xcore|Xcore SDK]] 1.3
 +
* EGit (and JGit) - required components for downloading source from Git
 +
** Available from Eclipse release train update site: <nowiki>http://download.eclipse.org/releases/mars </nowiki>
 +
 
 +
=== Editor Settings  ===
 +
 
 +
Code style: slightly modified built-in Eclipse style
 +
 
 +
* line width: 120 characters both for code and comments
 +
* using spaces for indentation
 +
 
 +
Downloadable style available from [[Image:IncQueryFormatter.xml.zip]]
 +
 
 +
Comment templates:
 +
* Copyright header for each Java file
 +
* Leaving override annotations out
 +
 
 +
Downloadable template available from [[File:Eiq-jdt-templates.xml.zip]]
 +
 
 +
=== Downloading IncQuery source projects from Git  ===
 +
 
 +
The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url.  
  
 
After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace.  
 
After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace.  
Line 21: Line 42:
  
 
Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address.  
 
Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address.  
 +
 +
== Automatic (Oomph) ==
 +
 +
* Download and run [https://www.eclipse.org/downloads/installer.php Eclipse Installer]
 +
* Product:
 +
** Product: Eclipse IDE for Java Developers
 +
** Product Version: Mars
 +
* Projects:
 +
** Add [http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/plain/releng/org.eclipse.incquery.setup/incquery.setup the setup file]
 +
** Add it to the projects to install
 +
* Variables:
 +
** Target Platform: Mars
 +
 +
= Bootstrapping =
 +
 +
== Generating EMF model code ==
 +
 +
Run the EMF Model code generator on the following:
 +
 +
* ''/org.eclipse.incquery.runtime.rete.recipes/model/rete-recipes.genmodel''
 +
* ''/org.eclipse.incquery.viewers.runtime/model/notation.genmodel''
 +
* ''/org.eclipse.incquery.viewmodel/model/traceability.genmodel''
  
 
== Generating the Editor Components  ==
 
== Generating the Editor Components  ==
Line 26: Line 69:
 
The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is '''not committed into Git'''; they are to generated in the workspace after cloning and after changes of the grammar or workflow files.  
 
The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is '''not committed into Git'''; they are to generated in the workspace after cloning and after changes of the grammar or workflow files.  
  
*The src-gen folders contain code generated by the Xtext code generation workflows.  
+
* The src-gen folders contain code generated by the Xtext code generation workflows.  
*The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.
+
* The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.
  
 
=== Xtext code generation workflows  ===
 
=== Xtext code generation workflows  ===
  
The org.eclipse.incquery.patternlanguage, org.eclipse.incquery.patternlanguage.emf and org.eclipse.incquery.tooling.generator.model projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension). All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows either by selecting Run as/GeneratePatternLanguage.mwe2 from the context menu of the .mwe2.launch file in the corresponding project root. In case of the tooling.generator.model project, you may be required to create the folder "src-gen" manually the first time.
+
The following projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension):
  
All workflow files require about 30-60 seconds to run - be patient.  
+
* ''org.eclipse.incquery.patternlanguage''
 +
* ''org.eclipse.incquery.patternlanguage.emf''
 +
* ''org.eclipse.incquery.tooling.generator.model''
  
'''Important''': In case of fuure language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.<br>
+
All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows by selecting ''Run as/MWE2 Workflow'' from the context menu of the .mwe2 file in the corresponding project. In case of the tooling.generator.model project, you may be required to create the folder ''src-gen'' manually the first time.  
  
=== Xtend code generation  ===
+
All workflow files require about 30-60 seconds to run - be patient.
  
Xtend files are used for code generation and some other reasons in language projects and tests. After the Xtext code generation workflows are executed, it might be required to clean the projects with xtend files, otherwise they do not find the freshly generated java code. (It is the easiest to issue a clean all and then build the entire workspace.)
+
'''Important''': In case of future language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.<br>
 +
 
 +
'''Important''': The workflow of the patternlanguage.emf project might require a large amount of heap/permgen memory. If such issues occur, add extra memory to the workflow using the Run configurations dialog.
  
 
=== Optional dependencies  ===
 
=== Optional dependencies  ===
  
Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the [[GEF/GEF4|GEF4]] version. Alternatively you can just close the projects depending on them (as they are non-essential).
+
Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the [[GEF/GEF4|GEF4]] version. Alternatively you can just close the projects depending on them (as they are non-essential).
 +
 
 +
As the GEF4 Zest component is under heavy refactoring, the extra update site of EMF-IncQuery also contains a Zest version known working with the current version.
 +
 
 +
== Bootstrapping EMF-IncQuery code generation ==
 +
 
 +
Some extensions already include EMF-IncQuery patterns but the generated code is not stored in version control.
 +
In order to correctly compile these addons, you need to start a Runtime Eclipse and import the following projects:
 +
 
 +
* ''org.eclipse.incquery.testing.queries'' (''src/org/eclipse/incquery/testing/queries/matchRecordQueries.eiq''
 +
* ''org.eclipse.incquery.tooling.ui.retevis'' (''src/org/eclipse/incquery/tooling/ui/retevis/ReteVisualization.eiq'')
 +
* ''org.eclipse.incquery.uml'' (''src/org/eclipse/incquery/uml/derivedfeatures/DerivedFeatures.eiq'')
 +
* ''org.eclipse.incquery.viewers.runtime'' (''src/org/eclipse/incquery/viewers/runtime/model/patterns/traceability.eiq'')
 +
* ''org.eclipse.incquery.viewmodel'' (''src/org/eclipse/incquery/viewmodel/traceability/patterns/helpers.eiq'')
 +
 
 +
After importing, the EMF-IncQuery builder should generate the code for each pattern definition as needed.
 +
 
 +
Notes:
 +
* You may have to manually open and edit-save the *.eiq files to trigger the builder.
 +
* You may get exceptions during build if the imported projects are also selected for inclusion in the run configuration.
 +
* Make sure to include the required metamodels either in the run configuration or import them into the runtime workspace as well.
  
 
[[Category:EmfIncQuery]]
 
[[Category:EmfIncQuery]]

Latest revision as of 06:55, 18 February 2016

Setup

Choose one of the following options:

Manual

Prerequisites

  • Eclipse Modeling Tools 3.7, 3.8, 4.2, 4.3, 4.4 or 4.5 distribution
    • Other Eclipse distributions might work as well, but this contains EMF-related plug-ins
    • Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.4 and 4.5)
  • Xtext SDK 2.8
    • Xtext update site http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/
    • Other versions of Xtext are not supported
    • This also requires a current version of EMF (2.10)
  • Xcore SDK 1.3
  • EGit (and JGit) - required components for downloading source from Git
    • Available from Eclipse release train update site: http://download.eclipse.org/releases/mars

Editor Settings

Code style: slightly modified built-in Eclipse style

  • line width: 120 characters both for code and comments
  • using spaces for indentation

Downloadable style available from File:IncQueryFormatter.xml.zip

Comment templates:

  • Copyright header for each Java file
  • Leaving override annotations out

Downloadable template available from File:Eiq-jdt-templates.xml.zip

Downloading IncQuery source projects from Git

The project is available in the from the Eclipse repository at http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/. To download it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url.

After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects under the plugins/ subfolder into your Eclipse workspace.

For details, see the Eclipse EGit help and the Git tutorial from Lars Vogel.

Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address.

Automatic (Oomph)

  • Download and run Eclipse Installer
  • Product:
    • Product: Eclipse IDE for Java Developers
    • Product Version: Mars
  • Projects:
  • Variables:
    • Target Platform: Mars

Bootstrapping

Generating EMF model code

Run the EMF Model code generator on the following:

  • /org.eclipse.incquery.runtime.rete.recipes/model/rete-recipes.genmodel
  • /org.eclipse.incquery.viewers.runtime/model/notation.genmodel
  • /org.eclipse.incquery.viewmodel/model/traceability.genmodel

Generating the Editor Components

The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, all src-gen and xtend-gen folders contain generated code. Generated code is not committed into Git; they are to generated in the workspace after cloning and after changes of the grammar or workflow files.

  • The src-gen folders contain code generated by the Xtext code generation workflows.
  • The xtend-gen files contain code generated from Xtend files. These files do have dependencies of the Xtext workflow-generated files: before the workflow was executed, it is normal for these files to be erroneous.

Xtext code generation workflows

The following projects all contain a code generation workflow file (found in the top-level package in each project, with a mwe2 extension):

  • org.eclipse.incquery.patternlanguage
  • org.eclipse.incquery.patternlanguage.emf
  • org.eclipse.incquery.tooling.generator.model

All workflows need to run to generate the editor and parser code in the workspace: first the core, then the emf, finally the tooling.generator.model workflow needs to be executed. You can run these workflows by selecting Run as/MWE2 Workflow from the context menu of the .mwe2 file in the corresponding project. In case of the tooling.generator.model project, you may be required to create the folder src-gen manually the first time.

All workflow files require about 30-60 seconds to run - be patient.

Important: In case of future language changes, the corresponding languages are to be regenerated. Until that happens, the codebase might or might not have compile errors. However, if the language is not changed, this regeneration step is not necessary.

Important: The workflow of the patternlanguage.emf project might require a large amount of heap/permgen memory. If such issues occur, add extra memory to the workflow using the Run configurations dialog.

Optional dependencies

Zest, GMF and Graphiti are marked as dependencies of optional supplementary components. You can either install GMF and Graphiti from the Juno update site, while Zest uses the GEF4 version. Alternatively you can just close the projects depending on them (as they are non-essential).

As the GEF4 Zest component is under heavy refactoring, the extra update site of EMF-IncQuery also contains a Zest version known working with the current version.

Bootstrapping EMF-IncQuery code generation

Some extensions already include EMF-IncQuery patterns but the generated code is not stored in version control. In order to correctly compile these addons, you need to start a Runtime Eclipse and import the following projects:

  • org.eclipse.incquery.testing.queries (src/org/eclipse/incquery/testing/queries/matchRecordQueries.eiq
  • org.eclipse.incquery.tooling.ui.retevis (src/org/eclipse/incquery/tooling/ui/retevis/ReteVisualization.eiq)
  • org.eclipse.incquery.uml (src/org/eclipse/incquery/uml/derivedfeatures/DerivedFeatures.eiq)
  • org.eclipse.incquery.viewers.runtime (src/org/eclipse/incquery/viewers/runtime/model/patterns/traceability.eiq)
  • org.eclipse.incquery.viewmodel (src/org/eclipse/incquery/viewmodel/traceability/patterns/helpers.eiq)

After importing, the EMF-IncQuery builder should generate the code for each pattern definition as needed.

Notes:

  • You may have to manually open and edit-save the *.eiq files to trigger the builder.
  • You may get exceptions during build if the imported projects are also selected for inclusion in the run configuration.
  • Make sure to include the required metamodels either in the run configuration or import them into the runtime workspace as well.

Back to the top