How to Build an Eclipse Product (Unfinished Draft)
Prose by: Wassim Melhem
Date: February 17, 2005 (aka. 3.1M5 Eve)
Introduction
This document describes how to create an Eclipse product from first principles. We will create a minimal rich client application and show you how you can easily turn it into a fully-branded Eclipse product using PDE tooling that is available in Eclipse 3.1M5.
This document is not an introduction to plug-in development nor is it an RCP tutorial. We will also assume that you are familiar with Eclipse application launch configurations, and we will not get into the details of how to implement a rich client application. Our focus will be on the aspect of turning an RCP application into a product. This includes customizing the application window, program executable, splash screen, etc. You will then see how you can test and export the product with a single click.
Requisites
For maximum enjoyment of this tutorial, you need:
Creating a Rich Client Application
1. Bring up the New Plug-in Project Creation Wizard via File > New > Project...>Plug-in Project
2. Enter the project name 'com.example.xyz' and accept all defaults. Click Next.
3. In the Rich Client Application section, choose YES. Accept all other defaults on the page. Click Next.
4. PDE provides three RCP templates of varying complexity. The Hello RCP template creates a minimal RCP application that consists of an empty window with a title. On the other end of the spectrum, the RCP mail template provides a rich template that creates a fully-functioning fully-branded product. Since we want to incrementally build a product from scratch in this tutorial, we will choose Hello RCP template. Click Finish.
5. A new plug-in project is created and the manifest editor for the plug-in automatically opens. In the Testing section of the Overview page, click on the 'Launch an Eclipse application' link to see your pre-branded rich client application in action.
6. An empty window with the title 'Hello RCP' comes up within seconds. This is the minimal application which we will use as a starting point to turn it into a product. Close it.
Creating a Product Configuration
To create and manage all aspects of your product, you need to create a new product configuration via File > New > Other... > Product Configuration.
The product configuration name must have a .product extension. Besides that, there are absolutely no other restrictions. The file can reside in any folder, in any project in your workspace.
The wizard offers you three ways to initialize the product configuration:
1. using an existing product: This option should be chosen if you have already declared the product that you want to brand and/or build. The product configuration will then be automatically filled out with all the information that is known about the product, e.g. its name, what plug-ins it needs to run, etc.
2. using a launch configuration: When you test your application as we did in the previous section, an Eclipse application launch configuration was created. Choosing this second option will copy over all relevant data into the product configuration. Data include product name, the list of plug-ins you launched with, whether you have a custom config.ini file or not, etc.
3. a minimal configuration file: If you have an application, but you don't have a product nor do you even know how to create one, this option is for you. PDE will help you build that product one piece at a time.
For the purpose of this tutorial, we will choose option 3 and click Finish.
Managing the Product Configuration
The Product Configuration editor, made with 100% recyclable Eclipse Forms, is the one place where you manage all aspects of your product.
Since we chose to create a minimal product configuration in the previous section, the file is initially next to empty. That's the idea.
We will now explore all sections of the editor as we incrementally define our product.
Product Definition
1. Enter 'My Product' as the product name. This is the name that will appear in the title bar of the application window.
2. Since we don't have a product id yet, let's create one on the fly. Press the New... button in the Product Definition section of the Overview page. The New Product Definition wizard comes up.
2. To declare a product in Eclipse, you must extend the org.eclipse.core.runtime.products extension point. The plug-in where this extension is declared is referred to as the product's defining plug-in. Choose 'com.example.xyz' as the defining plug-in, and specify a product ID.
3. Associate the product with the 'com.example.xyz.application' application. This is the Hello RCP application we created above. The application is the default entry point when the product runs.
4. Press Finish. The product ID and application are now set in the Product Definition section of the editor.
NOTE: At this point, the wizard used the data you entered to create an org.eclipse.core.runtime.products extension in the plugin.xml file of the com.example.xyz plug-in.
5. The product can be based on either plug-ins or features. In this tutorial, we are building a plug-in-based product, so leave the default as-is and navigate to the Configuration page.
Product Content
The Configuration page is where you explicitly list all the plug-ins and fragments that constitute the product. This list is typically a minimal list containing the plug-in defining the product/application and all its pre-requisites.
1. Press Add... and select com.example.xyz, i.e. the plug-in where our product and our application ares defined.
2. Press Add Required Plug-ins.
Configuration File
Upon startup, the Eclipse runtime reads a config.ini file located in a configuration/ directory at the root of the installation directory. This properties file contains data such as the product ID, what plug-ins to run, location of splash screen, etc. It is therefore recommended that you let PDE generate this file for you during the export process. You may alternately specify a custom config.ini file that PDE will copy as-is when exporting the product.
Launching Arguments
You have the option to specify the program and vm arguments you want your product to be launched. Specify these arguments in the Launching Arguments section. These values will be copied over to your launch configuration when you test your product.
When you export your product, a file named <launcher>.ini, where the <launcher> is the name of your product launcher, will be created by PDE and it will include all the specified program and VM arguments.
Branding
In this section, we will give the product its identity by customizing the splash screen, the application window, the About dialog and the program launcher. This customization is done on the Branding page of the Product Configuration editor.
Import the Images
1. Download images.zip into a temp directory, e.g. D:\Temp. This ZIP file contains the splash image, the About image and all other images to be used in the next sections.
2. Bring up the Archive import wizard via File > Import...>Archive file. Import the contents of D:\Temp\images.zip into the com.example.xyz plug-in.
Program Launcher
1. The launcher name is the name of the executable that will be used to launch the product. Set the launcher name to 'MyLauncher'.
2. Set the root directory of the end product to be 'MyProduct'. If left blank, the root directory will be named 'eclipse' when the product is built.
3. You can also customize the icon associated with the launcher. The requirements for this customization varies per platform. Samples were provided in the zip file we have just imported. Complete the rest of the Program Launcher section as below.
Splash Screen
The splash screen appears when the product is launched. The splash must be a BMP file and must be named 'splash.bmp'. This file's default location is at the root of the product's defining plug-in. We have just imported a sample splash.bmp into the root of the com.example.xyz plug-in project, therefore the splash screen section of the editor can be left blank.
Window Images
You can specify two GIF images that will be associated with the product. On Windows, the 16x16 image that will appear in the title and task bars, while the 32x32 image will appear in the Alt-tab application switcher.
About Dialog
Both the text and image of the About dialog are customizable to display information about your product. The image must not exceed 250x330 pixels in size.
Testing Your Product
To test the product, go back to the Overview page.
1. Before you launch the product, you have to synchronize. So why synchronize and what does synchronize do? It is important to note that the product configuration is the central place that manages all aspects of your product at development time only. It will NOT end up in the final product and it is NOT read or understood by the Eclipse runtime. So before you launch or export the product, you have to synchronize the product configuration with the product's defining plug-in. This will copy all the changes you made in the product configuration into the product's defining plugin's manifest (plugin.xml) file. This includes product id, application, splash screen location, window images and the About dialog data.
2. Test the product by clicking on the 'Launch the product' link.