• Home
• Download
• Documentation
• Support
• Community
• Developers

• Getting Started
• Installation
  • Install Pre-Configured Eclipse With Xtext
  • Install Xtext From Update Site
• 5 Minutes Tutorial
  • Creating A New Xtext Project
  • Generating The Language Infrastructure
  • Try The Editor
  • Conclusion
• 15 Minutes Tutorial
  • Create A New Xtext Project
  • Write Your Own Grammar
  • Generate Language Artifacts
  • Run the Generated IDE Plug-in
  • Second Iteration : Adding Packages and Imports
• 15 Minutes Tutorial - Extended
  • Writing a Code Generator With Xtend
  • Unit Testing the Language
  • Creating Custom Validation Rules
• Reference Documentation
• Overview
  • What is Xtext?
  • How Does It Work?
  • Xtext is Highly Configurable
  • Who Uses Xtext?
  • Who is Behind Xtext?
  • What is a Domain-Specific Language
• The Grammar Language
  • A First Example
  • The Syntax
  • Ecore Model Inference
  • Grammar Mixins
  • Common Terminals
• Configuration
  • The Language Generator
  • Dependency Injection in Xtext with Google Guice
• Runtime Concepts
  • Runtime Setup (ISetup)
  • Setup within Eclipse-Equinox (OSGi)
  • Logging
  • Validation
  • Linking
  • Scoping
  • Value Converter
  • Serialization
  • Formatting (Pretty Printing)
  • Fragment Provider (Referencing Xtext Models From Other EMF Artifacts)
  • Encoding in Xtext
• IDE Concepts
  • Label Provider
  • Content Assist
  • Quick Fixes
  • Template Proposals
  • Outline View
  • Hyperlinking
  • Syntax Coloring
• Xtext and Java
  • Plug-in Setup
  • Referring to Java Elements using JVM Types
  • Referring to Java Types Using Xbase
  • Inferring a JVM Model
  • Using Xbase Expressions
  • Xbase Language Reference
  • Lexical Syntax
  • Types
  • Expressions
  • Extension Methods
• MWE2
  • Examples
  • Language Reference
  • Syntax Reference
• Xtend
  • Getting Started
  • Classes and Functions
  • Expressions
• Integration with EMF and Other EMF Editors
  • Model, Ecore Model, and Ecore
  • EMF Code Generation
  • XtextResource Implementation
  • Integration with GMF Editors
• Appendix
• Migrating from Xtext 1.0.x to 2.0
  • Take the Shortcut
  • Migrating Step By Step
  • Now go for then new features
• Migrating from Xtext 0.7.x to 1.0
  • Migrating Step By Step

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.

Top

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

with

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.

• In the generated UI plug-in's MANIFEST.MF, remove the package exports of no longer existing packages and make sure the bundle activator points to the newly generated one (with .ui. in its package name).
• It was already mentioned that the plug-ins org.eclipse.xtext.ui.core and org.eclipse.xtext.ui.common have been merged into a new single plug-in org.eclipse.xtext.ui. The same happened to the respective Java packages. Change eventually remaining bundle-dependencies in all manifests.
• The plug-in org.eclipse.xtext.log4j no longer exists. We use a package import of org.apache.log4j instead. Also remove the buddy registration.
• Due to renamed packages, you have to fix all references to classes therein in the plugin.xml. A comparison with the plugin.xml_gen will be a great help. If you haven't added a lot manually, consider merging these into the generated version instead of going the other way around. Note that warnings in the plugin.xml can be considered to be real errors most of the time. Make sure the MyDslExecutableExtensionFactory has the .ui. package prefix. Classes from org.eclipse.xtext.ui.common and org.eclipse.xtext.ui.core are now usually somewhere in org.eclipse.xtext.ui. They are also referenced by the MyDslExecutableExtensionFactory and thus not covered by the validation of the plugin.xml.
• A number of new features are being registered in the plugin.xml, e.g. Find references, Quick Outline, and Quick Fixes. You can enable them by manually copying the respective entries from plugin.xml_gen to plugin.xml.
• To run MWE2 workflows later on, you must change the plug-in dependencies from org.eclipse.emf.mwe.core to org.eclipse.emf.mwe2.launch in your manifest. Optional resolution is fine.

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.

