EMF-IncQuery Contributors' Guide

Setting up the EMF-IncQuery Development Environment

Outdated page

This page is now maintained in the Eclipse wiki: http://wiki.eclipse.org/EMFIncQuery/DeveloperDocumentation/DevEnvironment

The rest of the page is preserved here only for archive purposes.

Prerequisites

Downloading IncQuery source projects from Git

The project is available at http://eclipse.org/incquery. To download it, you shoud point your Git client to http://git.eclipse.org/c/incquery/org.eclipse.incquery.git/ and 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.

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.

Xtext code generation workflows

In order to generate editor and parser code, execute the mwe2 code generation workflows by right clicking to the files below, and selecting Run as | MWW2 Workflow  in the following order:

  1. org.eclipse.incquery.patternlanguage/src/org.eclipse.incquery.patternlanguage/GeneratePatternLanguage.mwe2
  2. org.eclipse.incquery.patternlanguage.emf/src/org.eclipse.incquery.patternlanguage.emf/GenerateEMFPatternLanguage.mwe2: Type "y" in the console window to download antlr and finish code generation.
  3. org.eclipse.incquery.tooling.generator.model/src/org.eclipse.incquery.tooling.generator.model/GenerateGeneratorModel.mwe2: Type "y" in the console window to download antlr and finish code generation.

After issuing code generation, Eclipse should warn you about compile errors in the projects. To resolve them (by generating the missing code), click "Proceed". All workflow files require about 30-60 seconds to run - be patient.

Xtend code generation

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

Optional dependencies

Zest and Graphiti are marked as dependencies of optional supplementary components. You can either install these external plug-ins from the Juno update site, or just close the projects depending on them (as they are non-essential).

 

Additional Development Tools

EMF-IncQuery Testers' Guide

Testing framework overview

Check out testing framework related projects from: https://github.com/ujhelyiz/EMF-IncQuery/tree/master/tests
  • org.eclipse.viatra2.emf.incquery.snapshot (+ .edit, .editor): For handling recorded match sets
  • org.eclipse.viatra2.emf.incquery.testing.core: Xtend files for building test cases
  • org.eclipse.viatra2.emf.incquery.testing.queries: EMF-IncQuery queries used by derived features in snapshot files and for comparing actual and expected snapshots
  • org.eclipse.viatra2.emf.incquery.testing.ui: Query Explorer right-click menu contribution for Saving snapshots into .eiqsnapshots files.
Test cases can be defined using the following way (if the test is to check that the match set of queries is equal to the recorded match set):
 
 
For an example test project with the correct settings and a representative set of test definitions, see: https://github.com/ujhelyiz/EMF-IncQuery-Examples/tree/master/school/school.tests
  • Used patterns can be parsed right from text (there are additional methods for loading a pattern model from file or uri as well)
  • Input models are referenced from the recorded match set (there are additional methods for loading input models from file or uri as well)
  • Recorded match sets are loaded from file or uri
  • Two comparing implementations:
    • Use recorded match set as partial matches (reports unexpected and not found matches)
    • Record actual match set and use EMF-IncQuery queries for listing unexpected and not found matches (this comparison method relies on correct behavior of matches on a limited feature set of the pattern language)
  • Short-hand "assert" methods (see above) for the default behavior
  • Additional methods can be suggested/implemented for other common use cases.
  • Test cases can be run as JUnit Plugin Tests (this maybe changed if we register the matcher factory used by the derived feature in the match set record metamodel)

Important to know:

  • EPackages must be registered at the time of the tests, so make sure to have correct dependencies set and include them into the runtime Eclipse.
  • Patterns/input/record models must be accessible from the workspace, so they should be probably put in the same project as the test specification

Step-by-step guide for creating IncQuery Test Cases

  1. You will need an EMF-IncQuery project, which contains an .eiq Query Definition file. Here you can find a working example project: https://github.com/ujhelyiz/EMF-IncQuery-Examples/tree/master/school/school.incquery
    You can create an own EMF-IncQuery project here: File | New | Project | EMF-IncQuery | EMF-IncQuery Project.
  1. You will need a plug-in project (!) which contains an instance model. If this project not a plug-in project, the jUnit Plug-in can’t load the instance model, so the test cases will not run.

    In this example https://github.com/ujhelyiz/EMF-IncQuery-Examples/tree/master/school/school.instancemodel you can find two school instance models with a school, years, classes, students, teachers, and courses.
    If you create a new plug-in project, you don’t need Activator (on the second wizard page, uncheck the „Generate an activator, a Java class that controls the plug-in’s life cycle”).

  1. The test project is an other plug-in project. For an example test project with the correct settings and a representative set of test definitions, see: https://github.com/ujhelyiz/EMF-IncQuery-Examples/tree/master/school/school.tests

    This project contains:

  • school.tests/src/school/tests

