This tutorial describes the product configuration file and the deployment of Eclipse applications. It also covers features.

1. Product configuration file

1.1. Overview

A product configuration file (product) defines the configuration of an Eclipse application. This includes icons, splash screen and the plug-ins or features included in your application.

The Eclipse IDE allows to create new product files via File  New  Other  Plug-in Development  Product Configuration and provides an editor to easily change the file.

A product always points to one application class. The default applications for Eclipse applications are:

  • org.eclipse.ui.ide.workbench for Eclipse IDE based applications

  • org.eclipse.e4.ui.workbench.swt.E4Application for Eclipse RCP applications not related to the IDE

Product extension definition

It is also possible to use custom applications, which implement the IApplication interface.

On the Overview tab of this editor, you can start the product. Pressing the Synchronize link writes the relevant product configuration information into the plugin.xml file.

On the Contents tab you define the set of plug-ins and features which are included in the final application.

1.2. Splash screen

The Splash tab allows you to specify the plug-in which contains the splash screen.

Launcher splash screen image can be in any of the following formats: PNG, JPG, GIF and BMP. Transparency and animation are not supported.

The name is predefined as splash.EXTENSION and it must be located in the root of the plug-in directory. Therefore, you need to put one of the following files into the project main directory:

  • splash.png

  • splash.jpg

  • splash.jpeg

  • splash.gif

  • splash.bmp

Show the tab splash from the product configuration file

The predefined name and location of the splash screen image can be changed via the osgi.splashPath parameter, the file name can be changed with the -showsplash path_to_file.

1.3. Icons, launcher name and program arguments

You can configure the launcher name and icon for your product. The launcher is the executable program that is created during the deployment of the product. A launcher is platform specific. For example, the default launcher is called eclipse.exe on the MS Windows platform. This launcher has also an icon associated with it. To change the name and the icon, select the Launching tab of your product configuration.

Here you can specify the file name of the launcher and the icon which should be used. Make sure the format of the icons is correct, otherwise Eclipse will not use them.

The icon configuration depends on the platform you are using. Eclipse allows you to export your application for multiple platforms and uses the correct ones based on your product configuration.

In the Launching Arguments section you can specify parameters for your Eclipse application and arguments for the Java runtime environment. Program Arguments are parameters passed to the Eclipse application.

Highlighting the section where the icons are maintained.

1.4. Product configuration limitations

Currently the splash handlers, which can be registered via the Customization part of the Splash tab are not supported by the Eclipse 4 standard. Also, the configuration in the About Dialog and the Welcome Page section on the Branding tab is not directly supported in Eclipse 4 RCP applications.

1.5. Deploying a runnable application

Earlier releases of Eclipse supported a manual export via the product file and these options are still present in the user interface. Unfortunately this does not work reliably in newer releases.

Therefore, you are advised to setup a Maven Tycho command line build for building and deploying your applicatioin. With the latest Tycho version setting up a build for a small RCP application can be done within a few minutes.

2. Using features

2.1. What are feature projects and features?

Using the Eclipse wizards you can create feature projects, similarly on how you create plug-in projects. An Eclipse feature project contains features.

A feature describes a list of plug-ins and other features which can be seen as a set of related components. It also has a name, a version number and in most cases a license information assigned to it.

A feature is described via a feature.xml file. The following listing shows an example of such a file.

<?xml version="1.0" encoding="UTF-8"?>
<feature
      id="com.vogella.eclipse.featuretest.feature"
      label="Feature"
      version="1.0.0.qualifier"
      provider-name="vogella GmbH">

   <description url="http://www.example.com/description">
      [Enter Feature Description here.]
   </description>

   <copyright url="http://www.example.com/copyright">
      [Enter Copyright Description here.]
   </copyright>

   <license url="http://www.example.com/license">
      [Enter License Description here.]
   </license>

   <plugin
         id="com.vogella.eclipse.featuretest.feature"
         download-size="0"
         install-size="0"
         version="0.0.0"
         unpack="false"/>

</feature>

2.2. Advantages of using features

The grouping of plug-ins into logical units makes it easier to handle a set of plug-ins. Instead of adding many individual plug-ins to your product configuration file, you can group them using features. That increases the visibility of your application structure.

Features can be used to install them into Eclipse applications and for the definition of Eclipse products. Features can also be used as basis to define a launch configuration.

Eclipse provides several predefined features, e.g., the org.eclipse.e4.rcp for Eclipse RCP applications.

2.3. Feature or plug-in based products

A product can either be based on plug-ins or on features. This setting is done on the Overview tab of the product configuration file.

On the Contents tab in the product editor you enter the plug-ins or features your products consists of.

A product does not perform automatic dependency resolution. If you add a feature to your product and want to add its dependencies, press the Add Required button.

2.4. Creating a feature

You can create a new feature project via the File  New  Other…​  Plug-in Development  Feature Project menu entry.

If you open the feature.xml file you can change the feature properties via a special editor.

The Information tab allows you to enter a description and copyright related information for this feature.

