Eclipse Setup

Once you have built Overture (see Checkout and Build Overture), you need to setup your development environment. This guide tells you how.

TOC

1. Initial Setup

• How to import projects
• Which projects to import
• Organizing projects
• Running in debug mode
• Troubleshooting

Initial setup

The first step is to ensure you have Eclipse properly configured. Overture requires that a few Eclipse plugins be installed so we will set those up first.

1. If you haven't already, download and install Eclipse 2019-12, available at http://www.eclipse.org/downloads. (You may want to skip the download installer and download a package directly. The "Eclipse IDE for Eclipse Committers" works fine.)

• Start Eclipse and go to Help ==> Install New Software.... From there, install the plugins below. All plugins are installed from the update site for the downloaded version of Eclipse (http://download.eclipse.org/releases/"version name").

1. m2e - Maven Integration for Eclipse. Note that Eclipse Luna (4..4.1) already has this plugin installed

• UML2 Extender SDK (optional. Only needed to work on the VDM-UML plugin)
• Graphical Editing Framework GEF SDK (also optional. Only needed to work on the RT Trace Viewer plugin)

How to import projects

We are now ready to import Overture into Eclipse. Once again, make sure Overture is built.

1. Go to Files ==> Import... and select Maven / Existing Maven Projects

• Browse to the Overture source code location
• Select the projects to import.
• Only import leaf projects of the tree. The roots are used to group other projects in the maven build.
• Do not import any project under features. They are only used for build configuration purposes.

Note that during the import process, you may be prompted to install additional maven connectors. Do so.

Which projects to import

We have already said that you should not import root or feature projects. Even discounting these, Overture has many projects (57 at the time of this writing). You probably do not want to import them all and you certainly don't need them.

Here are a few recommendations of which projects to import.

• Core Projects:
• ast, parser and typechecker. These 3 provide the basic functionality of constructing and validating ASTs representing VDM models.
• testframework or the projects under testing. These are the test frameworks for Overture (the first one is deprecated). You should test your work...
• Additional core projects such as pog, interpreter, etc. are mostly independent of each other and should be interpreted on a per-need basis.
• IDE Projects:
• Unlike the core projects, IDE projects solve their dependencies through Eclipse so you will need to import a larger set of projects: the ones you want to work on and the ones that satisfy their dependencies.
  • core, ui, debug, builders.vdmj, parsers.vdmj. These projects provide essential functionality that most other projects depend on. You almost always need them.
  • The dialect projects: core, ui and debug under vdmsl, vdmpp and vdmrt. These projects provide basic functionalities (such as editor and debugger support) for each dialect. Import them depending on your dialect needs.
  • product and platform are necessary for running Overture in debug mode from withing Eclipse.
  • plugin projects such as poviewer or uml2 should be imported on a per need basis.

Organizing Projects

Due to the number of projects in Overture, it's recommended you use Eclipse Working Sets to organize them. Here is a suggested setup:

• Core Primary: any core projects you are directly working on
• Core Secondary: test frameworks and infrequently used core projects
• IDE Primary: any IDE projects you are directly working on
• IDE Secondary: product, platform and other infrequently used IDE projects
• IDE Dependencies: IDE projects used only to satisfy dependencies

Running Overture in debug mode

Overture can be launched (and debugged) from within Eclipse. This is sometimes called tethered mode. In order to launch Overture in tethered mode follow these steps:

1. Go to Run ==> Run Configurations
2. Create a new Eclipse Application configuration
3. Choose Run a product and select org.overture.ide.platform.product
4. In the Plug-ins tab make sure that you tick Validate plug-ins automatically prior to launching.
5. You can also use this tab to customize which plug-ins you actually want to run, but it's easier to select all workspace and enabled target plug-ins.

Troubleshooting

Artifact has not been packaged yet:

This error will show up in Eclipse after importing or updating IDE projects It is, unfortunately, common and recurring. To solve it, perform the following steps:

1. Right-click the project in error and select Maven ==> Update Project.

• You may get a jar error (see below). Ignore it for now.
• You will get a series of type and package errors. This is expected. Perform Update Project once again but this time untick Clean projects.

Note that bulk updates can cause projects to constantly cycle through the various error stages. So this fix should be applied to one project at a time.

Jar is not on its project's build path

This error can appear while doing a Maven update in Eclipse of an IDE project with a Core counterpart. Its cause is linked to the two-stage build process we use and an inability of the m2e plug-in to determine whether or not the respective core project has been built. You can simply ignore this and run the Maven update again. Also, see the error above.

Import or bundle not resolved:

This error usually means that you have some unresolved dependencies in IDE projects because you have not imported all necessary projects. Check through the error messages and MANIFEST.MF files of your projects to make sure that you have imported all of necessary dependencies. Remember that only IDE projects can be used to satisfy dependencies. Alternatively, you may need to install some of the Eclipse plug-ins mentioned in the setup section.