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.

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!

Selecting an obfuscator

The first challenge is selecting the right tool for the job. The most important feature of an RCP application obfuscator (assuming it does a good job at obfuscating!) is that it can obfuscate multiple jars at the same time. Some tools expect you to obfuscate one jar at a time, and unless your RCP application contains only one jar, these tools will not work.

In my case, I chose a tool called Zelix Klassmaster. This obfuscator handles multiple jars, and also integrates nicely into a build process managed by Ant scripts. The process I describe is based on Klassmaster. I’ve also heard that the open-source obfuscator ProGuard can handle multiple jars at the same time, but I haven’t tried this tool myself. If anyone manages to get a similar process working with ProGuard, I’d appreciate it if you’d let me know.

The big picture

The big picture for an obfuscation process includes all of the jars that are distributed with your application. These jars can then be divided into two categories: those that will be obfuscated and those that will not.

• Obfuscated – Jars that make up your own proprietary plugins
• Non-Obfuscated – All third-party plugins and libraries, including the RCP plugins. This category may also include your own plugins that cannot be obfuscated for one reason or another.

Zelix Klassmaster operates on these two sets of jars, loading them all into memory at the same time and then obfuscating only those in the first category.

The build process

An obfuscation process begins after an RCP product has been exported either by the Product Export Wizard or by an automated build process. The exported application is then obfuscated using an Ant script and a related Zelix script. The Ant script controls the process, and it has three functions:

1. Create lists of jars and other parameters which are then substituted into the Zelix script.
2. Execute the obfuscate Ant task provided by the Zelix obfuscator.
3. Replace the original plugin jars with the new obfuscated jars.

In the obfuscate Ant task, Zelix loads all of the plugin jars into memory and then obfuscates those in the list to be obfuscated. These jars are placed into a new folder (in my case a folder called “obfuscated”). These jars are then merged back into the plugin directory of the application.

Of course, if your plugins are not exported as jars, then this process will be a little more involved. Another good argument for migrating to the new packaging structure.

Excluding package names – choosing a naming convention

Exclusions are one of the trickiest part of obfuscating any application, and in particular an RCP application. A good general rule of thumb is that any class referenced in an extension or extension point should be excluded. This doesn’t mean that the code in the class won’t be obfuscated, but that both the package and class names associated with the class need to be excluded. I’ll deal with class names in a bit, but first I’d like to address the issue of package exclusion.

The important thing about package exclusion is that when you exclude a package name that is deep in your package hierarchy, you are required to exclude all other packages above it. This can make it difficult to exclude packages deep in your hierarchy without abandoning package name obfuscation entirely.

The solution I’ve come up with is to make a clear distinction between obfuscated and non-obfuscated packages in the package naming conventions I use. It turns out that this convention fits nicely with another naming convention used in the Eclipse code itself that separates code making up the public API from internal code. Basically, package names that can be obfuscated are always considered to be “internal” packages and will never contain classes referenced by extensions or extension points. Public packages are excluded from package name obfuscation and may contain excluded classes.

To make this convention as useful as possible (to allow as many packages to be obfuscated as possible), this distinction between public and internal needs to be made very high in the package structure. My convention differs from the Eclipse convention in that I make this branch even before the plugin name portion of the package structure. Here is an example of the convention I use.

• Public package – com.marketcontours.plugin-name.subpackage
• Obfuscated package – com.marketcontours.internal.plugin-name.subpackage

Of course, only public packages can be included in the “Exported Packages” list for a plugin. If you specify a package that will be obfuscated, the plugin will not be able resolve the package name at runtime. This is just one more reason to align the concepts of public/internal packages and non-obfuscated/obfuscated packages. And finally, by maximizing the amount of classes in internal packages (which is a good thing to do for many reasons), we can keep the amount of unobfuscated package names to a minimum.

Excluding class names – a new properties file

The second challenge is to exclude the names of classes and interfaces referenced by extensions and extension points. I’ve found that the easiest way to do this is to track the exclusions at the plugin level with a new properties file called obfuscation.properties. Whenever I need to add a new exclusion, I put it into this property file, and then at build time these exclusions are combined by Zelix into a master exclusion list. The exclusion format I use is particular to Zelix, and is meant to exclude both the package and class names of the classes in question. To see the details of what the exclusions look like, check out the sample properties file included in the download below.

Remember that you need to include any class referenced in either your plugin.xml or manifest.mf files. This includes the Plugin (or Activator) class, if you use one.

Also, for now, each obfuscation.properties file must be added by hand to the the Zelix script. So every time you create a new plugin, you’ll need to edit the script. One area for improvement would be to have the Ant script create the list of properties files at build time and substitute them into the Zelix script.

Obfuscation and localization

There are a few extra gotchas that need to be handled when obfuscating an RCP application. The main one is that your localization classes (if you are using the new NLS class) need to be excluded from obfuscation. Fortunately, this can be done with one exclusion in the Zelix script:

exclude *.* + extends org.eclipse.osgi.util.NLS;

This line causes any class that extends the NLS class to be excluded from obfuscation.

A second issue also relates to NLS classes. When Zelix does flow-control obfuscation (for more information on this feature, see the Zelix site), it adds a static variable to various classes. This is usually not a problem, but with NLS classes it is. The NLS static initializer attempts to resolve the these static variables which it thinks are localized strings, and this initialization fails for these new variables added by Zelix. This doesn’t cause visible runtime problems, but it does pollute the logs. But again, this problem can be solved by adding a single exclude to the Zelix properties file:

obfuscateFlowExclude *.* extends org.eclipse.osgi.util.NLS *;


Try it for yourself

That ends this brief summary of my obfuscation process. If you would like to try this out for yourself, you can download the scripts that I use. Applying them to your own build process should be pretty straightforward, but if you have any questions, feel free to ask me questions.

Download obfuscation scripts

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