× Home Tutorials Training Consulting Products Books Company Donate Contact us









NOW Hiring

Quick links

Share

Eclipse RCP product deployment. This tutorial describes how the product configuration file and the deployment process of Eclipse RCP applications. It is based on Eclipse 4.5 (Eclipse Mars).

1. Product configuration file

1.1. The Product configuration file and the application

A product configuration file (in a shorter form this is called: product ) defines the configuration of an Eclipse application. This includes icons, splash screen and the plug-ins (directly or via the usage of features) which are included in your application.

A product always points to one application class. The default application for Eclipse RCP applications is the org.eclipse.e4.ui.workbench.swt.E4Application class which should be sufficient for most scenarios. In case customers want to adjust the default Eclipse initialization logic they could also provide their own implementation, such implementation must implement the IApplication interface.

A product is a development artifact and is not required at runtime.

1.2. Creating a new product configuration file

A product is typically created in a separate project. In the Plug-in Development perspective you can create a new product configuration file via a right-click on a project and by selecting New ▸ Product Configuration.

1.3. Using the product editor

You can edit the product file via a special editor. The product extension and the containing plug-in can be defined in the Product Definition section.

Product extension definition

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. Both settings are highlighted in the following screenshot.

Product definition file show the overview tab

It is possible to enter an ID for the product. Avoid using the same ID for the product as for a plug-in as this might create problems during a product export. Convention is to add the .product extension to the ID.

On the Contents tab you can define the set of plug-ins or features which are included in the product, e.g., the plug-ins that are included if you start or export your product.

1.4. Splash screen

The Splash tab allows you to specify the plug-in which contains the splash screen. The name is predefined as splash.bmp and it must be located in the root of the plug-in directory. Therefore, you need to put a file called splash.bmp file into the project main directory. Currently Eclipse supports only Bitmap (.bmp) files.

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.5. 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.6. 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.

2. Deployment of your application

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

2.2. Exporting via the product file

Select your product configuration file to export your application. Select the Overview tab and click on the Eclipse Product export wizard link. In the wizard you can specify the target directory for the export via the Directory property in the Destination group/section. The export wizard is depicted in the following screenshot.

pdeexportwizard10

The Root directory property can be used to specify a sub-folder in the destination which contains the complete exported application. This is useful, if you export the product as an archive file.

The resulting directory can be shared with others, typically as an archive (zip) file. The export dialog allows you to create an archive file directl.

If the Generate p2 repository option is selected, an (p2) update site is generated in a repository folder. This folder can be used to update the Eclipse RCP application via the p2 API.

If you transfer the content of this directory to another machine (with the same architecture, e.g., Linux 64 bit), your application can start on this machine. Of course, the correct Java version must be installed on the target machine.

2.3. Defining which artifacts are included in the export

The artifacts which are included in an export are defined by the build.properties file of the plug-in. Eclipse provides an graphical editor for this file.

Eclipse adds the compiled Java classes by default. Other files must be added manually, e.g., icons or splash screen images.

An Eclipse application started from the Eclipse IDE has access to all resources available in the IDE. But to make them available in the exported application you need to select them in the build.properties file.

It is good practice to include new required resources immediately in the build.properties file. This avoids errors after the export of your application.

2.4. Mandatory plug-in artifacts in build.properties

Make sure the following items (if available) are included in each plug-in of the exported application
  • META-INF/MANIFEST.MF

  • plugin.xml

  • other static files, e.g., icons, splash.bmp, etc.

  • Application.e4xmi

  • CSS files

  • OSGi service definition files

  • model fragments

  • translation files

The screenshot below shows the build.properties file for a plug-in with most of these components.

buildproperties10

2.5. Common product export problems

2.5.1. Problems with the export and log files

During the export or the start of the exported application you may encounter problems. If your application got successfully exported but cannot be started you find a log file ending with the .log extension in the configuration folder of your application. This file contains the error you encountered.

Alternatively the export process may fail. In both cases you can use this chapter as reference to try to find and fix the reason for the failure.

2.5.2. Export problem number #1: export folder is not empty

