Oomph Basic Tutorial

Oomph is a project providing tooling to make the installation and configuration of Eclipse instances easier. The ultimate goal is to install and set-up an Eclipse IDE or product with a single click. Oomph also allows to share setups, as an example, you can preconfigure an IDE to work on a certain project and all developers can use this setup to get easily involved in the project.

Before we get started with the hands-on tutorial, we will introduce some basic concepts in this section.

Oomph stores configuration information in files, which can be easily shared. Those files are called “Setup Models”. There are two types of setups models in Oomph.

Product setup models define a complete Eclipse instance to be installed. This includes all plugins, which shall be contained in the Eclipse installation as well as default preferences and other basic settings. Product setups are comparable to the Eclipse packages you can download from eclipse.org (e.g. the Java EE Edition or the Modeling Edition). The difference being, you can chose exactly what should be in your product. Additionally, you can add plugins, which are not part of the release train, e.g. Checkstyle.

Project setup models define the set-up for a specific development project. This includes gut repositories, projects to be checked out, project-specific settings, etc..

Project setup models always need a product setup model first to create the Eclipse instance. However, Oomph already provides the standard Eclipse Packages as product setup models. So it is possible to just create a project setup model without the need to configure a product and vice versa.

Later in this tutorial, we will describe in detail how to specify product setup models and then project setup models. Before we cover this, a few words about how Oomph is working in general and about the different components it consists of. The following diagram shows a (simplified) overview of all relevant Oomph components. The Oomph installer (also called Eclipse installer) is a dedicated application, you can download and launch. As the name implies, it is responsible for installing Eclipse instances. Therefore, it presents the user a list of available project setup models and, subsequently, a list of available project setup models. Based on those two models, it will create an Eclipse installation for you. Additionally, it allows the user to select a few settings, which are related to the installation, such as the installation directory. We will describe the installer more in detail later.

image11

Besides the Oomph installer, Oomph also provides three “runtime” components, which are typically installed in the Eclipse instances: the Oomph Updater, the Oomph Project Setup and the Oomph Authoring tooling, including the Preference Recorder.

The Oomph Updater is responsible for keeping an existing Eclipse instance up-to-date once it has been created. Therefore, on every start-up, it checks the product setup model for any changes in the configuration. If there are any changes, e.g. a new bundle has been added, it will apply those changes automatically to the existing Eclipse instance.

The Oomph Project Setup component reads a project setup model and applies it to a created Eclipse instance. This means, it configures the Eclipse with project specific settings. Some of those settings are already applied during the installation (e.g. the addition of bundles) and are therefore taking care of by the Oomph Installer. Some project specific things can only be done, once the Eclipse instance is already created and started, therefore, the Oomph Project Setup component runs in this Eclipse instance and manages this second step. As an example, it clones specific Git repositories, imports projects, configures Mylin queries, and so on. We describe the configuration of an project setup model in more detail in the section Project Setup Models.

Finally, Eclipse instances typically contain the Oomph Authoring tooling. This tooling allows you to create and modify product setup models and project setup models. This powerful tooling requires quite a few Eclipse framework components, such as Editors and EMF. Additionally, you typically want to share setup models with Git. Last but not least, the tooling allows you to capture some settings from a running instance, e.g. using the Preference Recorder. That is the reason, the Oomph Authoring is not part of the installer, but the running Eclipse instance. This way, the installer remains a very slim component, just responsible for using setup models. We will describe the Oomph Authoring tooling more in detail in the section “The Oomph Authoring Tooling”.

Installing the three Oomph runtime components into an Eclipse instance is optional. The “Oomph updater” and the “Oomph project setup” are typically wanted to keep the installation up to date and to enable the usage of project setup models. Therefore, we recommend you always include those two runtime components. The “Oomph Authoring” is only required, if users of the Eclipse instance are expected to create and edit Oomph profiles. As this also involves the creation of user specific profiles, based on common profiles, we recommend you additionally install this runtime component.

