When developing Eclipse RCP applications we execute our code in the IDE using a run configuration. A run configuration is basically a collection of properties that defines how our application should be run, and these properties include:
- What application or product to launch, specified by id
- Which bundles to make available at runtime
- What program (Eclipse-specific) or VM arguments to use
And while run configurations are relatively straightforward, there can be some confusion about how to create and manage them. Hopefully this post will help.
Creating a run configuration
There are three ways to create a run configuration:
- By hand (yuck!)
- Clicking the Launch an Eclipse application link on the Overview tab of the Manifest Editor.
- Clicking the Launch an Eclipse application link on the Overview tab of the Product Configuration Editor.
Let’s ignore creating a run configuration by hand. If you prefer that approach, more power to you! But most of us find it easier to generate run configurations by clicking the editor links mentioned above.
Where some confusion arises is that the two editors in question generate run configurations in different ways. Let’s look at each editor in turn.
Creating a run configuration with the Manifest Editor
It’s possible to generate a run configuration by clicking on the Launch an Eclipse application link in the Testing section of the Manifest Editor. We can also accomplish this by clicking the equivalent toolbar button. Both options are highlighted by the red squares in the image below.
But what really happens when you click the link or button? Behind the scenes, the following logic is performed:
- The bundle associated with the manifest being edited is searched for an application or product extension. If one is found, that extension will be used when creating the run configuration.
- The current run configurations are searched, and if an existing configuration exists for the particular application or product id, then that configuration will simply be reused.
- If no matching run configuration is found, then a new one will be created. The available bundle list is created by traversing the dependency graph for the bundle associated with the manifest being edited. The arguments are taken from the current target platform for the workspace.
And what happens if you launch from a bundle that does not contain an application or product? Then the application will be set to Eclipse itself and a new instance of Eclipse will be launched with your bundles added into the mix.
This can be a source of great confusion for Eclipse RCP developers, and this is one reason that I discourage use of the Manifest Editor to create run configurations. On the other hand, it’s usually obvious if you’ve selected the wrong manifest. Your first tip that something is amiss will be the appearance of the Eclipse splash screen. If you’re not seeing your own splash screen, you’ve probably launched from the wrong manifest.
Creating a run configuration with the Product Configuration Editor
Because it’s very easy to create incorrect run configurations using the Manifest Editor, I usually suggest that developers use the Product Configuration Editor instead. The options look very similar in this editor (unfortunately at times they look too similar), and you can see them highlighted in red below.
But while the options look similar in both editors, there are slight differences in behavior. Specifically, the Product Configuration Editor uses the following logic:
- First, a new run configuration is always generated. No attempt is made to search existing run configurations for a match, and if one already exists it will be overwritten. This can be particularly important if you’ve made manual changes to your run configurations.
- The product id will obviously be taken from the product configuration file, as will the available bundles (Dependencies tab) and arguments (Launching tab). Note that arguments associated with your target platform are not used in this case.
What is the best approach?
As you’ve probably surmised, I suggest using the Product Configuration to create run configurations. Here are the two biggest reasons:
- It’s easier to make a mistake with the Manifest Editor by selecting a manifest in the wrong bundle.
- Using the bundle list generated by a product configuration ensures the same bundles will be built into your deployed application. When using the Manifest Editor, it’s very easy to get into a situation where your app works in the IDE, but not after it is built and deployed.
As an aside, it’s possible to generate your run configuration from the Product Configuration Editor and then run it later by clicking the Run button in the main toolbar or selecting it in the Run Configurations dialog. This will obviously not cause your existing configuration to get overwritten.
I choose not to do this because I prefer to treat my product configuration as the only real location for runtime properties. I’ll come back to this issue in a subsequent post, as this discussion has gone a bit long!