How to write an Eclipse installer

How to write an Eclipse installer

Last modified 15:20 Friday June 18, 2004

Eclipse-based products need to be correctly installed on the end user's computer. Special-purpose packaging tools, such as InstallShield and RPM, are often used to build executable installers that automate installing, updating, and uninstalling. This note describes how to write an installer for an Eclipse-based product, and for separately-installable extensions to Eclipse-based products.

We assume that a product development team is responsible for providing the raw ingredients that will need to find their way to end users' computers packaged as an executable installer. The creation of executable installers is scripted, as are the install time actions needed to interact with the end user and deposit files on their computer. This note described in detail what these installers need to do and how they should work.

This note should be treated as a recipe for the person responsible for writing an installer for an Eclipse-based products. Two good reasons why we recommend all installers writers follow our recipe:

Product and extension interoperability. By behaving in standard ways, an installer for one Eclipse-based product or extension automatically works with products and extensions laid down by other installers. Otherwise the idiosyncrasies of one product's installer would require matching quirks in all extension installers that expected to work with that product.
Uniformity of install time user interaction. All installers for Eclipse-based products and extension should interact with the user in the same manner. There is nothing to having gratuitous variety in this matter.

Product installer creation script

A product installer should be self-contained - the kind of thing that could be distributed on a CD and installed on any machine with a suitable operating system.

Eclipse requires a Java2 Java Runtime Environment (JRE) to run Java code. JREs are licensed software, obtained from Java vendors. With a license to redistribute a JRE from a JRE vendor, a company can include a JRE with its product, and install it on the end user's computer at the same time as the product. The alternative is to require that a JRE be pre-installed on the end user's computer, and associated with at product install time. One way or the other, an Eclipse-based product requires a suitable JRE, and the product installer must play a role in either installing a JRE or locating and linking to a pre-existing JRE.

Assume that a JRE is to be installed with the product. A directory containing the JRE is one input to the installer creation script. Denote this directory <JRE>. This directory must have a standard JRE directory structure, with the Java executable is located at jre/bin/java.exe and the class library at jre/lib/rt.jar below the <JRE> directory. For reference, the skeletal structure of this directory looks like:

<JRE>/
jre/
    bin/
      java.exe
    lib/
      rt.jar

There are additional files (and subdirectories) in these directories; we've only shown a sample to give the general structure. Italicized names in italics are product-specific.

The second input to the installer creation script is a directory, <product head>, containing the product-specific executable launcher and any files unrelated to Eclipse. For reference, the skeletal structure of this directory would look like (italics indicate file names that will vary from product to product):

<product head>/
acmeproduct.exe

The third input to the installer creation script is a directory, <product body>, containing the features and plug-ins developed for the product. For reference, the skeletal structure of this directory would look like:

<product body>/
eclipse/
    features/
      com.example.acme.acmefeature_1.0.0/
      feature.xml
      com.example.acme.otherfeature_1.0.0/
        feature.xml
    plugins/
     com.example.acme.acmefeature_1.0.0/
        plugin.xml
        about.ini
        about.properties
        about.mappings
        plugin_customization.ini
        splash.bmp
     com.example.acme.otherfeature_1.0.0/
        plugin.xml
        about.ini
        about.properties
        about.mappings
     com.example.acme.myplugin_1.0.0/
        plugin.xml
        myplugin.jar
     com.example.acme.otherplugin_1.0.0/
        plugin.xml
        otherplugin.jar

The fourth input to the installer creation script is a directory, <platform>, containing the features and plug-ins for the Eclipse platform itself and any third-party tools being included. This directory also includes the standard Eclipse executable launcher, eclipse.exe, (named eclipse on Unix operating environment), its companion startup.jar, and any other Eclipse platform files required to be at the root of the install. For reference, the skeletal structure of this directory would look like:

<platform>
eclipse/
eclipse.exe
    startup.jar
    features/
      org.eclipse.platform_2.0.0/
      org.eclipse.platform.win32_2.0.0/
      org.eclipse.jdt_2.0.0/
    org.eclipse.pde_2.0.0/
    plugins/
      org.eclipse.platform_2.0.0/
    org.eclipse.core.runtime_2.0.0/
    org.eclipse.core.boot_2.0.0/
    org.eclipse.core.resources_2.0.0/
    org.eclipse.ui_2.0.0/
    org.eclipse.jdt_2.0.0/
    org.eclipse.jdt.core_2.0.0/
      org.eclipse.jdt.ui_2.0.0/
    org.eclipse.pde_2.0.0/
    org.eclipse.pde.core_2.0.0/
      org.eclipse.pde.ui_2.0.0/
    (more org.eclipse.* plug-in directories)

