Developer Eclipse Setup with Oomph

The Eclipse setup with Oomph allows to automatically create a fully configured Eclipse IDE for the development of KIELER semantics. Note that we recommend installing a new instance of Eclipse even if you already have one for other purposes. There is no problem having multiple Eclipse installations on the same machine, and separate installations help prevent cross-project problems.

Prerequisites:

• Java 11 or up (use OpenJDK or download from Oracle)

Guide:

1. Go to the Eclipse download site (https://www.eclipse.org/downloads/index.php) and download the Eclipse Installer for your platform. The site does not advertise that it ships the Oomph Eclipse Installer but downloading Eclipse with the orange download button will give you the installer.
   You can skip this step if you already have the installer available on your system.

2. Starting the installer for the first time will open a window that looks like the following (if you have previously followed these steps, skip to step 4):
   

3. Click the Hamburger button at the top right corner and switch to "Advanced Mode".

4. Oomph now wants you to select the base Eclipse distribution for your development. Please use "Eclipse IDE for Java and DSL Developers". As product version we recommend to use "Latest Release (...)". Since 2020-09, Eclipse requires Java 11+ to run.
   Then press Next to continue with the project section.
   

5. Next, we need to register the KIELER Semantics specific setup in Oomph (only the first time you use the installer). Click the green Plus button at the top right corner. Select "Github Projects" as catalog and paste the following URL into the "Resource URI" field:
   https://raw.githubusercontent.com/kieler/semantics/master/oomph/kieler-semantics-developers.setup
   Then press OK.

6. Now Oomph lists the KIELER Semantics setup in the "<User>" directory of the "Github Projects" catalog. Check the KIELER Semantics entry. A new entry for KIELER Semantics will appear in the table at the bottom of the window. Click Next.
   

7. Now you can further configure where and how your development Eclipse should be created. Check "Show all variables" to enable all possible configuration options. You can hover over the field labels to get a more detailed explanation of their effects.

• If you already have cloned the semantics repository and you want Eclipse to use this location instead of cloning it into the new IDE environment, you should adjust the "Git clone location rule".
• Preferably, you have a Github account with an SSH key uploaded to Github. Otherwise, you should adjust the "KIELER Semantics Github repository" entry to use the https option in the pulldown menu. See adding an SSH key to your Github account.
• If the "JRE 11 location" is empty, you need to install and/or locate a JDK that has at least version 11.
  

8. Click Next to get a summary of what will happen during installation. Click Finish to start.

9. Once the basic installation is complete, your new Eclipse will start. If it fails to clone the Github repository, then you should use the back button in the Oomph dialog and change the way you are accessing the repo (ssh or https). See above.
   The setup may also fail to clone the repository via SHH if Eclipse cannot find the private ssh key that matches the public key you uploaded to Github. You can configure the location of your private key in Eclipse as follows. In the Eclipse IDE, click the menu entry Window -> Preferences (on Mac Apple-Menu -> Preferences) and navigate to General -> Network Connections -> SSH2 in the tree view on the left and configure the SSH home directory and key names according to your computer. After the repo has been cloned, you can safely close the initial Oomph dialog (if not dismissed automatically). You will see a Welcome page that you can close.

10. In the new Eclipse, it may automatically start building the project, or it may pop up an "Eclipse Updater" dialog. If neither happens, you can click the button with the yellow and blue cycling arrows in the status bar at the bottom. Oomph will perform various operations to configure the Eclipse environment. This may take some time. Wait until the setup is finished.

11. When the setup dialog is closed, your KIELER development IDE is ready. Probably, Eclipse is still compiling some code but when this is finished as well, all error markers on the project should have disappeared. If the build ends up with "Project 'xyz' is missing required source folder: 'xtend-gen'" errors, please go to Project -> Clean..., select Clean all project and click Clean. This should fix this problem. When all project are built, you can start a runtime Eclipse to test the actual KIELER end-user IDE. In the toolbar, click on the small arrow next to the green Start button. There should be an entry named KIELER in the Eclipse Application category. If not you should wait until the initial build has finished, then restart your Eclipse and try again.
    
    Click on "Run" at the bottom to start the end-user IDE.

Semantics Target Platform

The target platform defines the build environment for the developed plug-ins. In the semantics project, the target platform references specific versions of the pragmatics and ELK project.

When does this matter?

Normally you work on your branch which is relatively up to date with the current master.

But sometimes one of the following situations might appear:

• The master is changing its target platform but you want to build your branch with the old one (short-term of cause)
• You want to checkout and run an old version/commit of the semantics repository

Then you need to switch your local target platform.

Note that using the target platform definition in your development eclipse requires an installation with the correct Oomph setup.

Eclipse Development Environment for KIELER Semantics

If you followed the instructions in this guide so far, you have set up an eclipse installation with the current target platform activated.

However, the guide was updated in the past and there was a version where you may have been instructed to download the setup file onto your computer and register its local file path in Oomph. Only then you should have a look at the following section because your eclipse installation does not contain a valid target platform.

Deprecated Oomph Setup

You can detect a deprecated setup configuration by starting the eclipse installer and inspect the KIELER setup task. If it is a folder containing two setups one for semantics and one for pragmatics then everything is fine. If there is only one setup to select and the two projects are selectable as streams in the setup than you have a deprecated setup file.

Solution

The easiest way to get an up-to-date version and configuration of your eclipse development environment, is to create a new installation using the guide above. Simply commit and push your changes of your current working branch, set up a new installation following the current guide. Checkout your branch and adapt to the new target platform if necessary.

It is not recommended to keep on using an eclipse installation created with a downloaded setup file, because you are unable to receive updates of the target platform in the future.

Switching between Target Platforms

If you want to build your plug-ins against an older target platform definition, you open the Preferences window and navigate to Plug-in Development → Target Platform and select the one you wish to use.

Automatic Setup Task

The automated update task is run by Oomph at every start of your eclipse. It will update your eclipse and download new target platforms if necessary.

However, it will also activate the current target platform at each start, overriding your own selection. If you are annoyed by this behavior, you can switch off these automatic setups by selecting the corresponding property in Ooomph → Setup Tasks. Note that this will also disable automatic updates and you have to run Help → Perform Setup Tasks... manually, to receive updates of the target platform and other definitions provided by the semantics Oomph setup.