Migrating from Xtext 0.7.x to 1.0

For the sake of completeness, here is how you migrate from Xtext 0.7.x to Xtext 1.0, so you might do a migration to 2.0 in two steps. Nevertheless, there have been so many new features and changes that it probably makes more sense to just copy the grammar and start with a new Xtext 2.0 project. The grammar language is fully backward compatible.

Migrating Step By Step

Once again, 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 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 subpackages" in the rename 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 (src) in combination with the SimpleNamesFragment (src). 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 MyDslStandaloneSetup inheriting form the generated MyDslStandaloneSetupGenerated 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.

For an overview over the new features in Xtext 1.0 consult our New and Noteworthy online.