The exact contents of the <JRE>, <product head>, <product body>, and <platform> input directories determine what files will eventually be installed on the end user's computer.

The final inputs to the installer creation script are the id and version strings for the product's primary feature; e.g., "com.example.acme.acmefeature", and "1.0.0"; and the name of the product executable; e.g., "acmeproduct.exe". For products that do not require their own product executable, this would be the path of the standard Eclipse executable launcher "eclipse/eclipse.exe". These strings have special significance to the installer, appearing in file and directory names, and in the contents of marker files created at install time.

At install time, the installer should behave in the standard manner (further details follow the list of steps):

warn user to exit all programs
introduce the product to be installed
if appropriate, ask the user for the name of the registered owner and for the license key
display the product's licensing agreement and ask the user to accept
recommend a location on the disk to install the product (but allow user to override this default)
check that a product or extension is not already stored at the specified location
ask user to confirm all details of the install
create marker file to mark root of product install
copy files to disk (see below)
if appropriate, insert name of registered owner and license key into the "about " description
create a desktop shortcut to run the product executable
create an appropriate entry to allow the user to uninstall the product
launch the product executable with -initialize option to perform all first-time processing
offer to show the product release notes ("readme" file)

If the location specified in step 5 is <install>, the installer copies all the files in the <JRE>, <platform>, <product>, and <product plug-ins> directories into <install>.