The Included Plug-ins tab allows you to change the included plug-ins in the feature. If you want to add a plug-in to a feature, use this tab. A frequent error of new Eclipse developers is to add it to the Dependencies tab.

The Included Features tab allows you to include other features into this feature. Via the Dependencies tab you can define other features which must be present to use this feature.

The Build tab is used for the build process and should include the feature.xml file. The last two tabs give access to the configuration files in text format.

3. Deployment of your application

3.1. Creating a stand-alone version of the application

An Eclipse application needs to be exported (also called: deployed) to run outside of Eclipse. Exporting your product creates a folder with all required artifacts to run your application. This includes a native launcher specific to the platforms, e.g., Windows or Linux, you have exported it for.

Earlier releases of Eclipse supported a manual export via the product file and these options are still present in the user interface. Unfortunately this does not work reliably in newer releases.

Therefore, you are advised to setup a Maven Tycho command line build for building and deploying your applicatioin. With the latest Tycho version setting up a build for a small RCP application can be done within a few minutes.

3.2. Checklist for common export problems

If the export encounters a problem please have a look into the following table for a solution:

Table 1. Problems with the product export
Problem Possible cause

Export fails

Try using an empty target directory, sometimes the export cannot delete the existing files and therefore fails.

No executable file after the export

Check the flag "The product includes native launcher artifacts" in your .product file on the Overview tab.

Product could not be found

Validate that all dependencies are included in the product. Delete an existing launch configuration and restart the product from the IDE to see if everything is configured correctly.

Splash screen or other icons are missing

Check the build.properties file to see if all required images and icons are included in the export.

Splash screen is missing

Ensure that you have entered the defining plug-in in the "Splash" tab on the product configuration file. If this is not set, the splash screen is not displayed after the export. Unfortunately, it is displayed if you start the plug-in from the Eclipse IDE.

Issues during start of the application

Check the log file in the workspace folder of your exported application to see the error messages during the start process. Alternatively add the "-consoleLog" parameter to the ".ini" file in folder of the exported application.

applicationXMI argument is missing

Check the build.properties file to see if the Application.e4xmi and the plugin.xml files are included in the export.

Service could not be found or injected

Make sure that the bundle which provides the service has the Activate this plug-in when one of its classes is loaded _ flag set. Also make sure that the org.apache.felix.src bundle is started automatically with a _Start Level less than 4.

Application ID could not be found

Define a start level of 1 and set auto-start to true for the org.eclipse.core.runtime plug-in.

Translations not available in the exported product

Ensure via the build.properties file of the relevant plug-in that the files containing the translations are included in the export.

3.3. Exercise: Using a static splash screen

Add a splash screen to your application. For this create or download a splash.bmp bitmap file.

Add the splash.bmp file to the main directory of your application. You can copy and paste it into the Package Explorer or Project Explorer view.

If you add files outside of the Eclipse IDE, you need to Refresh your project to see the file in Eclipse. This can be done via the F5 keybinding in the Package Explorer view.

The file name and the location of the file must be correct, otherwise Eclipse will not use your splash screen.

On the Splash tab of your product configuration file, define that your application plug-in contains the splash screen.

Adding splash to the product configuration file

Start your application from the Eclipse IDE and verify that the splash is displayed.

3.4. Include the splash screen into the exported application

Configure that the splash.bmp file is included into the exported application by adding it to the build.properties file of your application plug-in.

Add splash to build properties

Make sure that the target directory of the export is empty before you start the export.

4. Optional exercise: Create a feature based product

You could group your plug-ins into a custom feature. This is not required and an definitely and overhead if you only have one plug-in but in this exercise you learn how to do it.

4.1. Create a feature project for your generated RCP application

Create a new feature project called com.example.e4.feature via the File  New  Other…​  Plug-in Development  Feature Project entry. The following screenshot shows the first wizard page.

Creating a feature

Include the com.example.e4.rcp plug-in into the new feature.

Include plug-in into a feature

4.2. Create a new project for the product configuration file

While you could leave the .product file in its current location, a command line build will expect it in a separate project. Create therefore a new project of type General named 'com.example.e4.product' and move the product file to this project.

create e4 wizard product10

Also ensure that the ID field is set, this is also required for a command line build.

create e4 wizard product20

4.3. Ensure you the product configuration file allows to use plug-ins and features

Ensure that the .product file is open. Select the Overview tab and ensure the plug-ins and features option is selected.

Switching to features in the product configuration file

4.4. Add the features as content to your product

Switch to the Contents tab in your product editor. Add the following features to your product via the Add…​ button.

  • com.example.e4.feature

  • org.eclipse.e4.rcp

The Include required Features and Plug-ins automatically will include the dependencies of the e4 feature.

4.5. Start the application via the product

Start your application via the product configuration file and ensure that the application starts correctly.

If the application does not start, check:

  • that you start your application via the product configuration and NOT with an existing launch configuration. This ensures that your new product configuration is used.

5. Eclipse product and export resources