Migrating Step By Step

Before you start the migration to Xtext 1.0, you should make sure that no old plug-ins are in your target platform. Some plug-ins from Xtext 0.7.x have been merged and do no longer exist.

Tip: The following steps try to use the Eclipse compiler to spot any source-incompatible changes while fixing them with only a few well described user actions. Doing these steps in another order causes most likely a higher effort.

Update the Plug-in Dependencies and Import Statements

You should update the constraints from version 0.7.x to [1.0.0,2.0.0) in your manifest files if you specified any concrete versions. Make sure that your dsl.ui-projects do not refer to the plug-in org.eclipse.xtext.ui.common or org.eclipse.xtext.ui.core but to org.eclipse.xtext.ui instead. The arguably easiest way is a global text-based search and replace across the manifest files. The bundle org.eclipse.xtext.log4j is obsolete as well. The generator will create import-package entries in the manifests later on.

The next step is to fix the import statements in your classes to match the refactored naming scheme in Xtext. Perform a global search for " import org.eclipse.xtext.ui.common." and " import org.eclipse.xtext.ui.core." and replace the matches with " import org.eclipse.xtext.ui.". This fixes most of the problems in the manually written code.

Rename the Packages in the dsl.ui-Plug-in

We changed the naming pattern for artifacts in the dsl.ui-plug-in to match the OSGI conventions. The easiest way to update your existing projects is to apply a “Rename Package” refactoring on the packages in the src- and src-gen folder before you re-run the workflow that regenerates your language. Make sure you ticked “Rename sub-packages” in the dialog. It is error-prone to enable the search in non-Java files as this will perform incompatible changes in the manifest files. Furthermore, it is important to perform the rename operation in the src-gen folder, too. This ensures that the references in your manually written code are properly updated.

Update the Workflow

The JavaScopingFragment does no longer exist. It has been superseded by the ImportURIScopingFragment in combination with the SimpleNamesFragment. Please replace

<fragment 
    class="org.eclipse.xtext.generator.scoping.JavaScopingFragment"/>

with

<fragment 
    class="org.eclipse.xtext.generator.scoping.ImportURIScopingFragment"/>
<fragment 
    class="org.eclipse.xtext.generator.exporting.SimpleNamesFragment"/>

The PackratParserFragment has been abandoned as well. It is save to remove the reference to that one if it is activated in your workflow. After you’ve changed your workflow, it should be possible to regenerate your language without any errors in the console. It is ok to have compilation errors prior to executing the workflow.

MANIFEST.MF and plugin.xml

The previous rename package refactoring updated most of the entries in the MANIFEST.MF and and some entries in the plugin.xml. Others have to be fixed manually. The Eclipse compiler will point to many of the remaining problems in the manifest files but it is unlikely that it will spot the erroneous references in the plugin.xml.

Noteworthy API Changes

The src folders are generated once, so existing code will not be overwritten but has to be updated manually. At least one new class has appeared in your src-folder of the ui plug-in. there will now be a StandaloneSetup inheriting form the generated StandaloneSetupGenerated to allow customization.

You will face a couple of compilation problems due to changes in the API. Here’s a list of the most prominent changes. It is usually only necessary to change your code, if you face any compilation problems.