Get started with Xtext and Eclipse in 5 Minutes


With this post I'll demo the creation of a new Xtext project in Eclipse. I'll show you how to compile and start editors tailored to your languages for testing. Xtext offers the creation of such language-specific editors for the Eclipse platform, the IntelliJ IDEA platform, as well as for web browsers.

Before we get started, make sure you have Eclipse Xtext properly installed. You may install Xtext via one of our  sites or the Eclipse Market Place into your existing Eclipse IDE, and continue here. If you’re interested in Xtext’s IntelliJ IDEA or web support you need to install Buildship, too, which is available via the Eclipse Marketplace, as well.

After launching the Eclipse IDE you will be asked for a workspace directory, into which all the files and settings will be stored. You can start with the default proposal.

FiveMinTutorial_Workspace.png
Once you confirmed your workspace the IDE will start with a welcome page.

FiveMinTutorial_Welcome.png
Close the welcome page via the cross handle in the Welcome tab in the top left corner of the window, and there you go: This is your IDE.
FiveMinTutorial_PlainIDE.png

Creating a new Xtext project

Now create a new Xtext project by choosing File → New → Project… from the main menu. The dialog offers a couple of different project types. Select New Xtext Project from the category Xtext.
FiveMinTutorial_WizardProjectType.png
FiveMinTutorial_WizardPageNames.png
Keep the project and language names as proposed for the moment and continue via Next.
FiveMinTutorial_WizardPageTargets.png

Feel free to select all of the offered Facets, choose the Gradle build system, and finish the wizard. You will find 9 new projects in your workspace which are mostly empty. The Xtext grammar editor will be opened and show the definition of a very simple Hello World language.
FiveMinTutorial_FreshProject.png
The only thing this language allows is to write down a list of greetings. The following would be proper input:
  Hello Xtext!
  Hello World!

Generating the language infrastructure

In order to test drive this language, you will have to generate the respective language infrastructure. Therefore, open the grammar editor’s context menu and hit Run As → Generate Xtext Artifacts. A new Java process will be spawned, the Console view will appear, and afterwards you will find a couple of new files in the projects that were created by the project wizard.
FiveMinTutorial_GenerateXtext.png

Launch your Eclipse-based editor

Let’s give the editor a try. If you select Run As → Eclipse Application from the project’s context menu. A new Eclipse IDE instance will be launched and allows to test drive the editor.
FiveMinTutorial_RunEditor.png
Before you can create a file for the sample language in the test IDE you need to close the welcome page, of course, and create a sample project. Select File → New → Project… and choose a project type of your choice, e.g. Java Project, name it Sample and create a new file in the src folder of the project: From the context menu of the folder choose New → File, call it Sample.mydsl and hit Finish. The newly created editor for your language will open and ask you in a dialog, whether you want to add the Xtext nature to your project, which you should confirm. You can now give the editor a try, e.g. use content assist (Ctrl+Space) to insert the keyword Hello and see how the input is validated immediately.
FiveMinTutorial_EclipseEditor.png

Checkout the IntelliJ IDEA-based editor

The IDEA IDE can be launched by means of the Gradle build system. If you’re using the prepared Full Eclipse IDE, Gradle integration is already available. Otherwise, make sure to have Buildship installed, which is available via the Eclipse Marketplace, for example.

Open the Gradle Tasks view via Window → Show view → Other… → Gradle → Gradle Tasks.
FiveMinTutorial_RunIdea.png
Expand the project org.xtext.example.mydsl.parent and double click on the task named runIdea. A bunch of required components is downloaded first, and after successful compilation an IDEA IDE is launched.
FiveMinTutorialIdea_Welcome.png
Create a new project, e.g., a Java project. You may skip the determination of the SDK to be used and proceed to the prompt of the project name.
FiveMinTutorial_IdeaNewProject.png
Let’s call the project Sample.
FiveMinTutorial_IdeaProjectName.png
Once your project is set up create a plain file named Sample.mydsl in the src folder, and your DSL editor is opened. Enter the example text below, check out the content assist (CTRL/CMD + Space) as well as the live validation offered by the editor.
  Hello Xtext!
  Hello World!

FiveMinTutorialIdea_IdeaEditor.png

Give the Web editor a try

For testing the web editor a local web server needs to be started. That can be launched by means of the Gradle build system. If you’re using the prepared Full Eclipse IDE, Gradle integration is already available. Otherwise, make sure to have Buildship installed, which is available via the Eclipse Marketplace, for example.

Open the Gradle Tasks view via Window → Show view → Other… → Gradle → Gradle Tasks.
FiveMinTutorial_JettyRun.png
Expand the project org.xtext.example.mydsl.parent and double click on the task named jettyRun. A bunch of required components is downloaded first, and after successful compilation a Jetty web server is launched. It is accessible via the URL printed in the Console view.

Open that URL in your favorite browsers, click into the text field, and enter sample text
  Hello Xtext!
  Hello World!

Check out the content assist by hitting Ctrl/Cmd + Space.
 FiveMinTutorial_BrowserEditor.png
To stop the web server click into the Console view of your development IDE and hitenter/return.

Conclusion

In your first five minutes with Xtext, you have learned how to create a valid set of projects for building editors for your DSLs. You have run Xtext’s code generation in order to get a fully working language infrastructure, and finally learned how to test the generated editors.

Next up you should go through the more comprehensive Domain Model Example. It explains the different concepts of the Xtext grammar language and illustrates how to customize various aspects of the language.

 Take Our Xtext Survey

About Xtext-Team

Holger Schill, Karsten Thoms, Christian Dietrich, Arne Deutsch and Sebastian Zarnekow are driving Xtext activities at itemis. They have many years of experience in language engineering and Open Source development and are actively contributing to the development of the Xtext framework. They gather their inspiration from customer projects which use Xtext in a large scale and variety, where they are actively involved in the development as well as offering professional support services.