After this basic introduction, we will describe the Oomph components in more detail. In the first section, we explain how to use “The Oomph Installer / Eclipse Installer” from an end-user perspective. In the second section, we give a general introduction about “The Oomph Authoring Tooling. Subsequently, we describe how to create “Oomph Product Setup Models” and “Oomph Project Setup Models”.

The Oomph Installer / Eclipse Installer

The Oomph installer (also called Eclipse installer) is a stand-alone SWT application, which can read product/project setup models and, based on those, install pre-configured Eclipse instances. If you only want to consume a setup model, this is the only tool you need to use. You can download the installer for your operating system here. After the installation, you can simply launch the installer. The installer supports two modes, “the simple mode” and “the advanced mode”. You can always switch between the two. Generally, the simple mode is easier to use, if you just want to install a default Eclipse, however, it does not provide all of the configuration options of the advanced mode. By default, the installer is launched in the simple mode, to switch to advanced mode, please click on the menu button in the top right corner.

image13

In the following sections, we will describe all of the options of the Oomph installer. Those, which are only available in advanced mode are marked as such.

Select Product Setup Model

On the first page of the installer, you can select the product, you want to install from a list of available product setup models. The simple mode shows a flat list, the advanced mode groups them by “product catalogue”. By default, the list contains all standard packages provided by the Eclipse Packaging Project (EPP), such as “Eclipse for Java Developers” or “Eclipse for PHP Developers”. However, you can add your own product setup models here, which is described in this section. To select a product to be installed in the simple mode, you need only to click on it. In the advanced mode, select it and click “next”.

Product Version (advanced)

The advanced mode allows you to specify the simultaneous release on which the installation will be based on, e.g. “Mars”, “Mars.1” or “Neon”. That means, that all bundles will be installed from the corresponding release update site. Please note, that a certain Eclipse version must be explicitly supported by a product setup model. Alternatively, you can also choose the “latest release”, which will use the most recent Eclipse release, or “latest”. This will use the developer builds of the upcoming Eclipse release. The simple mode will always use the latest release.

Configure JVM

Both modes allow you to configure the JVM to be used for the Eclipse installation. (second page for the simple mode, first page for the advanced mode). This JVM will be used later to start the Eclipse installation you install with the Oomph installer.

Configure installation directory

Both modes allow you to specify the directory, in which the Eclipse instance will be installed. Please note, that if you use bundle pools (see next section), the installation directory will mainly contain the executable launcher, the instance-scoped preferences, and some ressources. The bundles, of which an Eclipse installation contains will be placed in the bundle pool.

Configure Bundle pools (advanced)

Bundle pools are a concept of p2 to save space on disk if you are running multiple Eclipse instance on one machine. While different installations of Eclipse can have different setting and maybe slightly different plugins installed, they typically share the majority of bundles among each other. In order to avoid downloading and storing those common bundle several times, bundle pools provide a common directory for bundles to be used by several Eclipse instances. Instead of the installation directory, all bundles are placed in those folders then, you only need one bundle pool per Eclipse version. On startup, every Eclipse instance will access its specific subset of bundles from the bundle pool during runtime. Probably the only disadvantage of using bundle pools is that installation are not self-contained anymore. So you cannot just zip them and send them around. However, when using Oomph, sharing of Eclipse installations is no longer a typical problem. Bundle pools are activated by default and as long as you do not want to take care of the location that is stored (in a .eclipse subfolder of your home directory), you do not necessarily have to care about them. In the simple mode, it is only possible to switch bundle pools on or off, the default is “on”.

Add product setup models (advanced)

As described earlier, the Oomph installer already shows some default products to be installed. If you want to use an existing product setup model, provided by someone else, or a product you defined yourself, you need to add it to the installer first. To do that, select the “plus” icon in the advanced mode right on top of the list of product setup models. This allows you to directly add a file from disk or a URL, where the setup model is located. The latter allows you to host the setup model at any location, which is reachable over HTTP, e.g. GitHub or any web server. Therefore, it provides a very simple way of sharing product setup models. For example, we use this way to share our EclipseSource Oomph Profile. Custom profiles will be shown in the category “User Products”.

