Revision as of 12:50, 13 March 2009

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

Procedure

Setup new workspace with existing oAW Xtext projects

First, [[Xtext/GettingStarted|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.

migrate grammar and linking

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 change not only conceptual but on the syntax level as well as. If you have used any of the following features, please read on at the [#grammar|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)
• In M6, Enums are not yet implement
• string rules (have been replaced by datatype rules)
• lexer rules (habe been replaced by terminal rules)

General procedure

• Merge original grammar into new grammar definition

migrate workflow

• 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

migrate checks and templates

Qualified name of stdlib has changed from org.openarchitectureware.util to org.eclipse.xtend.util

extension org::openarchitectureware::util::stdlib::io -> 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

migrate IDE

TBD

In-depth comparison

grammar

TBD, see Xtext/Documentation for now.

linking

TBD, see Jan's comment https://bugs.eclipse.org/bugs/show_bug.cgi?id=268506#c1

Unexpected errors

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