Modular Mind

In my last post I discussed how to best manage run configurations for Eclipse RCP applications. But there was one related topic I wanted to discuss in more detail, and that is how to manage launch arguments.

What are launch arguments?

Launch arguments are arguments that are added to the command line when you execute your application. These arguments come in two flavors:

• Program arguments – Arguments that are Eclipse-specific. For example, the -clean argument will clear the configuration area on startup.
• VM arguments – Arguments that make sense to the Java VM. For example, the -Xmx argument allows you to set the maximum heap size for the VM.

Both of these argument types can be set on the Arguments tab in the Run Configurations dialog.

Launch arguments and the target platform

We oftentimes want to apply the same launch arguments to all of our run configurations, and one way to handle that is to specify them on your target platform. On the Target Platform preference page there is a section where you can add whatever arguments you wish.

The arguments associated with a target platform will be added to run configurations generated from the Manifest Editor. They will not be added to configurations generated by the Product Configuration Editor. Also, because the Manifest Editor link does not regenerate a configuration each time, you will need to explicitly delete a configuration if you want to recreate it using new target platform arguments.

Launch arguments and products

A second way to manage arguments is to add them using the Launching tab of the Product Configuration Editor.

When you add arguments in this way, two things will happen:

1. The arguments will be added to your run configurations if you launch using the link in the Product Configuration Editor. Because this link regenerates the run configuration each time, consistent use of the link guarantees that your configuration is in synch with your product definition.
2. The arguments will also be added to your deployed application in the form of an INI file. This is a nice feature, but it means that you need to be careful when adding arguments that are only useful during development. For example, you may want to use -clean to clear the configuration area when you’re developing, but you probably do not want to ship this argument to your customers.

Launch arguments best practices

My approach is to add arguments using the Product Configuration Editor and to always launch my applications using the link in that editor. This guarantees that my run configurations are always in synch with my product definition. I also take care to not add arguments that would be detrimental to a deployed application. Some, such as -consoleLog, I consider harmless in a deployed app and I just leave those in.

If for some reason I absolutely have to add an argument that should not be deployed, I usually clean it out of the INI file during the build process. It’s pretty rare for me to have to do this, though.

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:

1. What application or product to launch, specified by id
2. Which bundles to make available at runtime
3. 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:

1. By hand (yuck!)
2. Clicking the Launch an Eclipse application link on the Overview tab of the Manifest Editor.
3. 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:

1. 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.
2. 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.
3. 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:

1. 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.
2. 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!

In this article I’m going to take you on a tour of the process I use to build a large-scale RCP application. Obfuscating an RCP application can seem like a big challenge, but it’s really not so bad.

Read the rest of this entry »

I often work with teams getting started with Eclipse RCP, and the most common complaint I hear is that it’s too hard to set up automated builds. PDE Build can be frustrating to work with because it’s a black box. Your code goes in one side and a fully branded RCP application pops out the other. But if something goes wrong inside the box, where do you start to debug?

In my opinion, the best way to work with PDE Build is to get a very simple build running in your environment. Then make small, incremental additions, verifying the integrity of the process after each change. So the immediate problem for a team becomes: How do I get that first build running?

To help with this, I’ve put together a simple feature-based RCP product build. Just download and import the sample projects. If you follow the instructions in the included readme.txt file, you should have a build running fairly quickly. Before you know it, you’ll be seeing that always elusive BUILD SUCCESSFUL message flash across your screen!

Note: If you want to run this sample build using Eclipse 3.2, you’ll need to work around a PDE Build defect. For instructions on how to do this, check out the “Problems parsing feature file in a product build” section on the PDE Build wiki page.

Update – October 6, 2009: The sample projects have now been updated to work with Eclipse 3.5.1