Select Project Setup Model (advanced)

After you have selected a product, the advanced mode also allows you to select a project setup model. As described before, project setup models will do project specific set-ups, such as checking specific repositories, setting up Mylin queries, as well as installing additional bundles, which are only required to work on a specific projects. As for the product list, the installer shows a list of available public setups as before, you can also add your own custom setups models on a project level.

To select a specific project, double click it in the list. Please note, that it is possible to add several project setup models to the list below, before you trigger the installation. This will execute all project setup tasks from all selected projects, so in theory, you receive an Eclipse working on multiple projects. However, as the setups from different projects might collide, this is a rather special case in practice.

Project setup models can support different “Streams”. That means, the setup for this project is sightly different for different versions or releases. If a project supports more than one stream, you can choose the stream to be installed in the table of selected projects.

Select Installation Folder

On the last page in both modes, you can select the installation folder for the Eclipse instance to be installed. In this folder, Oomph will create the launchable allowing you to start the installed Eclipse as well as instance specific resources and settings. Please note that if you use bundle pools, the installation directory will not contain the bundles of which the installation consists, they will be retrieved from the respective bundle pool instead (on start-up). The simple mode also allows to create a desktop and menu entry to start the installed instance. In the advanced mode, you must directly start the launchable in the installation folder or create the shortcut yourself.

Project specific settings (advanced)

In the advanced mode and if you have selected a project specific setup model, you might need to enter some project-specific variables. Those are defined in the project setup model and can therefore differ from project to project. A typical example is the user name, which is used to access git repositories. If you are in doubt about an available variable, you should contact the party, who provides the project setup model you want to install.

The Oomph Authoring Tooling

The Oomph authoring tooling enables you to create and modify product and project setups models. It is implemented as a plugin for the Eclipse IDE and is already part of most Eclipse packages as well as the Eclipse Oomph profile. Alternatively, you can download and install it from the Oomph update site (Feature Oomph setup). Once you have installed the tooling, it allows you to create Oomph artifacts with the default Eclipse “New” wizard. To version them, you can add them to an empty project, which is shared in a git repository. In the following two sections, we go in detail about product setup models and project setup models.

Both artifacts can be opened in a tree-based editor. It displays a hierarchy of elements, which specify the setup model in detail. In the following two sections, we describe the most relevant elements of a product setup model and a project setup model.

image03

Both, product and project setup models are extensively based on using variables. This improves the maintainability of Oomph profiles and also allows you to connect generic profiles to user specific settings. As an example, a project setup needs to know about the JRE in order to be used for launching applications. When specifying a project setup model, you do not know, where the JRE of a future user is located, therefore, the profile is bound to a variable, which can then be instantiated by the later user of a profile, meaning the user can select the JRE to be used. Some variables are predefined by Oomph, for example the location of the Eclipse Git and Gerrit server.

Oomph Product Setup Models

In this section, we describe how to define a custom product setup model. To create one, right click a container project, click “new” and select Oomph => Setup Product Model. The initial wizard allows you to specify a Label, a name, a description, the release train your product is based on, an installable unit ID, the container project, and a file name. The wizard focusses on the use case, where you want to specify a custom product based on Eclipse. Therefore, it will configure the product to contain basic features such as the Eclipse platform, the Eclipse IDE platform and Eclipse RCP. Additionally, it will add a feature using the ID you have specified under “installable unit ID”. If you want to configure a product based on Eclipse, this ID should be the ID of the root feature of your product. In the following, we describe the use case to build a custom IDE as we have done for the EclipseSource Oomph Profile. In this use case, we just bundle existing plugins for the Eclipse IDE, we do not provide any custom features. However, technically, both use cases are working the same and the way you specify them is similar. As a reference and to see the final result of this tutorial, you have can a look at the EclipseSource Oomph Profile, which can be found on github.