The most common problem is that the folder to which you export is not empty. If you export to a certain folder, ensure that the folder is empty. Exporting twice to the same folder may create file locks or results in error messages reporting version conflicts.

2.5.3. 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.eclipse.equinox.ds 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.

2.6. Export for multiple platforms via the delta pack

The delta pack contains the platform specific features and plug-ins which are required to build and export Eclipse applications for multiple platforms. It also includes binary launchers for all platforms in the org.eclipse.equinox.executable feature.

2.7. Including the required JRE into the export

You can also deploy your own RCP application bundled with a JRE to make sure that a certain JRE is used. An Eclipse application first searches in the installation directory for a folder called jre and for a contained Java-VM. If it finds one, then this JRE is used to start the Eclipse application.

To include the JRE from your running environment, select the Bundle JRE for this environment with the product flag on the Launching tab of your product configuration file.

2.8. Headless build

A headless build is an automatic build without user interaction and without a graphical user interface. It can be triggered from the command line. Typically, the build is automatically done via an additional software component called the build server which does so in a clean (and remote) environment.

Different solutions exist to do a headless build. Currently the most popular approach for building Eclipse RCP applications is based on Maven Tycho. Describing a headless build is beyond the scope of this description but you can see the online Maven Tycho tutorial for an introduction into headless builds for Eclipse RCP applications.

An example for a build server would be the Jenkins continuous integration (system). See the online Jenkins tutorial for an introduction into the setup, configuration and usage of Jenkins.

3. Exercise: Export your product

3.1. Export your product

Use the product file of your com.example.e4.rcp.wizard plug-in to export your Eclipse application.

Export product

Enter a new directory in the Directory field. If in doubt use the Browse button to find a valid directory. The following screenshot shows an example under Ubuntu.

Selecting the output directory in the product export dialog

Press the Finish button to start the export.

The exported directory should be empty. If you export twice to the same directory, delete its content, otherwise the export fails with a dependency conflict.

3.2. Validate that the exported application starts

After the export finishes check the Root directory folder in the Directory folder.

A double-click on the native launcher starts your application. Ensure that you can start the application from your exported directory.

If you face issues during the product export, check the list of common export problems from Common product export problems and try to solve the problem.

3.3. Using a static splash screen

Add a splash screen to your application. For this create or download a splash.bmp bitmap file. You find an example under the following URL: Example splash screen.

Add the splash.bmp file to the main directory of your application. You can copy and paste it into the Package Explorer view. If you add files outside of the Eclipse IDE, you need to Refresh (via F5) your project in the Package Explorer view, to see the file in Eclipse.

Afterwards, your project should look like the following screenshot.

Adding a splash bmp file
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

Export your product again and ensure that the splash screen is also shown if you start the exported application.

Make sure that the target directory of the export is empty before you start the export. See Common product export problems for details.

3.5. Change launcher name

The Eclipse export wizards uses eclipse as default for your application launcher name, e.g., on MS Windows this results in an eclipse.exe launcher file.

Change this launcher name to mywizard on the Launching tab of your product configuration file.

Change launcher name

Export your application via the product file again and validate that the launcher name has changed. Ensure that the directory you export to is empty before the export.

4. Exercise: Create a feature based product

4.1. Create a feature project for your generated RCP application

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

Creating a feature

Press the Finish button on this first wizard page.

4.2. Include your plug-in into the feature project

Include the com.example.e4.rcp.wizard plug-in into the new feature. For this open the feature.xml file, select the Plug-ins tab and press the Add…​ button.

Include plug-in into a feature

4.3. Change the product configuration file to use features

Open your product configuration file and select the Overview tab. Select the option that it is based on features as depicted in the following screenshot.

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 com.example.e4.rcp.wizard.feature feature to your product with the Add…​ button.

Add the org.eclipse.e4.rcp feature also with the Add…​ button.

Afterwards, press the Add Required button. This adds the dependencies of the org.eclipse.e4.rcp feature to the product.

Switching to features in the product configuration file

Ensure that you have the four features from the screenshot included in your product.

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 have included all four features

  • 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. About this website

6. Eclipse product and export resources

6.1. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2016 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.