Setting up a RCP product for a Xtext DSL

How can I produce a standalone application with the DSL editor I created? This question pops up sometimes in the forum. I will show you how to set up a rather minimal RCP application that enables using the DSL editor created with Xtext. As an example I take the simple Xtext project that you get when you create Xtext projects with the default settings.

Sources for the example project can be downloaded here.

1. Create the Xtext project

Open the menu File / New / Project / Xtext and select Xtext Project. Click Next and then Finish.

You will get the three projects

  • org.xtext.example.mydsl
  • org.xtext.example.mydsl.generator
  • org.xtext.example.mydsl.ui

2. Create a Plugin Project for your product

  1. Create a new Plug-in project with File / New / Project / Plug-in Development / Plug-in Project and press Next.
  2. Enter the project name “org.xtext.example.mydsl.product” and press Next.
  3. In the Options section deselect “Generate an activator…” and “This plug-in will make contributions to the UI”
  4. Press Finish
  5. Generate the DSL implementation by right-click on the GenerateMyDsl.mwe2 and select Run As / MWE2 Workflow.

3. Create a Feature Project for your DSL

Now we will create a Feature that contains only our DSL specific plugins.

  1. Create a new Feature projectwith File / New / Project / Plug-in Development / Feature Project and press Next.
  2. Give it the name “org.xtext.example.mydsl.feature” and press Finish.
  3. Open the feature.xml and go to the Plug-ins page.
  4. Add your DSL plugins:
    • org.xtext.example.mydsl
    • org.xtext.example.mydsl.generator
    • org.xtext.example.mydsl.product
    • org.xtext.example.mydsl.ui

4. Create a Feature Project for the Runtime

A second feature should bundle all the plugins that are required to get the DSL editor running on the RCP platform. This is indeed the most cumbersome work. What exectly is required in a minimal setup to get the editor working? Your DSL editor might need some more plugins than the ones listed here, but for the minimal Xtext project that comes out of the wizard the following list will give you a good starting point.

Now create another Feature Project “org.xtext.example.mydsl.platform.feature” like above. Add the following plugins:

ATTENTION: Xtext currently requires com.google.collect in a version < 1.0. You might have installed different versions of the plugin in your IDE, and to be sure that the right one will be picked, specify the version of that plugin explicitly. In my environment the version is v201008251220. You can identify the right version if you open the Plugin-Dependencies of the org.xtext.example.mydsl project in the Package Explorer and search for the com.google.collect plugin.

5. Define the org.eclipse.core.runtime.products extension

  1. Open the MANIFEST.MF in org.xtext.example.mydsl.product.
  2. Go to the “Dependencies” page and add org.eclipse.core.runtime as required plugin.
  3. Now go to the Extensions page. Click the “Add…” button and select the org.eclipse.core.runtime.products extension point.
  4. Select the extension and enter ID “product” in the Extension Details
  5. Right-click on the extension and select New / product.
  6. Enter value for application: org.eclipse.ui.ide.workbench
  7. Enter the name property for the product (“MyDSL”)
  8. Right-click on “MyDSL (product)” and select New / property.
  9. Enter name=appName, value=MyDSL in the Extension Element Details.

Go to the “plugin.xml” page. The content should now be:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>

   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.ui.ide.workbench"
            name="MyDSL">
         <property
               name="appName"
               value="MyDSL">
         </property>
      </product>
   </extension>

</plugin>

6. Create the Product Configuration

In the org.xtext.example.mydsl.product project create a new Product Configuration file “MyDSL.product” (File / New / Plug-in Development / Product Configuration).

Open the MyDSL.product file. On the Overview page do:

  1. set name “MyDSL”
  2. select Product org.xtext.example.mydsl.product.product
  3. select Application org.eclipse.ui.ide.workbench
  4. select “The product conifguration is based : features

Go to the Dependencies page and add the both features

  • org.xtext.example.mydsl.feature
  • org.xtext.example.mydsl.platform.feature

7. Starting the product for testing

On the Overview page you can directly start the product by clicking on the link “Launch an Eclipse Application”. In ideal case it should already work, but you might have to adjust the run configuration that was created. If you see in the console log errors like

MESSAGE Bundle org.eclipse.xtext_1.0.1.v201008251220 [167] was not resolved.
!SUBENTRY 2 org.eclipse.xtext 2 0 2010-11-12 14:00:47.803
!MESSAGE Missing required bundle org.eclipse.xtext.util_1.0.1.
!SUBENTRY 2 org.eclipse.xtext 2 0 2010-11-12 14:00:47.803
!MESSAGE Missing optionally required bundle org.eclipse.emf.codegen_2.5.0.

then close the application again (which should have started instead of these errors). Your DSL editor won’t work then.

Open Run / Run Configurations / Eclipse Application / MyDSL.product and open the Plug-ins page. Press the “Validate Plug-ins” button. If the validation fails for Xtext plugins then we have a problem.

The validation failures for the plugins

  • javax.servlet.jsp
  • org.apache.commos.el
  • org.apache.jasper
  • org.eclipse.equinox.jsp.jasper

can be ignored.

The possible problem causing these errors can be again the wrong version of com.google.collect that was selected for the run configuration. Make sure that version 0.8.0 is selected and 1.0.0 not.

Press “Validate Plug-ins” again. Now no Xtext plugin should fail validation. The others mentioned above can be ignored for now.

You might have to adjust also the memory settings if you experience OutOfMemory problems. This can be done on the Arguments page in the “VM argument” field. The settings I have chosen are:

-Xmx400m -XX:MaxPermSize=150m

8. Test the product

If everything is now configured correctly start the application again. The application should now start successfully and show a minimal Eclipse IDE.

Now it is time to test our DSL editor. To do so do the following:

  1. Create a new Project “MyDSLTest”
  2. In the Project Explorer right-click on the project and select Configure / Add Xtext Nature
  3. Create a new file “test.mydsl”.
  4. Enter “Hello Xtext!”. The word “Hello” should be colored purple and the Outline view should contain “Xtext”

9. Creating an executable application

Once the product has been tested successfully you can export it with the Eclipse Product export wizard. There is a direct link to it on the Overview page of the MyDSL.product file or run the Export wizard through File / Export / Plug-in Development / Eclipse product.

That’s it!

Now you have a small decent IDE that contains an editor for your DSL! Of course, depending on the requirements, you need to add more.

  • If your DSL requires more features to run add them to the feature.xml of org.xtext.example.mydsl.platform.feature
  • You might generate code for your DSL models. You should read about Xtext Build Participants. The Xtext Domainmodel example, which can be created with the New Project Wizard, demonstrates this also.
  • Add further IDE features (SVN, …) for your product to the Feature dependencies of the Product Configuration.
  • Set up a headless build for your product. Consider to use Maven 3 / Tycho for this.