image04

Once you have create the product setup model, it is opened with the Oomph editor. As you can see in the following screenshot, the initial model contains one root node and three elements on the first level. The root node represents the product itself. In its properties, you can adapt the Label, the id, and the description. This information will be shown in the Oomph installer, when users select your product.

The node “BrandingInfo” contains two key/value pairs, which specify the name of the folder, in which the product will be installed. This is not the installation folder name, which can be specified in the installer before the installation. Oomph will create a subfolder in the installation folder that is named as specified in the product setup model. For our use case, we leave those values to the default “eclipse”. The next element “Installation” is required by Oomph, but can be ignored for now.

image09

The fourth element “Mars” is a “Product Version”, it has been created because we selected “Mars” in the initial creation wizard. Product versions allow us to maintain a product setup model for several Eclipse release streams in parallel, e.g. for Mars and Luna. At the moment, our product just supports Mars. You can add additional product versions with a right click on the product (the root node). If we unfold the Mars product version node, we see the core element of the initial product, a “P2 Director” element. This element specifies a list of features, which will be installed into our product.

image07

In the following sections, we will describe the above mentioned elements as well as the other most relevant elements in more detail. Please note that this is not a complete list, we just focus on the core features of Oomph. If you feel something is missing, please contact us, as we might be able to extend this tutorial in the future.

Products and Product Versions

The root of every product setup model is a “product”. It can contain elements that describe steps to be taken during the installation. A product contains a “product version”. Product versions are like branches or release streams for a product, this allows you to maintain a product in multiple versions. A typical use case is to maintain a product for several Eclipse major versions, e.g. Luna, Mars and Neon. Users of your product setup model can select which product version they want to install in the Oomph installer. Product versions can be created directly as children elements of a product. If you work with product versions, all following elements can be either created in the product or a sub element of the product version. Elements in the product (root) will affect every installation of the product setup model. Elements underneath a product version will only be applied if the user has selected this specific version. So at the end, product versions will inherit everything from the containing product and can add version specific things. Both, products and product versions allow us to define a name and a label.

P2 Director

As one of the most important elements, the “P2 Director” specifies the content of your Eclipse installation. More precisely, the features and bundles to be installed. As described before, P2 directors can be added to the product or a specific product version only. To add bundles and features, the P2 director element supports two sub elements, which can be added as children elements.

Additionally, P2 director elements can specify a label, which is shown to the user during the installation for information purposes. The template of product setup models uses variables to specify the label: ${scope.product.label} (${scope.product.version.label}). This will resolve to “Product Label” + “Product Version Label”, e.g. “My Product Mars”. The usage of the second variable only makes sense, if the P2 director is placed inside a product version.

Oomph Project Setup Models

In this section, we describe how to define a custom project setup model. In order to create one, right click a container project, click “new” and select Oomph => Setup Project Model.

The wizard allows you to select between three templates: Eclipse Project, GitHub Project, and Simple Project. If you choose Eclipse or GitHub, the wizard will assist you in adding your specific repository from which you plan to check the sources. In turn, this will save configuration effort. In the following, we will assume you set-up a project setup model for an Eclipse project, however, this can easily be transferred to GitHub or any other hosting service. The initial wizard allows you to specify a Label, a name and a description for your project.

If you use the Eclipse or GitHub project template, you just need to specify the Git path within the Git repository, as Oomph already knows the URL for the repository itself and will use a variable to define it. For Eclipse projects, you can configure under “Remote URIs”, whether the repo should be accessed using Git, Gerrit or both. Based on the repository information, Oomph will be able to clone the project repository, if you execute the project setup model later on.

The next thing to consider is configuring the projects to be imported to your Eclipse workspace after the repo has been cloned. There are two ways of configuring it, please see the next section to learn more about them. This also covers the next two properties in the initial wizard to configure an “installable unit”.

The final option in the initial wizard is selecting the default JRE for you project.

image00

After finishing the wizard, the Oomph authoring tooling creates a pre-co