Xtext Project Setup

Goal

In this section you will learn

How to create a new XText Project.
How to run you toolchain (editor and parser).
What Project structures are created.
Run a unittest testing the parser.
Optional: How to start a build of your toolchain with maven at the command line

Step 1: Create a new Xtext Project

Follow section "Create A New Xtext Project" in (Xtext 15 Minutes Tutorial).

In addition to the information from the tutorial we suggest the following details for the other examples discussed on this site: model.dot

The result are a set of projects: we are mainly interested in the first project, which contains the grammar.

Step 2: Exploring the new domain model language

The example grammar (automatically created after project initialization) defines a "Model" consisting of "Greetings" is shown in the following. A "Model" contains "Greetings". Every "Greeting" consists of the Text 'Hello' and a name followed by '!' (details below).

grammar org.example.domainmodel.Domainmodel with
                                  org.eclipse.xtext.common.Terminals
generate domainmodel "http://www.example.org/domainmodel/Domainmodel"

Model:
    greetings+=Greeting*;

Greeting:
    'Hello' name=ID '!';

Greeting Meta Model

Notes:

"+=" denotes the owner relationship of one Model containing many Greetings (composition).
"name=ID" defines an attribute "name" of the Rule "Greeting" (allowing to define model elements of the type "Greeting"; attributes of model elements).
The attribute name has a special meaning by default, to denote the identifier of the Rule (identification of model elements).
ID is a terminal (like INT, STRING, etc.; see grammar, and click "F3" on "org.eclipse.xtext.common.Terminals" to see definition). "name=ID" means that the attribute "name" is parsed as "ID" (which in turn is - more or less - an alphanumerical word staring with no number)

Note on version control

When using git or svn make sure not to commit any generated code (e.g. everything under src-gen and xtend-gen). Use, e.g., a .gitignore file like the following:

target
src-gen
xtend-gen
.settings
.metadata
bin
generated

Step 3: Compile and Run the Project

Compile and Run the Project: Without modifing the grammar (or anything else), follow the steps in section "Generate Language Artifacts" in (Xtext 15 Minutes Tutorial).

After this, you can use explore the editor and enter a model according to the example meta model grammar provided by the Xtext project setup.

Now you can play with your new language (type CTRL-Space to get auto completion). Enter the following example:

Hello Pierre!
Hello Tim!
Hello Markus!

Step 5: Add Unittests

In the test project you can add a unittests. Locate the single file in the src folder. This file contains a unittest. Uncomment the test code and run the test.

Note: You need to generate the xtext artifact before (see above).

You may extend the default test code by adding the following:

@Inject extension
ParseHelper<Model> parseHelper
@Inject extension
ValidationTestHelper validationHelper

The you can easily check that no errors occurred while parsing:

package org.xtext.example.mydsl.tests

...

@RunWith(XtextRunner)
@InjectWith(MyDslInjectorProvider)
class MyDslParsingTest {
    @Inject extension
    ParseHelper<Model> parseHelper
    @Inject extension
    ValidationTestHelper validationHelper

    @Test
    def void loadModel() {
        val result = parseHelper.parse('''
            Hello Xtext!
        ''')
        Assert.assertNotNull(result)
        result.assertNoErrors
    }
}

Optional step 5: Build meta model using maven

When maven is selected as build tool, you can also use maven (instead of eclipse) to build your project on the command line: Go to the "parent" project and run "mvn package".

Maven will download all required packages in "~/.m2" (locally) and then build your sub-projects. The output is located in the folder "target" of each sub-project.