13 September 2009

Eclipse RCP Application Branding

A while ago, I figured out how to use the branding features in Eclipse to make the About dialog in my Anaconda Workbench show all the included features with the appropriate icons and other information. This was based on Eclipse 3.4, and here is a screenshot of the results:

Clicking on Feature Details, you get a list of all branded features included in the product:

Not every feature is branded by default. You have to associate a branding plug-in to a given feature and include an about.ini file and an optional icon in the branding plug-in. I won't go into details for this Eclipse 3.4 example, seeing that things have changed for Eclipse 3.5, and the rest of this post relates to Eclipse 3.5.

What's new in 3.5

The Feature, Plug-ins and Configuration Details buttons have gone, now there is just a single Installation Details button. To see the installed features, click on one of the feature icons to open a dialog listing all features branded with the same icon.

(Actually, I'm not quite sure whether or not the icon name is the grouping criterion, but I guess so from my experiments.)

Selecting a feature from the list and clicking on Plug-in Details, you can display all plug-ins contained in the feature.

Things to note

Eclipse Help has just two rather brief topics on Product Branding and Customizing a product. Branding a product is straightforward if you use the Product Configuration Editor as explained in the first topic. Things get more complicated when your product contains multiple features or even third-party products.

For each feature to branded, you need a branding plug-in containing the following resources:

  • about.ini
  • about.properties (optional)
  • a 32*32 icon
Make sure to include these resources in you build.properties so they will be exported to your plug-in JAR.

In about.ini, set the following two properties:

aboutText=Anaconda Workbench for Car Navigation Databases

You can use the optional about.properties to work with language dependent variables in about.ini. Set featureImage to the relative path of your icon resource.

By default, Eclipse assumes that the branding plugin for a feature com.acme.foo is also named com.acme.foo. If you want to assign a different name, you have to explicitly declare the branding plug-in in the feature editor.

I ran into a conflict between feature branding and product branding: My top-level product Anaconda Workbench contains another product udigLite, which in turn contains Geotools, Eclipse EMF and Eclipse RCP.

udigLite is a modified subset of uDig. uDig has a top-level feature named net.refractions.udig which a contains a branding plug-in of the same name with a product definition.

udigLite originally had a top-level feature net.refractions.udig.lite containing just a subset of the uDig plug-ins, including the net.refractions.udig plug-in which cannot be left out as it contains more than just branding information.

With this configuration, I ended up with two uDig features in the feature list: net.refractions.udig.lite as expected, and net.refractions.udig, although no such feature exists in my product.

It seems that a branding plug-in containing a product definition is automatically treated as a feature of the same name. I wonder if that's a bug or a feature (pun intended).

Anyway, to remove this duplicate, I dropped my net.refractions.udig.lite feature and changed the original net.refractions.udig feature to include just the required subset of plug-ins.

Another problem I ran into is bug 280186 or bug 289300, causing each feature to be listed twice in the exported product. To supress that, you can drop the org.eclipse.equinox.ds plug-in from your product, provided your application does not depend on Declarative Services.


david said...

I've run into the same issue ... how do you drop the org.eclipse.equinox.ds plugin?

I don't declare the plugin as a dependency in my feature, plugin, or product.

Harald Wellmann said...

If your application includes the org.eclipse.rcp feature, you get a transitive dependency on org.eclipse.equinox.ds.

To avoid that, don't include the RCP feature, just list all the plugins from org.eclipse.rcp, minus o.e.e.ds, in your own feature.