Setting up a RCP product for a Xtext DSL

Posted on by

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.

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.

49 thoughts on “Setting up a RCP product for a Xtext DSL”

  1. Hi,

    I’ve done something similar to get the product configuration / headless build working. However, for some reason, I’m seeing that the JDT tools automatically are getting added when I do Export product configuration or a headless build.

    The only difference is that I don’t create a product plugin. I just create foo.product and put that in my org.xtext.example.mydsl.ui plugin.

    I’ve ensured that none of the org.eclipse.jdt.* is selected in the foo.product (by going to Run As -> Run Configurations).

    Would you happen to have any idea why the JDT stuff keeps getting included? Thanks.

    Reply ↓

    • One way to identify what is depending on jdt.ui is to deselect that plugin from the Run Configuration and press Validate Plug-ins. Did you select org.eclipse.xtext.common.types.ui? This has a dependency to jtd.ui. If so, do you really need that plugin? If so, there is no chance to get rid of JDT. The example I have given here is completely without JDT.

      Reply ↓

      • Thanks for your help. I actually downloaded your example and tried it out. It is strange.

        Even in your example, if I do Export Product (using the Eclipse Product Export Wizard) to create the product, I notice that the JDT tools are being included in the plugins directory as well.

        I clicked on MyDSL.product, right click Run As -> Run Configuration and confirmed that the org.eclipse.jdt*.ui stuff is not selected. I also validated the plugin and everything checks out.

        If I Launch an Eclipse Application in the “Testing” under Overview, the application that starts up does not contain Java stuff (as there is no File -> New -> Project -> Java folder). I wonder what is going on.

      • I was finally able to figure this out. It turns out that if one uses the Target Platform (assuming it is Xtext-Eclipse), even though the org.eclipse.jdt_* plugins are unchecked in the Target Platform content, they (for some reason) get included. Thus, one has to create a new Eclipse folder (call it eclipse-target). In this folder, just remove all the JDT plugins except org.eclipse.jdt.core. Then go to Target Platform and add a new target with this folder as the contents. Check this folder so that it is the “active” target. Then when one exports using the wizard (or a headless build), things work OK. Since there are no org.eclipse.jdt.* plugins they don’t get included.

        Strange that just unchecking the plugins in Target Platform doesn’t seem to work for me (I’m on Window 7 64-bit).

      • > I was finally able to figure this out. It turns out that if one uses the Target Platform (assuming it is Xtext-Eclipse), even though the org.eclipse.jdt_* plugins are unchecked in the Target Platform content, they (for some reason) get included.

        Was it ever determined if this is an Eclipse RCP bug? I’m having the same issue right now but haven’t quite worked through things yet.

  2. Karsten:

    thank you for sharing this with us. I have tried for a good number of hours to make it work and I always end up at this error:

    java.lang.IllegalStateException: Unable to acquire application service. Ensure that the org.eclipse.core.runtime bundle is resolved and started (see config.ini).

    It looks like there are no “start” element in my ogsi bundles declaration in config.ini, only file references, including the runtime. I check the configuration and they are configured to be auto start.

    When I run the product as an Eclipse Application, it works fine when I export it and subsequently run it, I get the above error. Do you have an idea of what I could do wrong?

    thanks,

    JJ-

    Reply ↓

  3. I also noticed that my plugins directory does not contain an ui.ide.workbench plugin, even though it was available to select on the dropdown product configuration. I have ui.ide or ui.workbench, but neither show up in the dropdown. Is that expected?

    Reply ↓

    • I have the inverse problem: I’ve got an org.eclipse.ui.ide.workbench plugin in the plugins dir., but I can’t access it from Eclipse and the product doesn’t launch. The error is
      java.lang.RuntimeException: Application “org.eclipse.ui.ide.workbench” could not be found in the registry. The applications available are: […] at org.eclipse.equinox.internal.app.EclipseAppContainer.startDefaultApp(EclipseAppContainer.java:248)

      Reply ↓

      • Hi Meinte.
        I solved this problem adding the “org.eclipse.ui.ide.application” plugin to the configuration.

      • Hi Nicolás,

        I’m having similar issue,
        Shall you explain further, how did you solve this issue?
        Thanks

  4. Hi, thank you for the good job.
    I’ve the same problem of JJ.

    java.lang.IllegalStateException: Unable to acquire application service. Ensure that the org.eclipse.core.runtime bundle is resolved and started (see config.ini).

    @kthoms: what is the file MyDSL.product.launch in org.xtext.example.mydsl.product?

    Reply ↓

  5. Karsten,

    all I can think of, after you gave us all your files (thanks) is that you are using a specific target platform in the Eclipse/Preferences/Plugin Development.

    Could you elaborate? Are you using the default one? the current one? Did you build one from scratch?

    @Jake, the only thing I found that work was to edit the config.ini file manually. I can send you a sample if you want gmail.com/jdubray

    thanks,

    Reply ↓

  7. Tnx for the tutorial. I have another question about this: what should I do different if I want to integrate the editor in an external Java SWT application?

    Reply ↓

  8. I have an application that includes two XText-based plugins (mads and mads.ui as my DSL is called mads) plus one with the help system (mads.help) and one wich reads the model from the .mads file, runs calculations and produces some output.

    I end up with a large number of plugins, but my problem is not there: I followed the steps in your tutorial, and step 9 produces two directories, eclipse and repository.

    I must miss something very basic, as I do not know what to do from there. I was expecting something like “mads.exe” or “eclipse.exe” to get my product running, but i do not see it !!!

    Thanks for help
    MS

    Reply ↓

  9. I did try to follow your tutorial with a full application made of two XText DSL plugins(no generator) plus two more for using the model and for providing help.

    I did work out through the definition of features and product. But when it comes to the last step (export) I must have missed something basic: I get two directories – eclipse and repository – but nothing like an executable .exe file.

    Any suggestion would help.
    MS

    Reply ↓

    • No, the editor is dependent on Eclipse. As soon as Eclipse RAP supports Styled Text it might be possible to run it as a RAP application in the web. But RAP does not support this yet.

      Reply ↓

  11. Could please somebody post up to date example files? What plugins have to be included in the platform feature for eclipse indigo and xtext2.1?

    Reply ↓

  12. Is possible make rcp only with a navigator content and the editor for my dsl ? I dont want the other stuffs, likes menu bars, perspective changes..and more stuffs.

    Reply ↓

  13. I am creating an RCP in eclipse for a DSL to model multi-agent system, but I have problems when launching the applications eclipse shows that errors were detected in some plug-in and not allow the execution and the console displays the following log

    An error has occurred. See the log file

    C:\Users\User\Documents\Graduacion\Herramientas\eclipse-SDK-3.7.1-Xtext-2.2.1-win32\eclipse\workspace\.metadata\.plugins\org.eclipse.pde.core\agente.product\1333078233571.log

    I’m using version 2.2.1 of xtext and xtend2 for code generation,
    I need to know which solution can have this kind of problem, thanks.

    Reply ↓

      • C:\Users\User\Documents\Graduacion\Herramientas\eclipse-SDK-3.7.1-Xtext-2.2.1-win32\eclipse\workspace\.metadata\.plugins\org.eclipse.pde.core\agente.product\1333078233571.log

      • Getting the same message, the error log contains things like:
        1. ERROR in C:\Users\numbers\workspace_Juno\org.xtext.example.mydsl.ui\src-gen\org\xtext\example\mydsl\ui\AbstractMyDslUiModule.java (at line 83)
        return org.xtext.example.mydsl.ui.labeling.MyDslLabelProvider.class;
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        org.xtext.example.mydsl.ui.labeling.MyDslLabelProvider cannot be resolved to a type

        So some imports/dependencies might be missing.

  14. hello, i work on xtext 2.3 eclipse juno 4.2, can you send me the steps i could folow to get the same result you got in your example, because with this xtext version there is no plugin (.generator) when i create a new xtext project?? thanks

    Reply ↓

  15. I did work out through the definition of features and product. But when it comes to the last step (export) I must have missed something basic: I get two directories – eclipse and repository – but nothing like an executable .exe file.

    Any suggestion would help.
    MS

    Reply ↓

      • Thx for your response , actually it works for me, the problem was the ID of the the product (in ‘general information’ of MyDsl.product.product), i fixed it by entring MyDsl.product.product

  16. Hi guys I m getting the following log:

    1. ERROR in C:\Users\numbers\workspace_Juno\org.xtext.example.mydsl.ui\src-gen\org\xtext\example\mydsl\ui\AbstractMyDslUiModule.java (at line 83)
    return org.xtext.example.mydsl.ui.labeling.MyDslLabelProvider.class;
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    org.xtext.example.mydsl.ui.labeling.MyDslLabelProvider cannot be resolved to a type

    Anybody has an idea what should add where ?

    Reply ↓

  17. HI,

    i have a little problem with your tutorial at chapter 9.

    When i start the export i got the following errormessage:
    Cannot complete the install because one or more required items could not be found.
    Software being installed: GMEditor 1.0.0.201312101351 (com.encoway.ba.product.product 1.0.0.201312101351)
    Missing requirement: Eclipse e4 Rich Client Platform 1.2.0.v20130605-1738 (org.eclipse.e4.rcp.feature.group 1.2.0.v20130605-1738) requires ‘org.eclipse.emf.common.feature.group [2.7.0,3.0.0)’ but it could not be found.

    I really don´t know what to do now. Do i have a wrong emf version or what is the problem?

    Best regards
    Lennart

    Reply ↓

  19. While launching the eclipse application I get the following error in my case.
    I am running it through eclipse kepler. java.lang.ClassNotFoundException: org.eclipse.core.runtime.adaptor.EclipseStarter
    at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
    at java.security.AccessController.doPrivileged(Native Method)
    at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
    at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
    at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:633)
    at org.eclipse.equinox.launcher.Main.basicRun(Main.java:591)
    at org.eclipse.equinox.launcher.Main.run(Main.java:1450)
    at org.eclipse.equinox.launcher.Main.main(Main.java:1426)

    Reply ↓

  20. Pingback: Exporting a GMF Editor as an Eclipse Product | Modelesis

  21. hi,
    I tried to download the sources for the example project, but I found out that the link is dead.
    Can you send another link for the examples. Thanks.

    Best regards
    Smail.

    Reply ↓

  22. I am missing some plug-ins from step form, namely:
    com.google.collect
    org.antlr.gen
    org.aopalliance
    org.eclipse.xtend.typesystem.xsd
    org.eclipse.xtend.util.stdlib
    org.eclipse.xtext.xtend
    How do I get them? Any website to install them?
    Thank you!

    Reply ↓

  23. I have this error log
    java.lang.ClassNotFoundException: org.eclipse.core.runtime.adaptor.EclipseStarter
    at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:471)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:588)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:521)
    at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:654)
    at org.eclipse.equinox.launcher.Main.basicRun(Main.java:594)
    at org.eclipse.equinox.launcher.Main.run(Main.java:1447)
    at org.eclipse.equinox.launcher.Main.main(Main.java:1420)

    Reply ↓

  24. I am also missing some plugins. I first decided to leave them out. But in my case I had to stop because step 5.5 is not possible. I have only new / generic.,

    By the way, is it possible to export the DSL to some installable product I can give to someone to install it in his eclipse he is already using?

    Reply ↓

    • > I have only new / generic

      You are likely missing the Eclipse Plugin Development Environment (PDE) in your IDE. Install them or use an appropriate base distribution (e.g. Eclipse for DSL developers or for Committers).

      Sure, installing the plugins into an existing Eclipse instance is the typical way. Build a p2 repository with your plugins within and then use this as an update site. The wizard lets you create a project setup for this. Choose Eclipse Plugin including sub options and Maven as build system on the Advanced page.

      Reply ↓

  25. Thank you very much for this tutorial. I have just started speculating using eclipse and xtext for developing a new IDE. So I very curious to learn whether the “content assist” feature of eclipse+xtext would work in the solution proposed on this article.

    Would very much appreciate your response.

    Reply ↓

Leave a comment