| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Language" content="en-us"> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> | |
| <title>How to write an Eclipse installer</title> | |
| </head> | |
| <body> | |
| <h1>How to write an Eclipse installer</h1> | |
| <p>Last modified 11:15 Monday May 6, 2002</p> | |
| <p>Eclipse-based products need to be correctly installed on the end user's | |
| computer. Special-purpose packaging tools, such as <a href="http://www.installshield.com/">InstallShield</a> | |
| and <a href="http://www.rpm.org/">RPM</a>, 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.</p> | |
| <p>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. </p> | |
| <p>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:</p> | |
| <ul> | |
| <li><b>Product and extension interoperability.</b> 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.</li> | |
| <li><b>Uniformity of install time user interaction.</b> 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.</li> | |
| </ul> | |
| <h2>Product installer creation script</h2> | |
| <p>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.</p> | |
| <p>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. </p> | |
| <p>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 | |
| <<i>JRE</i>>. This directory must have a standard JRE directory structure, | |
| with the Java executable is located at <code>jre/bin/java.exe</code> and the class | |
| library at <code>jre/lib/rt.jar</code> below the <<i>JRE</i>> directory. | |
| For reference, the skeletal structure of this directory looks like:</p> | |
| <p><code><<i>JRE</i>>/<br> | |
| jre/<br> | |
| bin/<br> | |
| java.exe<br> | |
| lib/<br> | |
| rt.jar | |
| </code></p> | |
| <p>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.</p> | |
| <p>The second input to the installer creation script is a directory, <<code><i>product | |
| head</i></code>>, | |
| 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):</p> | |
| <p><code><<i>product head</i>>/<br> | |
| <i> acmeproduct.exe<br> | |
| </i> | |
| <br> | |
| </code>The third input to the installer creation script is a directory, <<code><i>product | |
| body</i></code>>, | |
| containing the features and plug-ins developed for the product. For reference, the skeletal | |
| structure of this directory would look like:</p> | |
| <p><code><<i>product body</i>>/<br> | |
| eclipse/<br> | |
| features/<br> | |
| <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/<br> | |
| feature.xml<br> | |
| <i>com.example.acme.otherfeature</i>_<i>1.0.0</i>/<br> | |
| feature.xml<br> | |
| plugins/<br> | |
| </code> <code> <i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/<br> | |
| plugin.xml<br> | |
| about.ini<br> | |
| about.properties<br> | |
| about.mappings<br> | |
| plugin_customization.ini<br> | |
| splash.bmp<br> | |
| </code> <code> <i>com.example.acme.otherfeature</i>_<i>1.0.0</i>/<br> | |
| plugin.xml<br> | |
| about.ini<br> | |
| about.properties<br> | |
| about.mappings<br> | |
| </code> <code> <i>com.example.acme.myplugin</i>_<i>1.0.0</i>/<br> | |
| plugin.xml<br> | |
| <i>myplugin</i>.jar<br> | |
| </code> <code> <i>com.example.acme.otherplugin</i>_<i>1.0.0</i>/<br> | |
| plugin.xml<br> | |
| <i>otherplugin</i>.jar | |
| </code></p> | |
| <p>The fourth input to the installer creation script is a directory, <<code><i>platform</i></code>>, | |
| 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, <code>eclipse.exe</code>, | |
| (named <code>eclipse</code> on Unix operating environment), its companion <code>startup.jar</code>, 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:</p> | |
| <p><code> | |
| <<i>platform</i>><br> | |
| eclipse/<br> | |
| eclipse.exe<br> | |
| startup.jar<br> | |
| features/<br> | |
| org.eclipse.platform_2.0.0/<br> | |
| org.eclipse.platform.win32_2.0.0/<br> | |
| org.eclipse.jdt_2.0.0/<br> | |
| org.eclipse.pde_2.0.0/<br> | |
| plugins/<br> | |
| org.eclipse.platform_2.0.0/<br> | |
| org.eclipse.core.runtime_2.0.0/<br> | |
| org.eclipse.core.boot_2.0.0/<br> | |
| org.eclipse.core.resources_2.0.0/<br> | |
| org.eclipse.ui_2.0.0/<br> | |
| org.eclipse.jdt_2.0.0/<br> | |
| org.eclipse.jdt.core_2.0.0/<br> | |
| org.eclipse.jdt.ui_2.0.0/<br> | |
| org.eclipse.pde_2.0.0/<br> | |
| org.eclipse.pde.core_2.0.0/<br> | |
| org.eclipse.pde.ui_2.0.0/<br> | |
| (more org.eclipse.* plug-in directories)<br> | |
| <br> | |
| </code>The exact contents of the <<i><code>JRE</code></i>>, <<i><code>product | |
| head</code></i>>, <<i><code>product body</code></i>>, | |
| and <<code><i>platform</i></code>> input directories determine what files | |
| will eventually be installed on the end user's computer.</p> | |
| <p>The final inputs to the installer creation script are the id and version | |
| strings for the product's primary feature; e.g., "<code><i>com.example.acme.acmefeature"</i></code>, | |
| and "<code><i>1.0.0</i></code>"; | |
| and the name of the product executable; e.g., "<code><i>acmeproduct</i></code><code>.exe</code>". | |
| For products that do not require their own product executable, this would be the | |
| path of the standard Eclipse executable launcher "<code>eclipse/eclipse.exe</code>". | |
| 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.</p> | |
| <p>At install time, the installer should behave in the standard manner (further | |
| details follow the list of steps):</p> | |
| <ol> | |
| <li>warn user to exit all programs</li> | |
| <li>introduce the product to be installed</li> | |
| <li>if appropriate, ask the user for the name of the registered owner and for | |
| the license key</li> | |
| <li>display the product's licensing agreement and ask the user to accept</li> | |
| <li>recommend a location on the disk to install the product (but allow user to | |
| override this default)</li> | |
| <li>check that a product or extension is not already stored at the specified | |
| location</li> | |
| <li>ask user to confirm all details of the install</li> | |
| <li>create marker file to mark root of product install</li> | |
| <li>copy files to disk (see below)</li> | |
| <li>if appropriate, insert name of registered owner and license key into the "about | |
| " description</li> | |
| <li>create a desktop shortcut to run the product executable</li> | |
| <li>create an appropriate entry to allow the user to uninstall the product</li> | |
| <li>launch the product executable with -initialize option to perform all | |
| first-time processing</li> | |
| <li>offer to show the product release notes ("readme" file)</li> | |
| </ol> | |
| <p>If the location specified in step 5 is <<code><i>install</i></code>>, | |
| the installer copies all the files in the <<i><code>JRE</code></i>>, <code><<i>platform</i>>, </code> <<i><code>product</code></i>>, | |
| and <code><<i>product plug-ins</i>></code> directories into <<code><i>install</i></code>>.</p> | |
| <table border="1" width="50%"> | |
| <tr> | |
| <td width="50%">Input file</td> | |
| <td width="50%">Installed file</td> | |
| </tr> | |
| <tr> | |
| <td width="50%"><code><<i>JRE</i>>/*</code></td> | |
| <td width="50%"><code><<i>install</i>>/eclipse/*</code></td> | |
| </tr> | |
| <tr> | |
| <td width="50%"><code><<i>product head</i>>/*</code></td> | |
| <td width="50%"><code><<i>install</i>>/*</code></td> | |
| </tr> | |
| <tr> | |
| <td width="50%"><code><<i>product body</i>>/*</code></td> | |
| <td width="50%"><code><<i>install</i>>/*</code></td> | |
| </tr> | |
| <tr> | |
| <td width="50%"><code><<i>platform</i>>/*</code></td> | |
| <td width="50%"><code><<i>install</i>>/*</code></td> | |
| </tr> | |
| </table> | |
| <p>The marker file created in step 8 is <code><<i>install</i>>/eclipse/.eclipseproduct</code> | |
| 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 <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | |
| 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:</p> | |
| <blockquote> | |
| <p><code>name=<i>Acme Visual Tools Pro</i><br> | |
| id=<i>com.example.acme.acmefeature<br> | |
| </i>version=<i>1.0.0</i></code></p> | |
| </blockquote> | |
| <p>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.)</p> | |
| <p>Step 6 requires checking for an existing <code><<i>install</i>>/eclipse/.eclipseproduct</code> | |
| or <code><<i>install</i>>/eclipse/.eclipseextension</code> file. A | |
| product cannot be installed in exactly the same place as another product or extension.</p> | |
| <p>After installing all files, the top-level structure of the install directory | |
| would contain the following files and subdirectories (and perhaps others):</p> | |
| <p><code><<i>install</i>>/<br> | |
| <i>acmeproduct</i>.exe<br> | |
| eclipse/<br> | |
| .eclipseproduct<br> | |
| eclipse.exe<br> | |
| startup.jar<br> | |
| features/<br> | |
| plugins/<br> | |
| jre/<br> | |
| <br> | |
| </code>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).</p> | |
| <p>This is done by recording the user responses in the "<code>about.mapping</code>" | |
| file in the primary feature's plug-in. For example, at <code><<i>install</i>>/plugins/<i>com.example.acme.acmefeature</i>_<i>1.0.0</i>/about.mapping</code>. | |
| The "<code>about.mapping</code>" file may be pre-existing in the <<i><code>product | |
| head</code></i>> | |
| input, or may need to be created by the installer at install time. | |
| The keys are numbers; the value of the "<i>n</i>" key is substituted | |
| for the substring "<code>{<i>n</i>}</code>" in the "<code>aboutText</code>" property. | |
| For example, if a license key was field number 0, an "<code>about.mapping</code>" | |
| file containing a line like "<code>0=T42-24T-ME4U-U4ME</code>" should | |
| be created.</p> | |
| <p>N.B. | |
| The "<code>about.mapping</code>" file is a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | |
| 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 "<code>1=\u03B1\u03B2\u03B3</code>".</p> | |
| <p>At step 12, the product installer launches the product executable,<code> <<i>install</i>>/<i>acmeproduct</i>.exe</code>, | |
| 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.</p> | |
| <h3>Uninstaller behavior</h3> | |
| <p>At uninstall time, the uninstaller should behave in the standard manner:</p> | |
| <ol> | |
| <li>warn user to exit all programs, especially the product being uninstalled</li> | |
| <li>ask user to confirm that the product is to be uninstalled</li> | |
| <li>remove all installed files from the <<i><code>install</code></i>> | |
| directory, and <b>all</b> files in <<i><code>install</code></i>><code>/eclipse/features</code> | |
| and <<i><code>install</code></i>><code>/eclipse/plugins</code> including ones put there by parties other than | |
| this installer (e.g., by the Eclipse update manager)</li> | |
| <li>remove desktop shortcut for the product executable</li> | |
| <li>remove entry for product uninstaller</li> | |
| <li>inform user of any files that were not removed</li> | |
| </ol> | |
| <p>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. <b>Important:</b> At uninstall time, there may be | |
| other directories and files in the <code><<i>install</i>></code> | |
| directory, notably <code><<i>install</i>>/eclipse/workspace/</code>, | |
| <code><<i>install</i>>/eclipse/links/</code>, and <code><<i>install</i>>/eclipse/platform.cfg</code>, | |
| 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.</p> | |
| <h3>Installer behavior when product already installed</h3> | |
| <p>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.</p> | |
| <p>At install time, the installer should behave in the standard manner:</p> | |
| <ol> | |
| <li>warn user to exit all programs, especially the product being updated</li> | |
| <li>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</li> | |
| <li> determine where this installer is a compatible update</li> | |
| <li>if appropriate, ask the user for the name of the registered owner and for | |
| the license key</li> | |
| <li>display the product's updated licensing agreement and ask the user to accept</li> | |
| <li>ask user to confirm all details of the update</li> | |
| <li>update files to disk (see below)</li> | |
| <li>if required, alter the desktop shortcut to run the product executable</li> | |
| <li>should add modified or newly added files to the list of ones to be removed at uninstall | |
| time (where feasible)</li> | |
| <li>offer to show the product release notes ("readme" file)</li> | |
| </ol> | |
| <p>In step 2, an installed product can be recognized by the presence of an "<code>eclipse</code>" | |
| directory immediately containing a file named "<code>.eclipseproduct</code>". | |
| The parent of the "<code>eclipse</code>" directory is a product's install | |
| directory; i.e., <code><<i>install</i>>/eclipse/.eclipseproduct</code>. | |
| 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).</p> | |
| <p>The installer should perform compatibility checks in step 3 by simple pattern | |
| matching against subdirectories in the <code><<i>install</i>>/eclipse/features</code> | |
| directory. For example, the presence of a folder matching "<code><i>com.example.acme.otherfeature</i>_<i>1.0.1</i></code>" | |
| would ensure that a certain service update had been applied to the installed | |
| product.</p> | |
| <p>For step 7, the installer may delete or replace any of the files that it | |
| originally installed, and add more files. <b>Important:</b> Several files and directories, | |
| including <code><<i>install</i>>/eclipse/workspace/</code>, <code><<i>install</i>>/eclipse/platform.cfg</code>, | |
| may be co-located with the install and contain important data files | |
| which need to be retained | |
| when the product is upgraded. </p> | |
| <p>In upgrade situations, there is a good chance that most of the files below <code><<i>install</i>>/eclipse/plugins/</code> | |
| are the same (likewise for <code><<i>install</i>>/eclipse/features/</code>). | |
| There is significant opportunity for optimization in <code><<i>install</i>>/eclipse/plugins/</code> | |
| 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 <code><<i>install</i>>/eclipse/plugins/org.eclipse.ui_2.0.0</code>/ | |
| 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 <code><<i>install</i>>/eclipse/plugins/org.eclipse.ui_2.0.1</code>/. </p> | |
| <p>Note also that the product executable must not be launched with -initialize | |
| in the reinstall case, as this would lose important user configuration data.</p> | |
| <h3>Associating a JRE installed elsewhere</h3> | |
| <p>The JRE is expected to be located at <code><<i>install</i>>/eclipse/jre/bin/javaw.exe</code>. | |
| If it is located elsewhere, the absolute path should be specified using the <code>-vm</code> | |
| option on the command line; e.g.,<code> -vm C:\j2jre1.3.0\jre\bin\javaw.exe</code>. | |
| In which case, the installer should add this option to the command line of the desktop shortcut | |
| it creates.</p> | |
| <h2>Extension installer creation script</h2> | |
| <p>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.</p> | |
| <p>Without loss of generality, assume that an extension consists of a single | |
| feature. The first input to the installer creation script is a directory, <<code><i>extension</i></code>>, | |
| 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 <code><<i>extension</i>>/</code>, | |
| and not in <code><<i>extension</i>>/eclipse/</code>. For reference, the skeletal | |
| structure of this directory would look like:</p> | |
| <p><code><<i>extension</i>>/<br> | |
| eclipse/<br> | |
| features/<br> | |
| <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/<br> | |
| feature.xml<br> | |
| plugins/<br> | |
| </code> <code> <i>com.example.wiley.anvilfeature</i>_<i>1.0.0</i>/<br> | |
| plugin.xml<br> | |
| about.ini<br> | |
| about.properties<br> | |
| about.mappings<br> | |
| </code> <code> <i>com.example.wiley.mainplugin</i>_<i>1.0.0</i>/<br> | |
| </code> <code> <i>com.example.wiley.otherplugin</i>_<i>1.0.0</i>/ | |
| </code></p> | |
| <p>The exact contents of the <<i><code>extension</code></i>> input | |
| directory determines what files | |
| will eventually be installed on the end user's computer.</p> | |
| <p>The final inputs to the installer creation script are the id and version | |
| strings for the extension's feature; e.g., "<i><code>com.example.wiley.anvil</code></i>" | |
| and "<code><i>1.0.0</i></code>". 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.</p> | |
| <p>An extension installer is similar to a product installer in most respects. | |
| The areas where it differs are highlighted below:</p> | |
| <p>At install time, the installer behaves in the standard manner:</p> | |
| <ol> | |
| <li>warn user to exit all programs</li> | |
| <li>introduce the extension to be installed</li> | |
| <li>if appropriate, ask the user for the name of the registered owner and for | |
| the license key</li> | |
| <li>display the extension's licensing agreement and ask the user to accept</li> | |
| <li>recommend a location on the disk to install the extension (but allow user to | |
| override this default)</li> | |
| <li>check that a product or a different extension is not already stored at the specified | |
| location</li> | |
| <li> ask user which product(s) to are to use this extension (search disk; | |
| browse; or skip) | |
| </li> | |
| <li>optionally, determine if extension is compatible with selected products</li> | |
| <li>ask user to confirm all details of the install</li> | |
| <li>create marker file to mark root of extension install</li> | |
| <li>copy files to disk (see below)</li> | |
| <li>insert name of registered owner and license key into the "about | |
| " description</li> | |
| <li>create an appropriate entry to allow the user to uninstall the extension</li> | |
| <li>write link file in each of the selected products to associate extension | |
| with product</li> | |
| <li>offer to show the extension release notes ("readme" file)</li> | |
| </ol> | |
| <p>If the location specified in step 5 is <<code><i>install</i></code>>, | |
| the installer copies all the files in the <code><<i>extension</i>> </code>directory | |
| into <<code><i>install</i></code>> in step 11.</p> | |
| <table border="1" width="50%"> | |
| <tr> | |
| <td width="50%">Input file</td> | |
| <td width="50%">Installed file</td> | |
| </tr> | |
| <tr> | |
| <td width="50%"><code><<i>extension</i>>/*</code></td> | |
| <td width="50%"><code><<i>install</i>>/*</code></td> | |
| </tr> | |
| </table> | |
| <p>For step 7, any Eclipse product might be a candidate. Eclipse-based product | |
| can be recognized by the presence of a <code><<i>product install</i>>/eclipse/.eclipseproduct</code> | |
| 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).</p> | |
| <p>The installer should perform compatibility checks in step 8 by simple pattern | |
| matching against subdirectories in the <code><<i>product install</i>>/eclipse/features</code> | |
| directory. For example, the presence of a folder matching "<code>org.eclipse.jdt_2.*</code>" | |
| means that JDT is included in the installed product. </p> | |
| <p>The marker file created in step 10 is <code><<i>install</i>>/eclipse/.eclipseextension</code> | |
| 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 <code>.eclipseproduct</code> marker file). This | |
| marker file is a <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | |
| 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:</p> | |
| <blockquote> | |
| <p><code>name=<i>Wiley Anvil Enterprise Edition</i><br> | |
| id=<i>com.example.wiley.anvilfeature<br> | |
| </i>version=<i>1.0.0</i></code></p> | |
| </blockquote> | |
| <p>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.)</p> | |
| <p>After installing all files, the top-level structure of the install directory | |
| would contain the following files and subdirectories:</p> | |
| <p><code><<i>install</i>>/<br> | |
| eclipse/<br> | |
| .eclipseextension<br> | |
| features/<br> | |
| plugins/</code></p> | |
| <p>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.) </p> | |
| <p>The link file created in step 14 is <code><<i>product install</i>>/eclipse/links/<i>com.example.wiley.anvilfeature.</i>link</code>; | |
| 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 <a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Properties.html">java.io.Properties</a> | |
| format file (ISO 8859-1 character encoding with "\" escaping). | |
| The key is "path" and the value is the absolute path of the installed | |
| extension, <code><<i>install</i>></code>; e.g., an entry might looks like "<code>path=C:\\Program | |
| Files\\Wiley\\Anvil</code>"<code>.</code> The installer is responsible for converting | |
| from native character | |
| encoding to Unicode and adding "\" escapes where required. Escaping is | |
| usually required since <code><<i>install</i>></code> | |
| 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.</p> | |
| <h3>Uninstaller behavior</h3> | |
| <p>At un install time, the un installer should behave in the standard manner:</p> | |
| <ol> | |
| <li>warn user to exit all programs, especially products using the extension | |
| being uninstalled</li> | |
| <li>ask user to confirm that the extension is to be un installed</li> | |
| <li>remove all installed files from the <<i><code>install</code></i>> | |
| directory, and <b>all</b> files in <<i><code>install</code></i>><code>/eclipse/features</code> | |
| and <<i><code>install</code></i>><code>/eclipse/plugins</code> including ones put there by parties other than | |
| this installer (e.g., by the Eclipse update manager)</li> | |
| <li>if feasible, remove the link file from any products to which it had been | |
| added </li> | |
| <li>remove entry for extension uninstaller</li> | |
| <li>inform user of any files that were not removed</li> | |
| </ol> | |
| <p>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.</p> | |
| <h3>Installer behavior when extension already installed</h3> | |
| <p>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.</p> | |
| <p>At install time, the installer should behave in the standard manner:</p> | |
| <ol> | |
| <li>warn user to exit all programs, especially products using the extension | |
| being updated</li> | |
| <li>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</li> | |
| <li> determine where this installer is a compatible update</li> | |
| <li>if appropriate, ask the user for the name of the registered owner and for | |
| the license key</li> | |
| <li>display the product's updated licensing agreement and ask the user to accept</li> | |
| <li>ask user to confirm all details of the update</li> | |
| <li>update files on disk (see below)</li> | |
| <li>should add modified or newly added files to the list of ones to be removed at uninstall | |
| time (where feasible)</li> | |
| <li>offer to show the extension release notes ("readme" file)</li> | |
| </ol> | |
| <p>In step 2, an installed extension can be recognized by the presence of an "<code>eclipse</code>" | |
| directory immediately containing a file named "<code>.eclipseextension</code>". | |
| The parent of the "<code>eclipse</code>" directory is an extension's install | |
| directory; i.e., <code><<i>install</i>>/eclipse/.eclipseextension</code>. | |
| 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).</p> | |
| <p>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 <code><<i>install</i>>/eclipse/.eclipseextension</code>. 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 <code><<i>install</i>>/eclipse/plugins/<i>com.example.wiley.otherplugin</i>_<i>1.0.0</i></code>/ | |
| 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 <code><<i>install</i>>/eclipse/plugins/<i>com.example.wiley.otherplugin</i>_<i>1.0.1</i></code>/. </p> | |
| <p><a href="hglegal.htm"><img src="ngibmcpy.gif" alt="Copyright IBM Corporation and others 2000, 2003." border="0" width="250" height="12"></a></p> | |
| </body> | |
| </html> |