The Xtext generator

Xtext uses the MWE2 (Modeling Workflow Engine 2) DSL to configure the generation of its artifacts. The generated .mwe2 file already comes with good defaults; thus, for the moment, we will not modify it. However, it is interesting to know that by tweaking this file we can request the Xtext generator to generate support for additional features, as we will see later in this book.

Note

In order to deal with additional platforms besides Eclipse, such as IntelliJ and Web editors (Chapter 11 , Continuous Integration), in Xtext 2.9, a brand new generator infrastructure has been introduced, which also aims at simplifying the overall configuration of the generated artifacts. This new generator is completely different from the old one. However, the old generator is still present in Xtext so that projects created before Xtext 2.9 still work and do not need to migrate to the new generator immediately. This book will always use the new generator.

During the MWE2 workflow execution, Xtext will generate artifacts related to the UI editor for your DSL, but most important of all, it will derive an ANTLR specification from the Xtext grammar with all the actions to create the AST while parsing. The classes for the nodes of the AST will be generated using the EMF framework (as explained in the next section).

The generator must be run after every modification to the grammar (the .xtext file). The whole generator infrastructure relies on the Generation Gap Pattern (Vlissides 1996). Indeed, code generators are fine, but when you have to customize the generated code, subsequent generations may overwrite your customizations. The Generation Gap Pattern deals with this problem by separating the code that is generated (and can be overwritten) from the code that you can customize (without the risk of being overwritten). In Xtext, the generated code is placed in the source folder src-gen (this holds for all the Xtext projects). What is inside that source folder should never be modified, since on the next generation it will be deleted and rewritten. The programmer can instead safely modify everything in the source folder src. On the first generation, Xtext will also generate a few stub classes in the source folder src to help the programmer with a starting point. These classes are never regenerated and can thus safely be edited without the risk of being overwritten by the generator. Some stub classes inherit from default classes from the Xtext library, while other stub classes inherit from classes that are in src-gen.

Most generated stub classes in the src folder are Xtend classes. The Xtend programming language will be introduced in the next chapter, thus, for the moment, we will not look at these stub classes.

There is one exception to the previously described generation strategy, which concerns the plugin.xml file (in the runtime and in the UI plugins); further Xtext generations will generate the file plugin.xml_gen in the root directory of your projects. It is up to you to check whether something has changed by comparing it with plugin.xml. In that case, you should manually merge the differences. This can be easily done using Eclipse: select the two files, right-click on them, and navigate to Compare With | Each Other, as illustrated in the following screenshot:

In general, checking the differences between plugin.xml and plugin.xml_gen is only needed either when you have modified the .mwe2 file or when you are using a new version of Xtext, which can introduce new features. If you add something to the plugin.xml file, in order to facilitate the comparison, it is best practice to append your custom additions to the end of the file.

Finally, after running the MWE2 workflow, since the grammar has changed, new classes can be introduced or some existing classes can be modified. Thus, it is necessary to restart the other Eclipse instance where you are testing your editor.