Input file Installed file
<JRE>/* <install>/eclipse/*
<product head>/* <install>/*
<product body>/* <install>/*
<platform>/* <install>/*

The marker file created in step 8 is <install>/eclipse/.eclipseproduct is used to mark a directory into which an Eclipse-based product has been installed, primarily for extension installers to locate. This marker file is a java.io.Properties format file (ISO 8859-1 character encoding with "\" escaping) and contains the following information that identifies the product to the user and distinguishes one Eclipse-based product from one another:

name=Acme Visual Tools Pro
id=com.example.acme.acmefeature
version=1.0.0

The values of the "id" and "version" property are inputs to the installer creation script; the name of the product is presumably known and hard-wired. (Products would not ordinarily access this marker file; only product and extension installers write or read it.)

Step 6 requires checking for an existing <install>/eclipse/.eclipseproduct or <install>/eclipse/.eclipseextension file. A product cannot be installed in exactly the same place as another product or extension.

After installing all files, the top-level structure of the install directory would contain the following files and subdirectories (and perhaps others):

<install>/
acmeproduct.exe
eclipse/
    .eclipseproduct
eclipse.exe
startup.jar
    features/
    plugins/
    jre/

If a product installer solicits license information from the user, such as the name of the registered owner and the license key, this information should make it into the product "about" dialog (step 10).

This is done by recording the user responses in the "about.mapping" file in the primary feature's plug-in. For example, at <install>/plugins/com.example.acme.acmefeature_1.0.0/about.mapping. The "about.mapping" file may be pre-existing in the <product head> input, or may need to be created by the installer at install time. The keys are numbers; the value of the "n" key is substituted for the substring "{n}" in the "aboutText" property. For example, if a license key was field number 0, an "about.mapping" file containing a line like "0=T42-24T-ME4U-U4ME" should be created.

N.B. The "about.mapping" file is a java.io.Properties format file (ISO 8859-1 character encoding with "\" escaping). When the native character encoding at install time is different from ISO 8859-1, the installer is responsible for converting the native character encoding to Unicode and for adding "\" escapes where required. Escaping is required when the strings contain special characters (such as "\") or non-Latin characters. For example, field number 1 containing the first 3 letters of the Greek alphabet would be written "1=\u03B1\u03B2\u03B3".

At step 12, the product installer launches the product executable, <install>/acmeproduct.exe, with the special -initialize option [exact details TBD]. This causes the Eclipse platform to quietly perform all time-consuming first-time processing and cache the results, so that when the user starts the product it comes up promptly in an open-for-business state.

Uninstaller behavior

At uninstall time, the uninstaller should behave in the standard manner:

warn user to exit all programs, especially the product being uninstalled
ask user to confirm that the product is to be uninstalled
remove all installed files from the <install> directory, and all files in <install>/eclipse/features and <install>/eclipse/plugins including ones put there by parties other than this installer (e.g., by the Eclipse update manager)
remove desktop shortcut for the product executable
remove entry for product uninstaller
inform user of any files that were not removed

When the product is uninstalled, files deposited at install time should be deleted, along with updated features and plug-ins created by the Eclipse update manager. Important: At uninstall time, there may be other directories and files in the <install> directory, notably <install>/eclipse/workspace/, <install>/eclipse/links/, and <install>/eclipse/configuration/, that contain important data which must be retained when the product is uninstalled. The user must be able to uninstall and reinstall a product at the same location without losing important data.

Installer behavior when product already installed

When the product is already installed on the user's computer, the installer should allow a service update or version upgrade to be applied to the installed product.

At install time, the installer should behave in the standard manner:

warn user to exit all programs, especially the product being updated
locate the installed product to be updated, if necessary by searching the disk for an existing product install or by allowing the user to locate it
determine where this installer is a compatible update
if appropriate, ask the user for the name of the registered owner and for the license key
display the product's updated licensing agreement and ask the user to accept
ask user to confirm all details of the update
update files to disk (see below)
if required, alter the desktop shortcut to run the product executable
should add modified or newly added files to the list of ones to be removed at uninstall time (where feasible)
offer to show the product release notes ("readme" file)

In step 2, an installed product can be recognized by the presence of an "eclipse" directory immediately containing a file named ".eclipseproduct". The parent of the "eclipse" directory is a product's install directory; i.e., <install>/eclipse/.eclipseproduct. The information contained within this marker file should be shown to the user for confirmation that the correct product is being updated (there may be several Eclipse-based product on the user's computer).

The installer should perform compatibility checks in step 3 by simple pattern matching against subdirectories in the <install>/eclipse/features directory. For example, the presence of a folder matching "com.example.acme.otherfeature_1.0.1" would ensure that a certain service update had been applied to the installed product.

For step 7, the installer may delete or replace any of the files that it originally installed, and add more files. Important: Several files and directories, including <install>/eclipse/workspace/, <install>/eclipse/configuration, may be co-located with the install and contain important data files which need to be retained when the product is upgraded.

In upgrade situations, there is a good chance that most of the files below <install>/eclipse/plugins/ are the same (likewise for <install>/eclipse/features/). There is significant opportunity for optimization in <install>/eclipse/plugins/ since the sub-directory name, which embeds the plug-in (or fragment) version number, changes if and only iff any of the files below it change. In other words, there is no need to touch any files in <install>/eclipse/plugins/org.eclipse.ui_2.0.0/ if this sub-directory should also exist after the upgrade; if any of the plug-in's files were to change, the plug-in's version number is revised, causing the files for the upgraded plug-in to be installed in a parallel directory <install>/eclipse/plugins/org.eclipse.ui_2.0.1/.

Associating a JRE installed elsewhere

The JRE is expected to be located at <install>/eclipse/jre/bin/javaw.exe. If it is located elsewhere, the absolute path should be specified using the -vm option on the command line; e.g., -vm C:\j2jre1.3.0\jre\bin\javaw.exe. In which case, the installer should add this option to the command line of the desktop shortcut it creates.

Extension installer creation script

By extension we mean a separately installable set of features and their plug-ins that can be associated with, and used from, one ore more Eclipse-based products installed on the same computer. In contrast to a product, an extension is not self-contained; an extension does not include a product executable, the Eclipse platform, a JRE.

Without loss of generality, assume that an extension consists of a single feature. The first input to the installer creation script is a directory, <extension>, containing its feature and plug-ins. We are assuming that an extension has no files that are related to Eclipse; if it did, they would go in <extension>/, and not in <extension>/eclipse/. For reference, the skeletal structure of this directory would look like:

<extension>/
eclipse/
features/
      com.example.wiley.anvilfeature_1.0.0/
        feature.xml
plugins/
     com.example.wiley.anvilfeature_1.0.0/
      plugin.xml
        about.ini
        about.properties
        about.mappings
     com.example.wiley.mainplugin_1.0.0/
     com.example.wiley.otherplugin_1.0.0/

The exact contents of the <extension> input directory determines what files will eventually be installed on the end user's computer.

The final inputs to the installer creation script are the id and version strings for the extension's feature; e.g., "com.example.wiley.anvil" and "1.0.0". These strings have special significance to the installer, appearing in file and directory names, and in the contents of marker files created at install time.

An extension installer is similar to a product installer in most respects. The areas where it differs are highlighted below:

At install time, the installer behaves in the standard manner:

warn user to exit all programs
introduce the extension to be installed
if appropriate, ask the user for the name of the registered owner and for the license key
display the extension's licensing agreement and ask the user to accept
recommend a location on the disk to install the extension (but allow user to override this default)
check that a product or a different extension is not already stored at the specified location
ask user which product(s) to are to use this extension (search disk; browse; or skip)
optionally, determine if extension is compatible with selected products
ask user to confirm all details of the install
create marker file to mark root of extension install
copy files to disk (see below)
insert name of registered owner and license key into the "about " description
create an appropriate entry to allow the user to uninstall the extension
write link file in each of the selected products to associate extension with product
offer to show the extension release notes ("readme" file)

If the location specified in step 5 is <install>, the installer copies all the files in the <extension> directory into <install> in step 11.

Input file Installed file
<extension>/* <install>/*

For step 7, any Eclipse product might be a candidate. Eclipse-based product can be recognized by the presence of a <product install>/eclipse/.eclipseproduct file; the user should be able to request a limited disk search for installed products (a "search for installed products" button), or would navigate to a directory containing a product (i.e., a "browse" button).

The installer should perform compatibility checks in step 8 by simple pattern matching against subdirectories in the <product install>/eclipse/features directory. For example, the presence of a folder matching "org.eclipse.jdt_2.*" means that JDT is included in the installed product.

The marker file created in step 10 is <install>/eclipse/.eclipseextension is used to mark a directory into which an Eclipse-based extension has been installed, primarily for extension installers to locate (analogous to a product's .eclipseproduct marker file). This marker file is a java.io.Properties format file (ISO 8859-1 character encoding with "\" escaping) and contains the following information that identifies the extension to the user and distinguishes one Eclipse-based extension from one another:

name=Wiley Anvil Enterprise Edition
id=com.example.wiley.anvilfeature
version=1.0.0

The values of the "id" and "version" property are inputs to the installer creation script; the name of the extension is presumably known and hard-wired. (Products would not ordinarily access this marker file; only product and extension installers write or read it.)

After installing all files, the top-level structure of the install directory would contain the following files and subdirectories:

<install>/
eclipse/
.eclipseextension
    features/
    plugins/

The only significant difference from a product installer is that an extension installer also creates link files in other Eclipse-based products already installed on the user's computer. (This saves the user from having to manually associate the new extension from within each product using the Eclipse update manager.)

The link file created in step 14 is <product install>/eclipse/links/com.example.wiley.anvilfeature.link; that is, the file has the same name of as the extension's feature directory less the version number suffix. A link file is a java.io.Properties format file (ISO 8859-1 character encoding with "\" escaping). The key is "path" and the value is the absolute path of the installed extension, <install>; e.g., an entry might looks like "path=C:\\Program Files\\Wiley\\Anvil". The installer is responsible for converting from native character encoding to Unicode and adding "\" escapes where required. Escaping is usually required since <install> typically contains special characters (such as "\") and may mention directories with non-Latin characters in their names. The product reads link files when it starts up. The installer keeps a record of any link files it creates so that they can be located when the extension is updated or uninstalled.

Uninstaller behavior

At un install time, the un installer should behave in the standard manner:

warn user to exit all programs, especially products using the extension being uninstalled
ask user to confirm that the extension is to be un installed
remove all installed files from the <install> directory, and all files in <install>/eclipse/features and <install>/eclipse/plugins including ones put there by parties other than this installer (e.g., by the Eclipse update manager)
if feasible, remove the link file from any products to which it had been added
remove entry for extension uninstaller
inform user of any files that were not removed

When an extension is uninstalled, all plug-in and feature files should be deleted; there are no important data files to be kept in these subdirectories. This allows the user to uninstall an extension completely, including any updates applied by the Eclipse update manager.

Installer behavior when extension already installed

When the extension is already installed on the user's computer, the installer should allow a service update or version upgrade to be applied to the installed extension.

At install time, the installer should behave in the standard manner:

warn user to exit all programs, especially products using the extension being updated
locate the installed extension to be updated, if necessary by searching the disk for an existing extension install or by allowing the user to locate it
determine where this installer is a compatible update
if appropriate, ask the user for the name of the registered owner and for the license key
display the product's updated licensing agreement and ask the user to accept
ask user to confirm all details of the update
update files on disk (see below)
should add modified or newly added files to the list of ones to be removed at uninstall time (where feasible)
offer to show the extension release notes ("readme" file)

In step 2, an installed extension can be recognized by the presence of an "eclipse" directory immediately containing a file named ".eclipseextension". The parent of the "eclipse" directory is an extension's install directory; i.e., <install>/eclipse/.eclipseextension. The information contained within this marker file should be shown to the user for confirmation that the correct extension is being updated (there may be several Eclipse-based extension on the user's computer).

For step 7, the installer should not delete or overwrite any of the files that it originally installed; rather, it should only add the files for new versions of features and plug-in, and possibly rewrite the marker file <install>/eclipse/.eclipseextension. Leaving the old versions around gives the user the option to back out of the update. As with upgrading a product install, there is no need to touch any files in <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.0/ if this sub-directory should also exist after the upgrade; if any of the plug-in's files were to change, the plug-in's version number is revised, causing the files for the upgraded plug-in to be installed in a parallel directory <install>/eclipse/plugins/com.example.wiley.otherplugin_1.0.1/.

Input file	Installed file
<JRE>/*	<install>/eclipse/*
<product head>/*	<install>/*
<product body>/*	<install>/*
<platform>/*	<install>/*