To start working on KIELER, you will need an Eclipse installation, configure it correctly, and import all the necessary projects. Choose one of the options below and run with it.
Which Java Version Do I Need?
Java 8. We're quite fond of lambda expressions and the stream API.
This is the easiest way, and is recommended for everyone.
- Go to this site 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.
- Start the installer. You should see something like this:
Click the Hamburger button at the top right corner and select Advanced Mode. Why? Because we're computer scientists, that's why!
Oomph now wants you to select which Eclipse distribution you want to use to develop KIELER in. Select the Eclipse Platform. Afterwards select the Product Version and click next.
In Product Version, you should not select the newest Eclipse distribution available because the KIELER Team might not have had time to adjust the code base and dependencies to the newest Eclipse API. As rule of thumb, you can select an Eclipse version that has been released a year ago. Eclipse Photon is known to work in June 2019.
Next, we need to tell Oomph how to setup an Eclipse ready for KIELER development. Click the Plus button at the top right corner. Select Eclipse Projects as Catalog and insert the following URL into the Resource URI field, then press OK.
In an earlier version of this site, you might be instructed to download the KIELER setup file and register the local file path. This setup file is now obsolete. Please do not use it anymore and register the new one. You might also want to remove it from the list and delete the downloaded setup file but this will cause errors in all Eclipse installations created with this setup. Hence, be careful and don't force me to say: I told you so!
Now Oomph lists a KIELER folder in <User>. Double-click on KIELER Pragmatics or KIELER Semantics to configure your setup. This will cause an item to appear in the table at the bottom of the window. The Stream column entry can be edited to choose on which state/branch you want to work. Once you're done, click Next.
Oomph now asks you to enter some more information. You can usually leave the settings as is, except for the Installation folder name. This will be the directory under which all your Eclipse installations installed with Oomph will appear, each in a separate sub-directory. Select a proper directory and click Next.
But... I Already Have Git Repositories
By default, the Oomph setup will clone all required Git repositories for each Eclipse installation, which takes up disk space and results in unnecessary duplication. You can change that by changing the Git clone location rule to Located in the specified absolute folder location and then setting the locations for each cloned repository accordingly.
Oomph will clone the repositories into the given folder, or use existing repositories.
Separate Installations?This is the part that veteran Eclipse developers will find strange. In the Oomph world, there is no one big Eclipse installation anymore. Instead, we simply use one installation for each project we're working on, completely self-contained in a folder that also contains the workspace and all required Git repositories. If something goes wrong, simply delete the whole folder and install a new Eclipse using Oomph.
Having multiple Eclipse installations isn't even a problem in terms of disk space. Each installation is very lightweight, because all features and plug-ins used are saved in a centralized bundle pool (usually something like
~/.p2), which keeps each installation very small.
- Oomph now displays a summary of what will happen once you click Finish. Ignore it and click Finish.
- Once the basic installation is complete, your new Eclipse will start (at this point, you can safely close the Oomph dialog). Now, Oomph will try (and probably fail) to clone all required Git repositories. The Eclipse window will look something like this (once you've closed the Welcome page):
Note the icon at the bottom with the error marker. It tells you that something went wrong during the Oomph setup.
- The problem is that Eclipse doesn't know which SSH key to use to clone the repositories. Go to the Eclipse preferences and navigate to General -> Network Connections -> SSH2. Add the private key you want to use to connect to our repositories and click OK.
- You will now need to retry the failed Oomph setup steps. Either click on the Oomph setup icon at the bottom of the Eclipse window (if it's still there), or select Perform Setup Tasks from the Help menu. The dialog shows the failed setup tasks. Click Back, Next, and Finish to retry them all.
Manual Installation (Deprecated)
If you want to install Eclipse on your own computer without using the Oomph setup, just expand the installation guide below. On Windows, double-click the
eclipse.exe found in the installation directory. On Linux, execute the
eclipse executable found in the installation directory. On second thought... Why would you want to do that? Spare yourself the trouble and just go with Oomph. In fact, we don't even know if the information below are still up-to-date. Probably not. Go with Oomph. Seriously.
The first step in getting your own Eclipse installation is to download Eclipse Luna 4.4.1 from the Eclipse download page. The download page offers several different variants of Eclipse; you want the Eclipse Modeling Tools, as they come with many of the features required for KIELER development already installed. Once Eclipse is installed and started, you need to install the remaining features. For each of these steps, fire up the software installation dialog by clicking Install New Software... from the Help menu.
- From the Luna update site (should already be in the Work with list), choose the following components:
- Xtext Complete SDK
- MWE 2 language SDK
- MWE 2 runtime SDK
- If you are going to be working in the Semantics project, you may also have to install the following from the Luna update site:
- Xpand SDK
- MWE SDK
- Xpand SDK
Now open up the Eclipse Marketplace from the Help menu and install the following plug-ins:
- Checkstyle Plug-in
- FindBugs Eclipse Plugin
After everything is installed, restart Eclipse and configure your installation according to our configuration guidelines.
If you are in charge of creating a new reference target platform, make sure to consider the below.
Some projects require a bunch of more esoteric dependencies. For each one of them, make sure you actually work with a given project and then install the required dependencies only if necessary.
- SVG export functionality is based on the Batik Swing feature from the Orbit update site. Make sure to install version 1.6 of the plug-in, not version 1.7.
- If you want to work on the Graphiti integration of KIELER Layout, install the Graphiti SDK Plus from the Kepler update site.
- If you want to work on KlighDning , install the Jetty bundles from the Jetty update site. Currently we are using version 8 (which should be included in the Luna Release).
- If you want to work on KWebS , install the JAX-WS Tools from the Kepler update site.
- If you're interested in e4 application development, install the following from the e4 update site: (If you don't know what e4 application development is, odds are you won't need these.)
- Eclipse e4 Tools (Incubation)
- We originally also installed E4 CSS Spy (Incubation), but it installed keyboard shortcuts that somehow conflicted with Eclipse's built-in ones. This lead to common shortcuts such as Ctrl+Z and Ctrl+Space not working properly, which is why we don't install the CSS Spy for the time being.
- If you use some code from Subversion repositories, install the Subversive SVN Team Provider from the Kepler update site. You will be prompted to install a Subversive Connector upon restarting Eclipse; select one that fits to your installed SVN version. KIELER does not use Subversion anymore.
- Some plug-ins require Papyrus to be installed, which you should probably simply google for.
- Some deprecated dependencies (we don't work with these frameworks anymore):
- Graphical Editing Framework Zest Visualization Toolkit SDK
- Graphical Modeling Framework (GMF) Notation SDK
- Graphical Modeling Framework (GMF) Tooling SDK
Regardless of the two methods you've decided on following, Eclipse may well run into problems due to lack of memory. If so, navigate to your installation directory, open eclipse.ini, and edit it to contain the following lines:
For more information about what these settings to, see this page.