Revision as of 12:46, 24 March 2016

Setup

Automatic (Oomph)

The above described manual process can be automated with Oomph.

• Download and run Eclipse Installer
• Product:
  • Product: Eclipse IDE for Java Developers
  • Product Version: Mars
• Projects:
  • Click the green plus button (Add user projects)
    • Catalog: Eclipse Projects
    • Resource URIs: http://download.eclipse.org/viatra/setup/VIATRAEMF.setup
  • Check the selected projects (see below)
• Variables:
  • Check show all variables
  • Installation location rule: leave default
  • Installation folder name: arbitrary
  • Root install folder: arbitrary
  • Workspace location rule: leave default
  • Git clone location rule: leave default
  • Target Platform: Mars
  • Git or Gerrit repository: SSH (read-write, Gerrit) is recommended if you want to contribute
    • Eclipse Git/Gerrit user ID: your Gerrit user ID if you selected a Gerrit repository
• When the bootstrap launch configs run, you are asked whether to proceed with launching with projects with errors. You can safely proceed, this is by design.

Project selection

The VIATRA setup file contains multiple subprojects to support various development use cases.

• VIATRA project: common components and settings, always include this
  • VIATRA Core subproject: core components, like query and transformation support, together with addons and integrations
  • CEP subproject: complex event processing code
  • DSE subproject: design space exploration support
  • VIATRA Tooling subproject: installs VIATRA SDK to avoid bootstrapping
  • Xcore Integration subproject: code related to Xcore support

Common combinations:

• Core developer: select VIATRA + Viatra Core + CEP + DSE subprojects; everything is downloaded as source. Manual bootstrapping of query code generation required.
• CEP developer: select VIATRA + VIATRA Tooling + CEP subprojects; CEP is available as source, but query development support is installed. No manual bootstrapping required.
• DSE developer: seelct VIATRA + VIATRA Tooling + DSE subprojects; DSE is available as source, but query development support is installed. No manual bootstrapping required.

Manual setup

Install dependencies

• Eclipse Modeling Tools 3.7, 3.8, 4.2, 4.3, 4.4 or 4.5 distribution
  • https://www.eclipse.org/downloads/packages/eclipse-modeling-tools/mars1
  • Other Eclipse distributions might work as well, but they must contain EMF SDK
  • Newer Eclipse versions should also work (we regularly test and develop with Eclipse 4.4 and 4.5)
• Xtext SDK 2.9
  • Xtext update site: http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/
  • Other versions of Xtext are not supported
  • This also requires a current version of EMF (2.10)
• EGit (includes JGit) - required components for downloading source from Git
  • Available from Eclipse release train update site: http://download.eclipse.org/releases/mars
• Guice Multibindings extension - used by the transformation language configuration
  • Available from Eclipse Orbit project: http://download.eclipse.org/tools/orbit/downloads/ (not an update site url)
  • Oomph setup uses the following update site: http://download.eclipse.org/tools/orbit/downloads/drops/R20150124073747/repository/

Optional: Install integration dependencies

If you want to develop the org.eclipse.viatra.integration.* projects, install the following dependencies:

• From http://download.eclipse.org/releases/mars
  • Graphical Modeling Framework (GMF) Runtime SDK
  • Graphical Modeling Framework (GMF) Notation SDK
  • Graphiti SDK
  • MoDisco SDK
  • UML2 Extender SDK
  • Xcore SDK

From http://download.eclipse.org/viatra/dependency

• • GEF4 Zest SDK

Alternatively you can just close the integration projects (as they are non-essential).

Clone source projects from Git

The project is available from the Eclipse repository at org.eclipse.viatra.git (browse, stats, fork on OrionHub) . To clone it, you can select either clone URLs listed. However, if you want to use the committer account, you have to use the ssh url.

After obtaining a local git repository on your hard disk, import the Eclipse plug-in projects in the repository into your Eclipse workspace.

For details, see the Eclipse EGit help and the Git tutorial from Lars Vogel.

Important: Do not forget to set up your name and email address in your local Git repository - Git identifies your commits using your email address.

Editor Settings

Code style: slightly modified built-in Eclipse style

• line width: 120 characters both for code and comments
• using spaces for indentation

Downloadable style available from File:IncQueryFormatter.xml.zip

Comment templates:

• Copyright header for each Java file
• Leaving override annotations out

Downloadable template available from File:Eiq-jdt-templates.xml.zip

Bootstrapping metamodel and grammar code generation

Run the following launch configurations:

• GenerateReteRecipeMetamodel.mwe2 (Query component)
• GenerateNotationMetamodel.mwe2 (Addon component, viewers)
• GenerateTraceabilityMetamodel.mwe2 (Transformation component, view model transformation)
• GenerateTransformationTraceMetamodel.mwe2 (Transformation component, debugger)
• GeneratePatternLanguage.mwe2 (Query component)
• GenerateEMFPatternLanguage.mwe2 (Query component)
• GenerateGeneratorModel.mwe2 (Query component)
• GenerateCepMetamodels.mwe2 (CEP component)
• GenerateVepl.mwe2 (CEP component)

Explanation: The projects contain both manually written and generated code. They are placed in different source folders: all src folders contain only manually written code, the following folders contain generated code:

• The emf-gen and src-gen folders contain code generated by the EMF metamodel generation workflows.
• The src-gen folders contain code generated by the Xtext code generation workflows.
• The xtend-gen files contain code generated by the Xtend compiler which is run incrementally. These files do have dependencies of the other workflow-generated files: before the workflow is executed, it is normal for these files to be erroneous.

Generated code is not committed into Git, so the generator workflows have to be run during setup or whenever a metamodel, grammar or workflow file changes.

Xtext code generator workflows require about 30-60 seconds to run - be patient.

Bootstrapping query code generation

This step has to be performed manually even after running the Oomph setup, unless the VIATRA SDK was installed using the VIATRA Tooling sub-project.

Some components already include VIATRA Query patterns but the generated code is not stored in version control. In order to correctly compile these projects, run the Bootstrap launch configuration and import the following projects:

• org.eclipse.viatra.addon.viewers.runtime
• org.eclipse.viatra.addon.viewers.runtime.zest
• org.eclipse.viatra.cep.core
• org.eclipse.viatra.cep.core.metamodels
• org.eclipse.viatra.integration.uml
• org.eclipse.viatra.query.tooling.ui.retevis
• org.eclipse.viatra.transformation.views

After importing, the VIATRA Query builder should generate the code for each pattern definition as needed.

Notes:

• You may have to manually open and edit-save the *.vql files to trigger the builder.
• If you create an own launch configuration for bootstrapping query code generation, make sure to exclude these imported projects from it, and either include the metamodel projects required by them in it or import them into the runtime workspace as well.