Developer Setup

This guide offers step-by-step instructions for setting up Eclipse so that you can run and develop ScenarioTools/SML. You will install the following components during the process:

  • Eclipse Modeling Framework
  • Xtext
  • GEF Zest
  • Henshin
  • JDT
  • GraphViz

If you already have these components installed you can skip the installation and start with importing the ScenarioTools/SML projects from Git.

0.1 Important!

In order to compile projects with xtend files, you need to change your text file encoding to UTF-8 in Eclipse:

  • Open the dialogue “Window -> Preferences”
  • Select the sub menu “General -> Workspace”
  • Change “Text File encoding” to UTF-8

Screenshots:

Installation Instructions - utf8_1  Installation Instructions - utf8_2

0.2 Note for Windows users

Due to the sometimes very long paths/filenames in the eclipse directory, it is recommended for windows users to install Eclipse to a location like C:\Eclipse or even C:\e. Otherwise, some files may get lost due to the restricted file name length. The same is recommended for other folders that contain Eclipse-related files such as your Eclipse workspace or your local copy of the Git repository.

1.0 Step-by-step Installation Guide

Download the latest Eclipse Modeling Tools and extract them as described above. This package includes some required modeling tools and JDT.

1.1 Install Xtext

  • Open the dialogue Help -> Eclipse Marketplace
  • Search for Xtext
  • Install Xtext 2.9.* or a later version
  • If you get a Security Warning about unsigned content, proceed with the installation

Screenshots:

Installation Instructions - xtext_1  Installation Instructions - xtext_2

1.2 Install Zest

Installing GEF Zest is optional but recommended, as the simulation history view requires Zest. (Note: the ‘optional’ part needs confirmation.)

  • open the “Install New Software” dialogue” (Help -> Install New Software…)
  • choose http://download.eclipse.org/releases/neon or an equivalent update site. Note: When choosing an update site for the first time Eclipse has to download its index. Progress for this download task is shown in Eclipse’s main window, NOT in the “Install New Software” dialogue (see screenshot 2 below).
  • search for “Zest”
  • install both features that are not labeled “examples”
  • If you get a Security Warning about unsigned content, proceed with the installation

Screenshots:

Installation Instructions - zest_1  Installation Instructions - zest_2

1.3 Install Henshin

  • open the “Install New Software” dialogue (Help -> Install New Software…)
  • copy & paste an update site from https://www.eclipse.org/henshin/install.php (e.g. Releases) into the “Work with:” field
  • install the new feature
  • If you get a Security Warning about unsigned content, proceed with the installation

Screenshots:

Installation Instructions - zest_1  Installation Instructions - henshin_2

1.4 Install GraphViz (optional)

Some algorithms, e.g., the controller synthesis, generate .dot files for visualizing graphs. To convert these into .pdf files it is recommended to install GraphViz. If you already got a program to view .dot files you can skip this step as it is optional.

1.5 Install Graphical Editing Framework (GEF)

To visualize ObjectSystem it is recommended to install the Graphical Editing Framework (GEF).

  • Open the “Install New Software” dialogue (Help -> Install New Software…)
  • Copy & paste an update site from this link  (recommended: GEF4 Releases) into the “Work with:” field
    Note: ScenarioTools is currently incompatible with GEF5 or higher.
  • Check the checkbox “Group items by category”
  • In the category “GEF4 DOT” check “GEF4 DOT”, “GEF4 DOT SDK” and optionaly “GEF4 DOT.UI”

Screenshots:

Installation Instructions - gef_1  Installation Instructions - gef_2

2.0 Import ScenarioTools/SML projects

