Product installation guidelines

The platform provides standard tools for updating and extending products.  In order to participate in the platform mechanisms for updating and extending products, your packaged product should follow the following guidelines.  This will allow your product to peacefully coexist with, or even enhance, other Eclipse based products.

Consider again the sample directory structure for the acmeweb product:

acmeweb/
    acmeweb.exe        
    eclipse/        
        .eclipseproduct    
        eclipse.exe    
        startup.jar    
        install.ini    
        .config/    
            platform.cfg
        jre/
        features/    
            com.example.acme.acmefeature_1.0.0/
                feature.xml
            org.eclipse.platform_2.0.0/
            org.eclipse.platform.win32_2.0.0/
            ...
        plugins/
            com.example.acme.acmefeature_1.0.0/
                plugin.xml
                about.ini
                about.html
                about.mappings
                about.properties
                acme.gif
                plugin_customization.ini
                splash.jpg
                welcome.xml
            com.example.acme.acmewebsupport_1.0.0/
            org.eclipse.platform_2.0.0/
            ...
        links/
            ...

Where did these files come from?  Let's look at the product content from the perspective of the development team.  The installed files can be grouped into five main categories:

• top-level product files (such as the acmeweb.exe)
• product features and plug-ins
• the Eclipse platform itself
• the Java runtime environment (JRE)
• files generated by the installation process itself

A proper installation script will produce the appropriate directory structure by doing the following:

• allow the user to specify the top level directory of the install (such as c:\acmeweb.  We will refer to it as acmeweb for the remaining steps.)
• ensure that a product is not already installed in the location
• copy the files as follows:
  • Top-level product files are copied to acmeweb
  • Eclipse files are copied to acmeweb/eclipse using the expected feature and plugin directory structures
  • JRE files are copied to acmeweb/eclipse/jre.  If a JRE is already located elsewhere, then the application shortcut should be setup to invoke eclipse with the -vm command line argument so that the location of the JRE is known by the platform
  • Product features and plug-ins are copied to acmeweb/eclipse/features and acmeweb/eclipse/plugins

• create a marker file, .eclipseproduct, in acmeweb/eclipse.  The marker file is a java.io.Properties format file that indicates the name, id, and version of the product.
• store any necessary install info (user, license, date) that is to be shown in the about dialog in acmeweb/eclipse/plugins/com.example.acmefeature_1.0.0/about.mappings
• replace the acmeweb/eclipse/install.ini with one that sets the property feature.default.id to the product's primary feature
• invoke the product executable using the -initialize option.  This causes the 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.

Multi-user issues

When a product is installed for the intention of allowing multiple users, care must be taken to separate individual users' data (such as the workspace directory) from the shared product install directory.

Uninstall issues

When a product is uninstalled, the following concepts are important.

• all files in the eclipse/features and eclipse/plugins directories should be removed, even if they weren't originally installed by the installation program.  This ensures that files added by the platform update manager are removed when the product is removed.
• except for the point above, only those files installed by the installation program in other directories should be removed.  It is important to preserve any important data, such as the workspace directory, so that reinstalling the product after an uninstall will produce expected results.

Reinstalling the product

When the product is already installed, the installer should allow a service update or upgrade if one is available.  The existence of the product can be confirmed by looking for acmeweb/eclipse/.eclipseproduct.  The information in this marker file can be used to confirm with the user that the correct product is being updated.  The availability of updates can be confirmed with pattern matches against feature names.  For example, the presence of acmeweb/eclipse/plugins/com.example.acmefeature_1.0.1 would indicate that the 1.0.1 version update had already been applied to the product.

Once the validity of the reinstall is established, the install program should copy or replace files as needed.  If the version of the underlying Eclipse platform has not changed, there is a good chance that complete directories can be ignored.  The version numbers appended to the platform features and plugins can be used to determine whether any changes underneath a plug-in or feature's directory are necessary. 

Additional information on installing products can be found in How to write an Eclipse installer.