Real Xtext FAQs

[ArneDeutsch]

I always thought a good FAQ document might reduce burden to answer the same questions over and over again, but it was to cumbersome to write it. The following document is created by AI crawling the web for most often asked questions and creating an FAQ from it (and some review/refinement/correction rounds afterwards). I think it is quite helpful and might reduce burden for answering the same questions again and again. Do you think there is a place in the repo for that? Quality high enough? Maybe as replacement or in addition to the existing FAQ? Or maybe directly linked from the front page of the repo?

---

Xtext Developers’ Comprehensive FAQ

This document collects practical questions and answers about common issues encountered when developing DSL applications with Xtext.

---

1. Cross‑Reference Resolution Problems

Q1.1: Why do my cross‑references show errors like “Couldn't resolve reference to …” in my DSL file?

Solution: By default Xtext uses the feature named name when resolving cross‑references. If your DSL elements use a different identifier (for example, an attribute called isbn or id), the default qualified name provider won’t find them. You have two options:

Option A: Change your grammar so that the identifier is called “name.” For example:

grammar org.example.library.Library with org.eclipse.xtext.common.Terminals

generate library "http://www.example.org/library/Library"

Library:
    books+=Book*;

Book:
    'Book' name=ID title=STRING ('sequelof' sequelof=[Book])?
;

Option B: Implement a custom qualified name provider that uses your desired attribute. For example, if you want to use the isbn field:

Grammar snippet (unchanged):

grammar org.example.library.Library with org.eclipse.xtext.common.Terminals

generate library "http://www.example.org/library/Library"

Library:
    books+=Book*;

Book:
    'Book' isbn=ID title=STRING ('sequelof' sequelof=[Book])?
;

Custom provider in Java:

package org.example.library;

import org.eclipse.xtext.naming.DefaultDeclarativeQualifiedNameProvider;
import org.eclipse.xtext.naming.QualifiedName;

public class LibraryQualifiedNameProvider extends DefaultDeclarativeQualifiedNameProvider {
    QualifiedName qualifiedName(Book book) {
        // Use the ISBN attribute for cross-reference resolution.
        return QualifiedName.create(book.getIsbn());
    }
}

Binding in your runtime module:

public Class<? extends IQualifiedNameProvider> bindIQualifiedNameProvider() {
    return LibraryQualifiedNameProvider.class;
}

---

Q1.2: How do I support fully qualified cross‑references that span multiple files?

Solution: For DSLs that have a package declaration, compute the qualified name by combining the package and element name. For example:

Grammar:

grammar org.example.multi.MultiDSL with org.eclipse.xtext.common.Terminals

generate multiDSL "http://www.example.org/multi/MultiDSL"

Model:
    packageDecl=PackageDecl
    elements+=Element*;

PackageDecl:
    'package' name=FQN;

FQN:
    ID ('.' ID)*;

Element:
    'elem' name=ID;

Custom qualified name provider:

package org.example.multi;

import org.eclipse.xtext.naming.DefaultDeclarativeQualifiedNameProvider;
import org.eclipse.xtext.naming.QualifiedName;
import org.eclipse.emf.ecore.util.EcoreUtil2;

public class MultiDSLQualifiedNameProvider extends DefaultDeclarativeQualifiedNameProvider {
    QualifiedName qualifiedName(Element elem) {
        Model model = EcoreUtil2.getContainerOfType(elem, Model.class);
        String pkgName = model.getPackageDecl().getName();
        String[] segments = pkgName.split("\\.");
        return QualifiedName.create(segments).append(elem.getName());
    }
}

Bind this provider in your module as shown in Q1.1.

---

Q1.3: What if my element needs to use a combination of properties for its name?

Solution: In your custom provider you can concatenate several attributes. For example, if an element should be named by its “package” and “id”:

public QualifiedName qualifiedName(MyElement elem) {
    String pkg = (elem.getPackage() != null) ? elem.getPackage() : "";
    String id = elem.getId();
    // Split the package name into segments and append the id.
    return QualifiedName.create(pkg.split("\\.")).append(id);
}

---

2. Maven/Tycho Build and Dependency Issues

