VIATRA/DeveloperDocumentation/DevEnvironment

Old information
The content from this page was migrated to the new, Github-based wiki system of VIATRA: https://github.com/eclipse-viatra/org.eclipse.viatra/wiki/Development-Environment-Setup

Setup

Automatic (Oomph)

The manual process of setting up a development environment (described below) can be automated with Oomph.

• Download and run Eclipse Installer
• Use the advanced mode
• Product:
  • Product: Eclipse Platform (Committers and Modeling also works)
  • Product Version: Latest
• Projects:
  • Catalog: Eclipse Projects
  • Check the selected projects (see below)
• Variables:
  • Check show all variables
  • Copyright owner (VIATRA): enter your employer or those who should be mentioned as copyright holders in new file comments (e.g. your employer). You don't have to add your name, as that is already inserted from the ${user} variable by Eclipse.
  • 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: select the latest version
  • 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 may be asked whether to proceed with launching with projects with errors. You can safely proceed, the executed generator workflows should fix these errors.

Project selection

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

Make sure you include EVERY subproject you require, as selecting the top-level VIATRA project does not automatically include its subprojects!

• VIATRA project: common components and settings, always include this
  • VIATRA Core subproject: core components, like query and transformation support, together with addons and integrations
  • VIATRA Tooling subproject: installs VIATRA SDK from the CI update site to avoid query bootstrapping; DO NOT install if you are planning to change the query environment (e.g. grammars or code generator)
  • CEP subproject: complex event processing code - only old versions available, not available since version 2.0
  • DSE subproject: design space exploration support

Common combinations:

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

Manual setup

Install dependencies

• Current Eclipse Modeling Tools distribution
  • 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 the latest releases)
• Xtext SDK 2.16+
  • Xtext update site: http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/ or the SimRel update site
  • Older 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/«current release»
  • Graphical Modeling Framework (GMF) Runtime SDK
  • Graphical Modeling Framework (GMF) Notation SDK
  • Graphiti SDK
  • UML2 Extender SDK
  • GEF Zest SDK (version 5.0+)

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)

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 after running the Oomph setup if you are on a pre-1.5 maintenance branch, 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.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.

Troubleshooting

Q: Oomph setup fails with the error message "The artifact is already available in the repository".

A: Uncheck 'Mirrors' in the Oomph setup dialog.

Q: Bootstrapping metamodel and grammar code generation fails with compilation errors.

A: Try rerunning the Oomph setup.

Q: After successfully running the Oomph setup, some of the plugins are not imported to the workspace and the generators do not run automatically.

A: Make sure every required subproject is selected.

Q: "Lambda expressions are allowed only at source level 1.8 or above" shows as an error message on an Xtend source.

A: This error occurs when Java 1.8 compatible Java has been generated from the specific Xtend source(s), but the required execution environment for the plugin is of an earlier version (Java 1.7, for example.) The error may occur even without having Java8 installed on the machine. Delete the contents of the xtend-gen folder (but not the folder itself!) and clean-build the project.