Clone this repository and import all projects into your workspace, except the *.examples.* projects:

  • right-click into your Package Explorer and choose Import…
  • choose Git -> Projects from Git
  • choose Clone URI
  • copy & paste the Clone URI (https://bitbucket.org/jgreenyer/scenariotools-sml.git) from Bitbucket into the URI field and enter your login credentials
  • keep all branches selected and simply click on Next
  • choose a location for your local copy of the Git repository
  • leave Import existing Eclipse projects selected and click on Next
  • keep all projects selected and click on Finish
  • your Eclipse will start compiling the code which may take a while. There are still some warnings but you should not get any errors once Eclipse is done building the projects.

Screenshots:

Installation Instructions - git_1  Installation Instructions - git_2  Installation Instructions - git_3  Installation Instructions - git_4  Installation Instructions - git_5  Installation Instructions - git_6  Installation Instructions - git_7

2.1 Launching ScenarioTools

ScenarioTools is a collection of Eclipse plug-ins. To launch ScenarioTools, you need to launch an Eclipse instance which includes all the plug-ins ScenarioTools consists of. Such an Eclipse instance can easily be launched via a Run/Debug Configuration once ScenarioTools’ sources are installed and have been built.

  • open the Debug Configurations dialog (Run -> Debug Configurations…)
  • right-click on Eclipse Application and choose New
  • pick a name for the configuration
  • pick a location for the workspace of this new Eclipse instance you are about to launch
  • click on Debug

Screenshots:

Installation Instructions - launch_config_1  Installation Instructions - launch_config_2  Installation Instructions - launch_config_3

2.2 Importing examples (optional)

There are a variety of examples you can use as a starting point to learn how to use ScenarioTools or how to create your own specifications. Importing these examples into the workspace of your just launched ScenarioTools Eclipse instance is the same process you followed to download and install the ScenarioTools sources from our repository, except that you use a different repository.

2.3 Setting up GraphViz (optional)

Some of the ScenarioTools features create .dot files to store generated graphs. Using GraphViz, these .dot files can be converted into .pdf files for viewing. The easiest way to do this conversion is by integrating GraphViz as an external tool into Eclipse.

  • open the External Tools Configurations dialog (Run -> External Tools -> External Tools Configurations…)
  • right-click on Program and choose New
  • pick a name for the configuration
  • enter the path of your dot binary (part of your GraphViz installation) into the Location: field
  • set the Working Directory: field to
    • ${container_loc}
  • set the Arguments: field to
    • ${selected_resource_loc} -Tpdf -O
  • click on Apply and then click on Close

After following these steps you can easily convert .dot files to .pdf in your Eclipse by selecting them in the Package Explorer and then running the External Tool Configuration you just set up.

Hint: If you want generated files to show up automatically without requiring a manual refresh, you can enable Refresh using native hooks or polling on the same preference page on which you changed the text file encoding to UTF-8.

Screenshots:

Installation Instructions - graphviz_1  Installation Instructions - graphviz_2  Installation Instructions - graphviz_3  Installation Instructions - automatic_refreshing

2.4 Setting up ObjectSystem preferences

To render an ObjectSystem in the ObjectSystem view, the path to the dot.exe file of Graphivz could be provided as described below.

  • Open the Preferences dialog from the Eclipse Runtime after Launching Scenariotools (Windows->Preferences)
  • Go to ScenarioTools->ObjectSystem Preferences
  • Clic on the button “Browse…” and choose the folder which contains the “dot.exe” file (e.g. C:\Program Files (x86)\Graphviz2.38\bin)
  • Clic on the button “Apply”
  • Clic on the button “OK”

Screenshots:

Settings up ObjectSystem prefrences - ObjectSystemPrefences_1  Settings up ObjectSystem prefrences - ObjectSystemPrefences_2

3.0 Alternative Installation Guide

If the above installation guide does not work for you, you may also try downloading and installing the Eclipse DSL Tools instead of the Eclipse Modeling Tools.

Download the latest Eclipse DSL Tools and extract them to a directory in the file system.

Then follow the Modeling Tools installation guide, except that you can skip the Xtext installation step.

4.0 Usage

Here video tutorials can be found explaining how to use ScenarioTools.