Q2.1: My Maven/Tycho build fails because of conflicting JDT (and related) dependency versions. How do I fix this?

Solution: Xtext’s transitive dependencies can bring in conflicting versions. The recommended solution is to force the correct versions via your build configuration. For example, in your Maven POM you can force the desired versions of JDT and related bundles by adding explicit dependency entries in your plugin configuration:

<plugin>
  <groupId>org.eclipse.xtext</groupId>
  <artifactId>xtext-maven-plugin</artifactId>
  <version>${xtext.version}</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
  <dependencies>
    <!-- Force the correct JDT core version -->
    <dependency>
      <groupId>org.eclipse.jdt</groupId>
      <artifactId>org.eclipse.jdt.core</artifactId>
      <version>3.26.0</version>
    </dependency>
    <!-- Force the matching JDT compiler APT -->
    <dependency>
      <groupId>org.eclipse.jdt</groupId>
      <artifactId>org.eclipse.jdt.compiler.apt</artifactId>
      <version>1.3.1300</version>
    </dependency>
  </dependencies>
</plugin>

In Tycho builds you may also add these as extra requirements in your target platform configuration.

---

Q2.2: I get “UnsupportedClassVersionError” (for example, with OperationCanceledException). What do I do?

Solution: This error indicates that some dependency was compiled for a newer Java version than your runtime supports. Ensure that your entire build environment (including your target platform and dependencies) is set to use a consistent Java version. Either upgrade your JDK or adjust your build configuration so that all components (especially transitive ones) are built with the same JDK level.

---

3. Code Generation and Language Choice

Q3.1: Why do new Xtext projects generate Java classes instead of Xtend classes?

Solution: Starting with Xtext 2.20, the “New Project” wizard was updated to generate Java code by default. The rationale is to use Xtend only where its extra features (template expressions, extension methods) add significant value—typically in code generators and unit tests—while keeping the generated skeleton in Java for broader compatibility.
Workaround: If you prefer to generate Xtend stubs, modify your MWE2 workflow’s configuration to set the preferXtendStubs to true

MWE2 example snippet:

Workflow {
    component = XtextGenerator {
        configuration = {
            code = {
                preferXtendStubs = "true"
                fileHeader = "/* generated by Xtext */"
            }
        }
        language = StandardLanguage {
            name = "org.example.mydsl.MyDsl"
            fileExtensions = "mydsl"
        }
    }
}

---

4. Grammar Ambiguity and Left‑Recursion Issues

Q4.1: How do I eliminate left recursion in my expression grammar?

Solution: Left recursion is not supported by the ANTLR3 backend used by Xtext. Rewrite your grammar using left‑factoring. For example, if you have a rule like:

Expression:
    Expression '+' Expression |
    '(' Expression ')' |
    INT;

rewrite it as:

Expression:
    TerminalExpression ('+' TerminalExpression)*;

TerminalExpression:
    '(' Expression ')' |
    INT;

---

Q4.2: How do I resolve ambiguity when two alternatives share a common prefix?

Solution: When alternatives (for instance, a bit‑slicing expression and a collection access) both start with the same token (e.g. '['), refactor the rule by left‑factoring. For example:

Before (ambiguous):

FieldOperationExpression returns Expression:
    UnaryExpression (('[' Expression ']') | ('[' Expression ':' Expression ']') | ('.' ID '(' (Expression (',' Expression)*)? ')'))*;

After (left‑factored):

FieldOperationExpression returns Expression:
    UnaryExpression ( '[' Expression ( (']') | (':' Expression ']') ) 
    | ('.' ID ( '(' (Expression (',' Expression)*)? ')' )? )
    )*;

This forces the parser to decide on the alternative after the common token is consumed.

---

5. Editor, Incremental Parsing, and Partial Parsing Issues

Q5.1: My editor sometimes throws a ClassCastException during incremental parsing. What can I do?

Solution: This typically happens when the partial re‑parsing (used for incremental updates) does not correctly re‑link the AST. A workaround is to override the partial parser helper to catch the error and log a more descriptive message. For example:

Custom Partial Parsing Helper:

package org.example.mydsl;

