This document describes how Xtext projects of oAW 4.3 can be migrated to TMF Xtext. It assumes that you do have a running version of TMF Xtext as described in the Getting Started Document.
work in progress
Setup new workspace with existing oAW Xtext projects
First, set up an Eclipse that works with TMF Xtext and create a new, empty workspace. Import your existing oAW Xtext projects (Grammar project, Generator project and UI project) into this workspace for further reference. Also, for future steps it is helpful to have the generated output of your project available to compare against the output of the new projects.
Be sure to disconnect these projects from version control or to work on a branch. You might want to apply changes on these folders to ease your comparison activities.
create new TMF Xtext project
Create your new Xtext project in this workspace with the Xtext project wizard. During this process you have to provide a fully qualified language name. Choose this name carefully, it not only affects the name of the language itself (last token). The package names of your projects are directly derived from this, too. To reduce the amount of migration work you should try to choose a name, that results in the same package structure and language name you had on oAW. Doing so, Xpand templates and Xtend files must not change their import statements. Leave the sample grammar unchanged and generate the Xtext artefacts as described in the GettingStarted document.
Start over if the resultung package or grammar names are not as expected. You can simply delete the created projects (be sure to tick "Delete project contents on disk").
setup minimalistic model
Test, whether your generator project works. In the generator project you will find a workflow file in the package workflow. If everything works fine you are now having an empty set of Xtext projects that have package structure and language name in common with your oAW projects.
If not done, yet, put your newly created projects under version control. Having solid checkpoints during your migration can save hours of work.
Extract a simple model file from your original and place it into the model package of your generator project and run the generator again. You should now get some parser errors. This is fine since the default example grammar does not correspond to the syntax of your model file.
Even though the capabilites of TMF Xtext have been extended or improved compared to oAW Xtext the grammar language itself remained widely compatible. Nevertheless, some features have been changed not only conceptually but on the syntax level as well as. If you have used any of the following features, please read on in the in-depth section of grammar migration.
- import feature with URI (this has been replaced with the importURI-feature)
- INT Rule with negative numbers (INT cannot consume "-", you have to introduce another terminal rule)
- enum rules (slightly modified syntax)
- string rules (have been replaced by datatype rules)
- lexer rules (have been replaced by terminal rules)
- Merge original grammar into new grammar definition
- Merge original workflow into new workflow
- Parser component has been replaced by reader
- Components and classes have been renamed, e.g.
oaw.workflow.common.DirectoryCleaner -> org.eclipse.emf.mwe.utils.DirectoryCleaner "directories" (deprecated) -> "directory"
- oaw.xpand2.Generator -> org.eclipse.xpand2.Generator
- oaw.xtend.XtendComponent -> org.eclipse.xtend.XtendComponent
- oaw.check.CheckComponent -> org.eclipse.xtend.check.CheckComponent
- org.openarchitectureware.xpand2.output.XmlBeautifier -> org.eclipse.xpand2.output.XmlBeautifier
- org.openarchitectureware.xpand2.output.JavaBeautifier -> org.eclipse.xpand2.output.JavaBeautifier
- oaw.xpand2.GeneratorAdvice -> org.eclipse.xpand2.GeneratorAdvice
- oaw.xpand2.output.NoChangesVetoStrategy -> org.eclipse.xpand2.output.NoChangesVetoStrategy
migrate checks, templates and extensions
Qualified names of some extensions have changed:
- org.openarchitectureware.util -> org.eclipse.xtend.util
- org::openarchitectureware::uml2::profile::profiling -> org::eclipse::xtend::typesystem::uml2::profile::profiling
This means you have to change you extension imports for stdlib like this:
extension org::eclipse::xtend::util::stdlib::io «EXTENSION org::eclipse::xtend::util::stdlib::io»
migrate headless build
- org.openarchitectureware.workflow.ant.WorkflowAntTask -> org.eclipse.emf.mwe.core.ant.WorkflowAntTask
- org.openarchitectureware.workflow.WorkflowRunner -> org.openarchitectureware.workflow.WorkflowRunner
Update the needed Jars to build classpath if you cannot rely on a working eclipse installation
Open you project's .project file in the project's root directory. There you have to replace the oAW builder and oAW nature:
- org.openarchitectureware.base.oawBuilder -> org.eclipse.xtend.shared.ui.xtendBuilder
- org.openarchitectureware.base.oawNature -> org.eclipse.xtend.shared.ui.xtendXPandNature
migrate modeling projects
This sections describes how to migrate projects which use an xtext generated DSL.
Right now there is no new project wizard for xtext based DSLs.
Dependencies / MANIFEST.MF
Require-Bundle: org.apache.commons.logging;bundle-version="1.0.4", org.eclipse.emf.ecore;bundle-version="2.5.0", org.eclipse.emf.ecore.xmi;bundle-version="2.5.0", org.eclipse.xtend.typesystem.emf;bundle-version="0.7.0", org.eclipse.emf.mwe.core;bundle-version="0.7.0", org.eclipse.emf.mwe.utils;bundle-version="0.7.0", org.eclipse.xtext;bundle-version="0.7.0", org.eclipse.xtext.log4j;bundle-version="1.2.15", org.eclipse.xtend;bundle-version="0.7.0", org.eclipse.xtend.util.stdlib;bundle-version="0.7.0", org.eclipse.xpand;bundle-version="0.7.0", org.eclipse.jface.text;bundle-version="3.5.0", org.antlr.runtime;bundle-version="3.0.0", com.ibm.icu;bundle-version="4.0.1"
TBD, see Xtext/Documentation for now.
TBD, see Jan's comment https://bugs.eclipse.org/bugs/show_bug.cgi?id=268506#c1
ClassCaseException while Parsing
EvaluationException : org.eclipse.xtext.parser.ParseException: java.lang.ClassCastException: java.lang.String
-> Missing ValueConverter
DiagnosticErrors while compiling grammar
Errors such as
XtextLinkingDiagnostic: null:21 Cannot resolve reference to 'ID' XtextLinkingDiagnostic: null:25 Cannot resolve reference to 'INT' XtextLinkingDiagnostic: null:238 Cannot resolve reference to 'STRING'
--> Missing super grammar
Cannot resolve reference to 'URI'
Import mechanism has been superseded