Automating Project-specific Eclipse Setups with Oomph

One big issue in the process of software development (especially, but not only for bigger teams) is the setup of a common IDE. There are many settings and Plugins that must be common to all project members:

  • File encodings
  • Target Platforms
  • SCM-Linking to Git/SVN/CVS/…
  • Ticket system integration
  • Database connections
  • Source code formatters
  • Build system, like Maven with specific Plugins
  • Deployment setup
  • Other Plugins (for example Spring Toolsuite)
  • … (fill in your last experiences)

The setup of a fresh workspace for new team members can take days (even if the setup documentation is good and not too old). If the team decides to change this setup, all members usually have to change their local setup manually.

Bildschirmfoto 2015-08-16 um 15.31.43

With the new Mars release, the eclipse IDE now ships with a tool that can (besides other features) reduce the time needed to initially set up a complete IDE for team members to just minutes: Oomph. Unfortunately I found the documentation not to be really helpful with this common usecase I describe here, so I hope this blogpost is bringing some light into how to:

  1. Create a setup for your project (projectXYZ.setup).
  2. Create a personal setup for you (user.setup).
  3. Let Oomph create a ready-to-work eclipse installation.
  4. Let Oomph keep the installation up to date with your setups on every start.
Create a setup for your project and a personal one (user.setup)
  1. Download the Eclipse Installer by Oomph.
  2. Use it to install some Eclipse wherever you want it. It does not really matter which Eclipse variant, we just need the Oomph setup editor, which is automatically installed by the Eclipse installer.
  3. In the fresh Eclipse, use the setup project wizard to create a project setup file (mine is projectXYZ.setup). Remember the location of this file 😉
  4. In the Setup Editor, you should at first activate the “Live validation” option in the menu bar – I have no idea why it is disabled by default. It can save some try-and-error time 😉
  5. The nodes in the Setup Editor are called Tasks. A task can be to change the eclipse.ini, to set a property, to install a plugin, import Maven projects and many more things.
  6. To include eclipse plugins, you need to have an update site and a Resource ID. The Resource IDs can be seen by “Install new Software” -> Choose the plugin to install -> click “more” (below Details) -> General Information -> Identifier.
    Right-Click on “plugins” in the Setup editor -> “New Child” -> “P2 Director”. A P2 Director Node can have Repositories (update sites) and requirements (IDs of the plugins to install from those update sites).
    Although one P2 Director node is sufficient, I like to have one P2 Director Tasks for each update site. That way, it is obvious from which update site a plugin is installed.
  7. Use the preference recorder (see below) to record preferences, then load your user.setup  (via Navigate->Open Setup->Open User). You can move and copy-paste Tasks between the two setup editors.
  8. Probably I will write some follow-ups on how to perform different other setup tasks with Oomph, this post is already quite big…
The preference recorder

Bildschirmfoto 2015-08-16 um 15.34.59

To set preferences, Oomph has a great feature: the preference recorder, which can be switched on and off by clicking on the red circle in the lower left corner of the Eclipse preference view. If it is switched on and you change some preferences, after a close of the preferences view you are asked whether these preferences should be saved. These new settings are then stored in <userdir>/.eclipse/org.eclipse.oomph.setup/setups/user.setup.

Bildschirmfoto 2015-08-16 um 15.35.57

Installing your project-specific personalised Eclipse

Try your new setup by restarting the eclipse installer (Restart, because only then it seems to reload files). Switch to advanced mode. On the first page (product selection), choose whatever product your eclipse should be based upon. On the second page, you can drag your projectXYZ.setup file from eclipse or the system explorer onto the “” top node. Double click it, so that it is shown in the three lists below. On the next page, you should check whether the plugins you chose are listed in the tasks to execute. You should also see tasks from your user.setup, as this is applied automatically by Oomph.

Bildschirmfoto 2015-08-16 um 15.37.58

Let Oomph keep the installation up to date with your setups on every start

Oomph can not only install the complete IDE for you, it can also track changes in the “.setup” files and apply them to the already installed Eclipse. To enable this feature, go to Eclipse Preferences -> Oomph -> Setup Tasks and disable the checkbox “Skip automatic task execution on startup”. If something has changed, you will see a
I tried this with plugin installations, Eclipse.ini changes and preferences, and it worked great. For this feature to work best, I suggest to use some common access URL like a webservice to distribute the project setup.

Opening the Setup with which an Eclipse was installed

In the Eclipse Menu bar you can select Navigate -> Open Setup. Then you can choose which Setup you want to open.

Using own product and project catalogs

There are many more things that can be done with Oomph. For example, your company may have several tool suites that are based upon Eclipse, each with different plugins and configurations. In this case, an own product and project catalog could provide a user experience similar to the Eclipse Installer, but just with the products of your company. Even if you do not have products, an own project catalog with your companies projects based on Oomph can provide a consistent, fast and automated setup for all your projects. You should also consult the documentation on this advanced topic.


3 thoughts on “Automating Project-specific Eclipse Setups with Oomph

  1. What’s the difference between the different setup files (user and project)? What’s a p2 director? I feel like this could been an awesome team for our dev team, but we’re using eclipse to develop web apps, but we do not know the inner workings of eclipse (p2, bundle pools etc.) and I feel like this tool is made for those kind of developers (the eclipse devs)… Which is what I dislike about this.

    Anyway, thank you for the post, it helped me a bit, although I still can’t find a tutorial with an example use case to follow…


    1. Thanks for your comment! I will try to clear some things up a bit (and maybe add another post on this topic).

      I feel much like you when you say that Oomph seems to target mostly Eclipse developers, as the documentation (although it improved much over time) is very lacking and the user interface (especially the Setup Editor) is not really self-explanatory.

      The different setups are applied at different scopes. The user setup (placed in your home directory) contains setup tasks that reflect your personal preferences like maybe enabled/disabled line numbers. The project setup can contain setup tasks that are special for your whole team (like creating a workspace and checking out a git repository). A product setting describes task that are specific to an Eclipse product (like Eclipse Luna or maybe some custom RCP application). User preferences can override project preferences and both can override product preferences.

      As I found out, a special case is formatting: although this is often told to be a use case for Oomph, Oomph does not help much here, as it doesn’t seem to work to set the workspace formatter and cleanup preferences via Oomph Preference Tasks in a project setup. In my current project, we work around this with tasks to copy the preference files that contain the formatting options to the created workspace. However, in the eclipse community it seems to be common to use project specific settings in eclipse and also have them versioned in git. With this “Oomphless” option, a new team member does not need to set workspace-specific formatter options, he/she just needs to checkout the source code (done by Oomph during setup) and Eclipse will apply the project-specific settings for every file in that project.

      Thank you for your input, maybe I will add a tutorial for an example use case.


      1. Thank you for the quick reply. I’ve been working with it for a while now and I’m starting to really like it. I still feel the documentation lacking a bit for setup authoring (you have to really try it yourself and test it a lot).

        The Oomph dev also usually reply pretty quickly when I reported bugs to them via Bugzilla, so that’s definitely a big plus!



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s