The basic and model manipulation test cases in .xtend file

An example model manipulation test, where change the School "Budapest University of Technology and Economics" name to "BME":

  • school.tests/model

Snapshot files

You can create an .eiqsnapshot file in Query Explorer: right click on a pattern result or the root of the patterns - Save EMF-IncQuery snapshot. Important: this file contains relative path to the instance model, so if you move this file to another folder, you need to check the path.

  • school.tests/SchoolTests.launch

JUnit run configurations. You can run the tests: right click  - run as - SchoolTests

 

 

Reflective Editor for eiq Files

As parsing eiq files requires custom components registered during the pattern load process, the built-in Reflective Ecore Editor cannot open eiq files. To overcome this, an Xtext-specific reflective editor is needed. A short description of the reflective editor component is available in the blog post Reflective Tree Editor for Xtext-based Languages. Downloads are available from:

Additionally, the registration of the reflective editor is created in an external project, as it is not planned to distribute this editor together with EMF-IncQuery (and manage its external dependency). For the same reason, the plug-in is only available in source form at Github,

 

EMF-IncQuery Automatic Build Configuration

The EMF-IncQuery build system

EMF-IncQuery uses Maven/Tycho for continous integration builds.

Project structure

Adding a new project to the build

There are two important things to configure for adding a new project to the build:

  1. In order to technically build the project, a build configuration needs to be created (and registered in the root project).
    1. This consists of a single pom.xml file in the project root.
    2. And a module declaration in the parent pom.
  2. Add the created feature to either an existing or a new feature
    1. If an existing feature is used, the feature.xml has to be extended with the id of the new project.
    2. If a new feature is created, this feature is required to be registered both in the root project and in the update projects' category.xml file.
    3. In both cases, don't forget to add the source plugin to the SDK or another Sources feature.

An example commit for executing all these steps (with the creation of a new project) is: https://github.com/ujhelyiz/EMF-IncQuery/commit/4b523260c94ddb2605ce1088... (Note that the addition of a source plugin is not included).

Defining the build configuration for a plug-in project

A project needs to have a pom.xml file in the project root for the build configuration. In most cases, this build configuration is very simple, as all required configurations are inherited either from the project type (Eclipse plug-in project) or the root project. Basically, there are two configuration types used in the project:

  1. Projects with xtend files (e.g. the org.eclipse.viatra2.emf.incquery.tooling.generator project)
  2. Projects without xtend files (e.g. the org.eclipse.viatra2.emf.incquery.base project)

To create such a configuration file for a new project, the recommended solution is to copy an existing corresponding project configuration, and replace the plug-in identifier.

Warning! If a project for any reason uses a different version number then the base IncQuery project (currently 0.7.0.qualifier), it is important to add the version information to the project, replacing '.qualifier' with '-SNAPSHOT' (currently 0.7.0-SNAPSHOT).

Additionally, the new project needs to be added to the parent project (org.eclipse.viatra2.patternlanguage.update):

The pom.xml file contains a module section where a list of submodules are presented - it needs to be extended with a new submodule describing the project location.

Adding the plug-in to an existing feature

The existing feature.xml file has to be extended with the new plug-in as a contained plug-in id.

Additionally, a source plug-in might need to be added to (a possibly different feature). The id of the source plug-in is: «plugin.id».source. The feature.xml editor reports warnings as such projects are non-existent in the project; however they are created during the build and included.

Currently most source plug-ins are added only to the SDK bundle, with the notable exceptions of runtime bundles that are added to the runtime features.

Adding the plug-in to a new feature

Creating a new feature project works similarly to creating a new plug-in project, but the feature builder pom.xml files are more simple. The recommended way of creating a new feature is to copy and existing one, and modifying the identifier, descriptions and contained plug-ins (and possibly features). The feature also needs to be registered into the root projects module section.

Additionally, this feature needs to be added to the update site. For this reason, the feature needs to be registered in the category.xml file stored in the update site project - the category.xml file has a form-based editor.