| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html lang="en"> |
| |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <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 15:20 Friday June 18, 2004</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), 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> |
| 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.equinox.launcher_1.0.0.v20070530.jar<br> |
| org.eclipse.equinox.launcher.win32.win32.x86_1.0.0.v20070523/<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="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html">java.util.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> |
| 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="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html">java.util.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/configuration/</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/configuration</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> |
| <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="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html">java.util.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="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Properties.html">java.util.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> |
| |
| |
| |
| </body> |
| |
| </html> |