import org.eclipse.xtext.parser.impl.PartialParsingHelper;

public class MyPartialParsingHelper extends PartialParsingHelper {
    @Override
    public IParseResult reparse(IParser parser, IParseResult previousParseResult, ReplaceRegion changedRegion) {
        try {
            return super.reparse(parser, previousParseResult, changedRegion);
        } catch (ClassCastException e) {
            throw new IllegalStateException("Partial parsing failed. Ensure that parent links are updated correctly.", e);
        }
    }
}

Bind the helper in your runtime module:

public Class<?> bindPartialParsingHelper() {
    return MyPartialParsingHelper.class;
}

---

Q5.2: How can I disable incremental parsing if it is causing too many problems?

Solution:
While not ideal (because it may slow down editing), you can disable incremental (partial) parsing:

Override the Binding:
You can override the binding for the partial parser helper in your UI module with a helper that always triggers a full reparse. For example:

Custom Full Parsing Helper Example:

package org.example.mydsl.ui;

import org.eclipse.xtext.parser.impl.PartialParsingHelper;
import org.eclipse.xtext.parser.IParseResult;
import org.eclipse.xtext.parser.IParser;
import org.eclipse.xtext.resource.ReplaceRegion;

public class FullParsingHelper extends PartialParsingHelper {
    @Override
    public IParseResult reparse(IParser parser, IParseResult previousParseResult, ReplaceRegion cr) {
        // Instead of performing a partial parse, perform a full parse.
        return fullyReparse(parser, previousParseResult, replaceRegion);
    }
}

Bind this helper in your UI module:

public Class<?> bindPartialParsingHelper() {
    return FullParsingHelper.class;
}

---

6. UI Test and Project Synchronization Issues

Q6.1: My UI tests (e.g. content assist, build synchronization) are flaky. How do I improve their stability?

Solution: Flakiness is usually due to timing issues such as workspace builds not finishing before tests start. To address this:

• Ensure complete builds: In your test setup code, force a workspace refresh and wait for the build to finish.

  Example in Java (Eclipse):

  IWorkspace workspace = ResourcesPlugin.getWorkspace();
  workspace.getRoot().refreshLocal(IResource.DEPTH_INFINITE, new NullProgressMonitor());
  // Optionally, poll until there are no build markers.

• Increase test retries: Configure your test runner (Maven Surefire or Tycho Surefire) to re-run failing tests:

  <configuration>
      <rerunFailingTestsCount>3</rerunFailingTestsCount>
  </configuration>

• Prefer pre‑imported projects: Instead of creating projects programmatically in tests, import fully configured project files.

---

7. Gradle and Plugin-Classpath Issues

Q7.1: I get a ClassNotFoundException (for example, for com.google.common.collect.Lists) when synchronizing Gradle projects.

Solution: This indicates that the Gradle build’s classpath is missing required libraries. Make sure your build file explicitly declares Guava and any other needed libraries.

Example Gradle build snippet:

plugins {
    id "org.eclipse.xtext" version "${xtextVersion}"
}

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.google.guava:guava:22.0" // or a version managed by the BOM (see Q10)
    // add other Xtext-related dependencies as needed
}

Also, clear your Gradle cache if version conflicts persist.

---

8. Inner Classes and Naming Issues

Q8.1: My generated code refers to inner classes (like a “Creator” inner class) but the references aren’t resolving.

Solution: When referring to inner classes, you must use the Java “$” notation in your qualified names. For instance, if your JvmModelInferrer generates an inner class for an element “Foo,” then instead of writing:

typeRef(Foo + "Creator")

use:

typeRef("com.example.Model$" + Foo + "Creator")

Example snippet from an inferrer:

members += element.toClass(expression.getName() + "Creator") [
    static = false,
    visibility = JvmVisibility.PUBLIC,
    members += element.toMethod("create", typeRef("com.example.Model$" + expression.getName())) [
        // method body here
    ]
]

---

9. Plugin XML and Manifest Issues

Q9.1: My build reports errors related to plugin.xml (e.g. “offending plugin.xml …” errors due to missing manifest entries).