• The method IScopeProvider.getScope(EObject,EClass) (src) has been removed. Use getScope(EObject,EReference) instead.
• Renamed DefaultScopeProvider to SimpleLocalScopeProvider (src). There have been further significant changes in the scoping API that allow for optimized implementations. Consult the section on scoping for details.
• The return type of AbstractInjectableValidator.getEPackages() (src) was changed from List<? extends EPackage> to List<EPackage>.
• The parser interfaces now use Reader instead of InputStream to explicitly address encoding. Have a look at the section on encoding for details.
• The handling of ILabelProvider in various contexts has been refactored. The former base class DefaultLabelProvider no longer exists. Use the DefaultEObjectLabelProvider (src) instead. See the section on label providers for details.
• We have introduced a couple of new packages to better separate concerns. Most classes should be easy to relocate.
• The runtime and UI modules have separate base classes DefaultRuntimeModule (src) and DefaultUiModule (src) now. We use Guice's module overrides to combine them with the newly introduced SharedModule (src). You have to add a constructor the your MyDslUiModule that takes an AbstractUIPlugin as argument and pass that one to the super constructor. Tip: There is an Eclipse quick fix available for that one.
• The interfaces ILexicalHighlightigConfiguration and ISemanticHighlightingConfiguration have been merged into IHighlightingConfiguration (src).
• The DefaultTemplateProposalProvider (src) takes an additional, injectable constructor parameter of type ContextTypeIdHelper (src).
• The HyperlinkHelper (src) uses field injection instead of constructor injection. The method createHyperlinksByOffset(..) should be overridden instead of the former findCrossLinkedEObject.
• The API to skip a node in the outline has changed. Instead of returning the HIDDEN_NODE you'll have to implement boolean consumeNode(MyType) and return false. Note: The outline has been re-implemented in Xtext 2.0.
• The Readonly*Storage implementations have been removed. There is a new API to open editors for objects with a given URI. Please use the IURIEditorOpener (src) to create an editor or the IStorage2UriMapper (src) to obtain an IStorage for a given URI.
• The interfaces IStateAccess and IEObjectHandle have been moved along with the IUnitOfWork (src) to the package org.eclipse.xtext.util.concurrent. Note: IStateAccess was split into IReadAccess and IWriteAccess in Xtext 2.0.
• The ValidationJobFactory is gone. Please implement a custom IResourceValidator (src) instead.
• The grammar elements Alternatives (src) and Group (src) have a new common super type CompoundElement (src). The methods getGroups() and getTokens() have been refactored to getElements().
• Completion proposals take a StyledString instead of a plain string as display string.
• The AbstractLabelProvider (src) does no longer expose its IImageHelper (src). Use convertToImage instead or inject your own IImageHelper (src).
• The implementation-classes from org.eclipse.xtext.index were superseded by the builder infrastructure. Use the QualifiedNamesFragment (src) and the ImportNamespacesScopingFragment (src) instead of the ImportedNamespacesScopingFragment. Please refer to the section about the builder infrastructure for details.
• All the Xtend-based fragments were removed.
• ILinkingService.getLinkText (src) was removed. Have a look at the LinkingHelper (src) and the CrossReferenceSerializer (src) if you relied on this method.
• The SerializerUtil was renamed to Serializer (src). There were other heavy refactorings that involved the serializer and its components like e.g. the ITransientValueService (src) but it should be pretty straight forward to migrate existing client code.
• The method-signatures of the IFragmentProvider (src) have changed. The documentation will give a clue on how to update existing implementations.
• Some static methods were removed from utility classes such as EcoreUtil2 (src) and ParsetreeUtil in favor of more sophisticated implementations.

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