bundles/org.eclipse.platform.doc.isv/guide/product_config_install.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
 <HEAD>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. 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-Type" CONTENT="text/html; charset=ISO-8859-1">
 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

 <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <TITLE>Product installation guidelines</TITLE>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <h2>Product installation guidelines</h2>
 <p>The platform provides standard tools for updating and extending
 products.&nbsp; In order to participate in the platform mechanisms for updating
 and extending products, your packaged product should follow the following
 guidelines.&nbsp; This will allow your product to peacefully
 coexist with, or even enhance, other Eclipse based products.</p>
 <p>Consider again the sample directory structure for the acmeweb product:</p>
 <pre>acmeweb/
 	acmeweb.exe
 	eclipse/
 		.eclipseproduct
 		eclipse.exe
 		install.ini
 		.config/
 			platform.cfg
 		jre/
 		features/
 			com.example.acme.acmefeature_1.0.0/
 				feature.xml
 			...
 		plugins/
 			com.example.acme.acmefeature_1.0.0/
 				plugin.xml
 				about.ini
 				about.html
 				about.mappings
 				about.properties
 				acme.png
 				plugin_customization.ini
 				splash.bmp
 				welcome.xml
 			com.example.acme.acmewebsupport_1.0.0/
 			...
 		links/
 			...</pre>

 <p>Where did these files come from?&nbsp; Let's look at the product content from
 the perspective of the development team.&nbsp; The installed files can be
 grouped into five main categories:</p>
 <ul>
   <li>top-level product files (such as the acmeweb.exe)</li>
   <li>product features and plug-ins</li>
   <li>the Eclipse platform itself</li>
   <li>the Java runtime environment (JRE)</li>
   <li>files generated by the installation process itself</li>
 </ul>
 <p>A proper installation script will produce the appropriate directory structure
 by doing the following:</p>
 <ul>
   <li>allow the user to specify the top level directory of the install (such as <b>c:\acmeweb.&nbsp;
     </b>We will refer to it as <b>acmeweb</b> for the remaining steps.)</li>
   <li>ensure that a product is not already installed in the location</li>
   <li>copy the files as follows:
     <ul>
       <li>Top-level product files are copied to <b>acmeweb</b></li>
       <li>Eclipse files are copied to <b>acmeweb/eclipse </b>using the expected
         feature and plugin directory structures</li>
       <li>JRE files are copied to <b>acmeweb/eclipse/jre</b>.&nbsp; If a JRE is
         already located elsewhere, then the application shortcut should be setup
         to invoke eclipse with the <b>-vm</b> command line argument so that the
         location of the JRE is known by the platform</li>
       <li>Product features and plug-ins are copied to <b>acmeweb/eclipse/features</b>
         and <b>acmeweb/eclipse/plugins</b></li>
     </ul>
   </li>
   <li>create a marker file, <b>.eclipseproduct</b>, in <b>acmeweb/eclipse</b>.&nbsp;
     The marker file is a <b>java.io.Properties</b> format file that indicates
     the name, id, and version of the product.</li>
   <li>store any necessary install info (user, license, date) that is to be shown
     in the about dialog in <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.0/about.mappings</b></li>
   <li>if the primary feature mechanism (pre R3.0) is used to define the product, replace the
   <b>acmeweb/eclipse/install.ini</b> with one that sets the property <b>feature.default.id
     </b>to the product's primary feature</li>
   <li>invoke the product executable using the <b>-initialize</b> option.&nbsp;
     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.</li>
 </ul>
 <h3>Multi-user issues</h3>
 <p>When a product is installed with the intention of sharing the installation among multiple users,
 care must be taken to separate individual user's data (such as the <b>workspace</b>
 directory) from the shared product install directory.</p>
 <h3>Uninstall issues</h3>
 <p>When a product is uninstalled, the following concepts are important.</p>
 <ul>
   <li><b>all</b> files in the <b>eclipse/features</b> and <b>eclipse/plugins</b>
     directories should be removed, even if they weren't originally installed by
     the installation program.&nbsp; This ensures that files added by the
     platform update manager are removed when the product is
     removed.</li>
   <li>except for the point above, <b>only</b> those files installed by the
     installation program in other directories should be removed.&nbsp; It is
     important to preserve any important data, such as the <b> workspace</b>
     directory, so
     that reinstalling the product after an uninstall will produce expected
     results.</li>
 </ul>
 <h3>Reinstalling the product</h3>
 <p>When the product is already installed, the installer should allow a service
 update or upgrade if one is available.&nbsp; The existence of the product can be
 confirmed by looking for <b>acmeweb/eclipse/.eclipseproduct</b>.&nbsp; The
 information in this marker file can be used to confirm with the user that the
 correct product is being updated.&nbsp; The availability of updates can be
 confirmed with pattern matches against feature names.&nbsp; For example, the
 presence of <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.1 </b>would
 indicate that the 1.0.1 version update had already been applied to the product.</p>
 <p>Once the validity of the reinstall is established, the install program should
 copy or replace files as needed.&nbsp; If the version of the underlying Eclipse
 platform has not changed, there is a good chance that complete directories can
 be ignored.&nbsp; 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.&nbsp; </p>
 <p>Additional information on installing products can be found in <a href="../reference/misc/eclipse-install.html">How
 to write an Eclipse installer</a>.</p>

 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
	<HEAD>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. 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-Type" CONTENT="text/html; charset=ISO-8859-1">
	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<TITLE>Product installation guidelines</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<h2>Product installation guidelines</h2>
	<p>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.</p>
	<p>Consider again the sample directory structure for the acmeweb product:</p>
	<pre>acmeweb/
	acmeweb.exe
	eclipse/
	.eclipseproduct
	eclipse.exe
	install.ini
	.config/
	platform.cfg
	jre/
	features/
	com.example.acme.acmefeature_1.0.0/
	feature.xml
	...
	plugins/
	com.example.acme.acmefeature_1.0.0/
	plugin.xml
	about.ini
	about.html
	about.mappings
	about.properties
	acme.png
	plugin_customization.ini
	splash.bmp
	welcome.xml
	com.example.acme.acmewebsupport_1.0.0/
	...
	links/
	...</pre>

	<p>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:</p>
	<ul>
	<li>top-level product files (such as the acmeweb.exe)</li>
	<li>product features and plug-ins</li>
	<li>the Eclipse platform itself</li>
	<li>the Java runtime environment (JRE)</li>
	<li>files generated by the installation process itself</li>
	</ul>
	<p>A proper installation script will produce the appropriate directory structure
	by doing the following:</p>
	<ul>
	<li>allow the user to specify the top level directory of the install (such as <b>c:\acmeweb.
	</b>We will refer to it as <b>acmeweb</b> for the remaining steps.)</li>
	<li>ensure that a product is not already installed in the location</li>
	<li>copy the files as follows:
	<ul>
	<li>Top-level product files are copied to <b>acmeweb</b></li>
	<li>Eclipse files are copied to <b>acmeweb/eclipse </b>using the expected
	feature and plugin directory structures</li>
	<li>JRE files are copied to <b>acmeweb/eclipse/jre</b>.  If a JRE is
	already located elsewhere, then the application shortcut should be setup
	to invoke eclipse with the <b>-vm</b> command line argument so that the
	location of the JRE is known by the platform</li>
	<li>Product features and plug-ins are copied to <b>acmeweb/eclipse/features</b>
	and <b>acmeweb/eclipse/plugins</b></li>
	</ul>
	</li>
	<li>create a marker file, <b>.eclipseproduct</b>, in <b>acmeweb/eclipse</b>.
	The marker file is a <b>java.io.Properties</b> format file that indicates
	the name, id, and version of the product.</li>
	<li>store any necessary install info (user, license, date) that is to be shown
	in the about dialog in <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.0/about.mappings</b></li>
	<li>if the primary feature mechanism (pre R3.0) is used to define the product, replace the
	<b>acmeweb/eclipse/install.ini</b> with one that sets the property <b>feature.default.id
	</b>to the product's primary feature</li>
	<li>invoke the product executable using the <b>-initialize</b> 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.</li>
	</ul>
	<h3>Multi-user issues</h3>
	<p>When a product is installed with the intention of sharing the installation among multiple users,
	care must be taken to separate individual user's data (such as the <b>workspace</b>
	directory) from the shared product install directory.</p>
	<h3>Uninstall issues</h3>
	<p>When a product is uninstalled, the following concepts are important.</p>
	<ul>
	<li><b>all</b> files in the <b>eclipse/features</b> and <b>eclipse/plugins</b>
	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.</li>
	<li>except for the point above, <b>only</b> those files installed by the
	installation program in other directories should be removed.  It is
	important to preserve any important data, such as the <b> workspace</b>
	directory, so
	that reinstalling the product after an uninstall will produce expected
	results.</li>
	</ul>
	<h3>Reinstalling the product</h3>
	<p>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 <b>acmeweb/eclipse/.eclipseproduct</b>.  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 <b>acmeweb/eclipse/plugins/com.example.acmefeature_1.0.1 </b>would
	indicate that the 1.0.1 version update had already been applied to the product.</p>
	<p>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.  </p>
	<p>Additional information on installing products can be found in <a href="../reference/misc/eclipse-install.html">How
	to write an Eclipse installer</a>.</p>

	</BODY>
	</HTML>