Solution: Such errors often occur when a plug‑in (especially in test fragments) lacks a proper manifest. To fix this, either add a minimal MANIFEST.MF file or modify the plugin.xml’s root element. For example, in your plugin.xml, add an “id” attribute:

<plugin id="org.example.tests" version="1.0.0">
    <!-- plugin extensions and configuration -->
</plugin>

Or create a MANIFEST.MF with minimal headers:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-SymbolicName: org.example.tests
Bundle-Version: 1.0.0

This makes the plug‑in recognizable by the build tools.

---

10. Dependency Management and the Xtext BOM

Q10.1: Do I need to specify dependency versions when using Xtext, or does Xtext provide its own BOM?

Solution: Xtext comes with its own Maven Bill of Materials (BOM) that centrally manages all third‑party dependency versions (such as Eclipse Platform, EMF, Guava, etc.). When you import the Xtext BOM into your project’s <dependencyManagement> section, you do not have to specify explicit versions for those dependencies. For example:

Maven Usage:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.eclipse.xtext</groupId>
      <artifactId>xtext-dev-bom</artifactId>
      <version>${xtext.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <!-- No version needed because it’s managed by the BOM -->
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-api</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

Gradle Usage:

dependencies {
    implementation platform("org.eclipse.xtext:xtext-dev-bom:${xtextVersion}")
    testImplementation 'org.junit.jupiter:junit-jupiter-api'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'
}

In these configurations, the versions for Xtext and related third‑party libraries are controlled by the BOM. This greatly simplifies maintenance.

---

Q10.2: What if I need to override a dependency managed by the BOM?

Solution: Although the BOM ensures that all Xtext-related dependencies are consistent, you might occasionally want to override a version. In Maven you can override a dependency’s version in your project’s <dependencyManagement> section after importing the BOM, like this:

<dependencyManagement>
  <dependencies>
    <!-- Import the Xtext BOM -->
    <dependency>
      <groupId>org.eclipse.xtext</groupId>
      <artifactId>xtext-dev-bom</artifactId>
      <version>${xtext.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
    <!-- Override a specific dependency -->
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>22.0</version>
    </dependency>
  </dependencies>
</dependencyManagement>

In Gradle, you can force a version by using the resolutionStrategy:

configurations.all {
    resolutionStrategy {
        force 'com.google.guava:guava:22.0'
    }
}

This lets you override the version provided by the BOM if necessary.

---

Q10.3: Do I need to list dependencies for Xtext client projects when using the BOM?

Solution: No. When your project imports the Xtext BOM, all the dependencies managed by the BOM (for example, for the Eclipse platform, EMF, Guava, etc.) will be automatically used. Clients only need to declare the dependencies they actually use, without specifying versions for those that are managed by the BOM.

---

11. Additional Tips and Best Practices

Q11.1: How can I minimize maintenance effort for dependency versions across my Xtext projects?

Solution:

• Use the Xtext BOM: Always import the Xtext BOM in your parent POM (or Gradle build) so that dependency versions are centrally managed.
• Avoid hardcoding versions: In generated project POMs (for example, those produced by the New Project Wizard), remove explicit version declarations for libraries that are managed by the BOM.
• Upgrade in one place: When updating to a new version of Xtext, simply update the BOM version in your dependency management section. All managed dependencies will update automatically.
• Override only when necessary: If a transitive dependency causes issues, override it as shown in Q10.2.

Q11.2: Are there any special considerations for using Xtext in large projects?

Solution:

• Workspace Synchronization: Ensure that large projects are fully built and synchronized before triggering incremental builds or UI tests (see Q6).
• Memory settings: For very large DSLs or numerous files, consider increasing the JVM heap size for Eclipse or your build tool.
• Performance Testing: Use Xtext’s built-in performance logging (and possibly a custom extension of the IFileSystemAccess2) to monitor code generation times.
• Modularization: Break your DSL into multiple modules if the grammar or generated model becomes too large. This helps both with performance and maintainability.

[LorenzoBettini]

That's interesting! Maybe at the top of this repo would be a good place (and linked in the README).
However, we should carefully check the contents... I only gave it a quick look and at least a few answers are not complete, and thus wrong...