VIATRA/UserDocumentation/Build

Maven integration

Version 0.8.0 of EMF-IncQuery supports building IncQuery projects in a Maven-based builds by generating the pattern matcher code from the eiq files.

Known limitations:

• bug 434794 - Code generation for integration components (e.g. validation framework, derived features) is not supported.
• The EMF-IncQuery project is not available from Maven Central, only from repo.eclipse.org.
• There is no maven archetype support: it is not possible to generate an eclipse-less project automatically, that works with IncQuery. However, manually created projects can be built with the existing compiler.

Repository

Maven components are available from the Eclipse maven repository with the following url: https://repo.eclipse.org/content/groups/emf-incquery/

It includes both snapshot and release versions.

The following three maven-projects should be used:

1. org.eclipse.incquery:incquery-runtime - dependency for the IncQuery runtime, without support for generic API
2. org.eclipse.incquery:incquery-maven-plugin - Maven code generator
3. org.eclipse.incquery:incquery-patternlanguage - dependency for the IncQuery with support for generic API (requires many more dependencies - only use if required)

To use IncQuery features, add the repository and the required dependencies to your Maven project:

<!-- use this in your project's pom.xml file -->
<properties>
	<incquery.version>Set your IncQuery version here</incquery.version>
</properties>
 
<dependencies>
	<dependency>
		<groupId>org.eclipse.incquery</groupId>
		<artifactId>incquery-runtime</artifactId>
		<version>${incquery.version}</version>
	</dependency>
 
	<dependency>
		<groupId>org.eclipse.incquery</groupId>
		<artifactId>incquery-maven-plugin</artifactId>
		<version>${incquery.version}</version>
	</dependency>
 
	<!-- requires many more dependencies - only use if required -->
	<dependency>
		<groupId>org.eclipse.incquery</groupId>
		<artifactId>incquery-patternlanguage</artifactId>
		<version>${incquery.version}</version>
	</dependency>
</dependencies>
 
<repositories>
	<repository>
		<id>incquery</id>
		<url>https://repo.eclipse.org/content/groups/emf-incquery/</url>
	</repository>
</repositories>

incquery-maven-plugin

The maven plugin requires information from the used EMF packages and additionally the EMF packages should be able loaded as well. For this reason, it is important to add references to EPackages and Genmodels together with the corresponding dependencies.

Additional notes

• Package reference is added either by file path (usually relative) to the .genmodel file or fully qualified name of the Ecore Package class that is available on the classpath. Note that if the class is in the same plugin as the query file, the class based reference will not work as compilation will happen at a later build phase than the generation.
• Each package that is imported or is used by any imported package must be listed in the metamodels section.
• Dependencies are transitive, so you don't need to specify all dependencies in all POM.XML files. Note that in some cases you need to add extra dependencies with specific versions (e.g. emf.core) if your genmodel requires a higher version than what is provided by the incquery-maven-plugin.

Example POM.XML

Example generator (based on school example):

<!-- Using maven-clean-plugin to remove previously generated code -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-clean-plugin</artifactId>
  <version>2.5</version>
  <executions>
    <execution>
      <phase>clean</phase>
      <goals>
        <goal>clean</goal>
      </goals>
      <configuration>
        <filesets>
          <fileset>
            <!-- Generated code folder -->
            <directory>src-gen</directory>
            <includes>
              <include>**/*</include>
            </includes>
          </fileset>
        </filesets>
      </configuration>
    </execution>
  </executions>
</plugin>
<!-- Setting up generator -->
<plugin>
  <groupId>org.eclipse.incquery</groupId>
  <artifactId>incquery-maven-plugin</artifactId>
  <version>0.8.0</version>
  <!-- Binding execution to the code generation lifecycle phase -->
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <!-- Output directory - required -->
    <outputDirectory>src-gen</outputDirectory>
      <metamodels>
        <metamodel>
          <!-- Java class for the EMF EPackage - use this if generated EMF code is in the classpath -->
          <packageClass>school.SchoolPackage</packageClass>
          <!-- genmodel file used for generating the EMF model classes - use this if EMF model is in the same project -->
          <!-- <genmodelUri>../school/model/school.genmodel</genmodelUri> -->
        </metamodel>
      </metamodels>
  </configuration>
  <dependencies>
    <!-- Dependency required for the school project (that contains the generated EPackage) -->
    <dependency>
      <groupId>org.eclipse.incquery</groupId>
      <artifactId>school</artifactId>
      <version>0.8.0</version>
    </dependency>
  </dependencies>
</plugin>

Troubleshooting

If you encounter the following error:

ERROR:Cyclic linking detected : PatternCall.patternRef->PatternCall.patternRef

you need to rename your .eiq files so that the files that call patterns from other files should have names lexicographically greater than the referenced files. Example:

// _0_util.eiq

pattern utilityPattern(...) {
  ...
}

// _1_logic.eiq

pattern myPattern(...) {
  find utilityPattern(...);
}