platform-core/runtime/howto.html - www.eclipse.org/eclipse - Git at Google

 <html>
 <head>
 		<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 		<title>The Equinox Runtime - Users Guide</title>
 		<link rel="stylesheet" title="default" href="http://eclipse.org/default_style.css" type="text/css">
 		<style>
 			th,td { vertical-align:top; text-align=left}
 			.issue { font-style:oblique; width:200px;}
 			.box	{ background-color:#E0E0FF}
 		</style>
 </head>
 	<body>
 	<table BORDER=0 CELLSPACING=5 CELLPADDING=2 WIDTH="100%" >
 			<tr>
 				<td ALIGN=left width="60%">

       <p><font class=indextop> eclipse</font><br>
         <font class=indexsub> runtime users guide</font> </p>
 				</td>
 				<td WIDTH="40%">&nbsp; </td>
 			</tr>
 	</table>

 <blockquote>
   <p><b>Summary</b> <br>
     This document details how to run and control the Eclipse 3.0 runtime. <br>
     Last Modified: 1700 March 23, 2004</p>
 </blockquote>

 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
       Controlling the runtime</font></b></td>
   </tr>
 </table>
 <p>This section has been moved to the Reference section of the ISV doc.</p>
 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
       <a name="locations"></a>Locations</font></b></td>
   </tr>
 </table>
 <p>This section has been moved to the Reference section of the ISV doc.</p>
 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> Configurations</font></b></td>
   </tr>
 </table>
 <p>Configurations define a (sub)set of plugins found in an install. Users can
   then run a configuration on a data set (e.g., workspace). This is easy to see,
   for example, in a corporate setting where all of the Eclipse-based products
   might be installed and managed in one large install base. This install would
   contain potentially thousands of plugins. The Eclipse runtime scales to handle
   this but the resultant environment is likely not interesting for users. Such
   shared installations reduce the effort required to manage
   products as well as providing a centralized point for defining consistent
   sets of function.</p>
 <p>For example,  users
     from, say, accounting should run the &quot;accounting configuration&quot; which identifies
   only those plugins useful to accountants. Similarly, the developers have their
   configurations as do the sales team. Further, products typically ship with
   predefined configuration(s) which define/suit their envisioned usecases. </p>
 <p>When the Eclipse runtime is run, agents (plugins, remote entities or humans)
   can control the set of plugins that the runtime manages. Plugins managed by
   the runtime are candidates for execution. A candidate must be resolved before
   any of its code can be run or its presence (e.g., extensions) is made known.
   The runtime keeps track of the set of managed plugins and associated information
   in a configuration location. If there is no such location or the location is
   readonly, the runtime will still run but may not be able to offer all function.
   For example, it will not be able to remember between sessions which plugins
   it manages.</p>
 <p>In a shared install the plugins themselves are shared as are the predefined
   configurations but each user may have their own area in which configuration
   values can be overridden and configuration-specific data can be stored. Eclipse
   uses the notion of <em>cascading configurations</em> to layer configurations.</p>
 <p>freezing</p>
 <p>&nbsp;</p>
 <p>&nbsp;</p>
 <p>To allow for shared installations and </p>
 <p>&nbsp;</p>
 <p>In </p>
 <p>the notion of a <i>configuration area</i> (see <code>Platform.getConfigurationLocation()</code>).
   For the runtime, the configuration area contains a file called config.ini.
   This file, if present, contains a set of properties which control the construction
   and operation of the framework and runtime. For example, it is in this file
   that an initial set of bundles to load and start is defined.</p>
 <p>The runtime does not define how this file is managed, nor does it contain
   any mechanism for updating the file (i.e., the runtime never writes the file).
   Rather, this responsibility is left to the entity managing the configuration.
   In some scenarios the configuration is defined and locked during product build,
   in other cases a system administrator crafts the configuration and pushes it
   to machines (or it is shared), in still other situations the end user manages
   the config.ini (in)directly using a configuration management tool such as the
   Eclipse Update Manager.</p>
 <p>Any of these entities are free to put additional files and information in
   the configuration area. They should be careful however to consider cases where
   the configuration area is read-only. While it is not a requirement that plug-ins
   using the configuration area operate completely or partially when the area
   is read-only, your plug-in may not be usable in certain situations if it does
   not. For example, a typical tooling scenario includes a writable configuration
   area. If your plug-in is targetted at tooling environments, you are probably
   safe making that assumption. Note however that if somoene tries to use your
   plug-in in a constrained RCP scenario where there is no writable storage, they
   will likely be disappointed.</p>
 <h4>cascading</h4>
 <p>configurators</p>
 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
       Running out of jars</font></b></td>
   </tr>
 </table>
 <p>running out of jars</p>
 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
       The Console</font></b></td>
   </tr>
 </table>
 <p>using the console</p>
 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
       Setting up your workspace</font></b></td>
   </tr>
 </table>
 <p>Users with existing workspaces should not encounter problems opening them with
   the Equinox runtme. However, since the runtime plug-in structure has changed,
   there some updating of classpaths may be required. In particular, developers
   setting up a runtime workspace (i.e., a workspace containing plug-ins) will
   need to either:</p>
 <ul>
   <li>configure the target platform (Preferences-&gt;Plug-in Development-&gt;Target
     Platform) to include the required plug-ins and then use PDE &quot;required
     plugin&quot; classpath containers on their projects (recommended) or </li>
   <li>add projects (binary or source) for the required plug-ins and setup explicit
     project dependencies for their projects</li>
 </ul>
 <p>Both of these can be accomplished using the PDE Tools-&gt;Update classpath
   project context menu. </p>
 <p>The following projects are needed (in addition to the normal set) :</p>
 <ul>
   <li>org.eclipse.osgi</li>
   <li>org.eclipse.core.runtime.compatibility</li>
   <li>org.eclipse.update.configurator</li>
 </ul>
 <p>If you have an existing runtime workspace containing one of the following pre-existing
   plug-ins, it must be updated to accurately match their new contents</p>
 <ul>
   <li>org.eclipse.core.boot</li>
   <li>org.eclipse.core.runtime</li>
 </ul>
 <p>Note that these plug-ins are only required if your plug-in uses the old runtime
   API. If you have adopted the new API (see <a href="#updating">Updating your
   code</a>) then these projects/plug-ins are not needed.</p>
 <p>There should be no need to modify the launch configurations as the runtime
   is self-discovering.</p>
 <table border=0 cellspacing=0 cellpadding=2 width="100%" >
   <tr>
     <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
       Feedback</font></b></td>
   </tr>
 </table>
 <p> Should you encounter any problems while using the Equinox runtime, you are
   encouraged to either log a bug report in the <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Equinox">Equinox
   Bugzilla database</a> or make a posting to the Core <a href="http://dev.eclipse.org/mailman/listinfo/platform-core-dev">mailing
   list</a> or the Platform <a href="news://news.eclipse.org/eclipse.platform">newsgroup</a>.
 </p>
 </body>
 </html>
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>The Equinox Runtime - Users Guide</title>
	<link rel="stylesheet" title="default" href="http://eclipse.org/default_style.css" type="text/css">
	<style>
	th,td { vertical-align:top; text-align=left}
	.issue { font-style:oblique; width:200px;}
	.box { background-color:#E0E0FF}
	</style>
	</head>
	<body>
	<table BORDER=0 CELLSPACING=5 CELLPADDING=2 WIDTH="100%" >
	<tr>
	<td ALIGN=left width="60%">

	<p><font class=indextop> eclipse</font><br>
	<font class=indexsub> runtime users guide</font> </p>
	</td>
	<td WIDTH="40%">  </td>
	</tr>
	</table>

	<blockquote>
	<p><b>Summary</b> <br>
	This document details how to run and control the Eclipse 3.0 runtime. <br>
	Last Modified: 1700 March 23, 2004</p>
	</blockquote>

	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
	Controlling the runtime</font></b></td>
	</tr>
	</table>
	<p>This section has been moved to the Reference section of the ISV doc.</p>
	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
	<a name="locations"></a>Locations</font></b></td>
	</tr>
	</table>
	<p>This section has been moved to the Reference section of the ISV doc.</p>
	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF"> Configurations</font></b></td>
	</tr>
	</table>
	<p>Configurations define a (sub)set of plugins found in an install. Users can
	then run a configuration on a data set (e.g., workspace). This is easy to see,
	for example, in a corporate setting where all of the Eclipse-based products
	might be installed and managed in one large install base. This install would
	contain potentially thousands of plugins. The Eclipse runtime scales to handle
	this but the resultant environment is likely not interesting for users. Such
	shared installations reduce the effort required to manage
	products as well as providing a centralized point for defining consistent
	sets of function.</p>
	<p>For example, users
	from, say, accounting should run the "accounting configuration" which identifies
	only those plugins useful to accountants. Similarly, the developers have their
	configurations as do the sales team. Further, products typically ship with
	predefined configuration(s) which define/suit their envisioned usecases. </p>
	<p>When the Eclipse runtime is run, agents (plugins, remote entities or humans)
	can control the set of plugins that the runtime manages. Plugins managed by
	the runtime are candidates for execution. A candidate must be resolved before
	any of its code can be run or its presence (e.g., extensions) is made known.
	The runtime keeps track of the set of managed plugins and associated information
	in a configuration location. If there is no such location or the location is
	readonly, the runtime will still run but may not be able to offer all function.
	For example, it will not be able to remember between sessions which plugins
	it manages.</p>
	<p>In a shared install the plugins themselves are shared as are the predefined
	configurations but each user may have their own area in which configuration
	values can be overridden and configuration-specific data can be stored. Eclipse
	uses the notion of <em>cascading configurations</em> to layer configurations.</p>
	<p>freezing</p>
	<p> </p>
	<p> </p>
	<p>To allow for shared installations and </p>
	<p> </p>
	<p>In </p>
	<p>the notion of a <i>configuration area</i> (see <code>Platform.getConfigurationLocation()</code>).
	For the runtime, the configuration area contains a file called config.ini.
	This file, if present, contains a set of properties which control the construction
	and operation of the framework and runtime. For example, it is in this file
	that an initial set of bundles to load and start is defined.</p>
	<p>The runtime does not define how this file is managed, nor does it contain
	any mechanism for updating the file (i.e., the runtime never writes the file).
	Rather, this responsibility is left to the entity managing the configuration.
	In some scenarios the configuration is defined and locked during product build,
	in other cases a system administrator crafts the configuration and pushes it
	to machines (or it is shared), in still other situations the end user manages
	the config.ini (in)directly using a configuration management tool such as the
	Eclipse Update Manager.</p>
	<p>Any of these entities are free to put additional files and information in
	the configuration area. They should be careful however to consider cases where
	the configuration area is read-only. While it is not a requirement that plug-ins
	using the configuration area operate completely or partially when the area
	is read-only, your plug-in may not be usable in certain situations if it does
	not. For example, a typical tooling scenario includes a writable configuration
	area. If your plug-in is targetted at tooling environments, you are probably
	safe making that assumption. Note however that if somoene tries to use your
	plug-in in a constrained RCP scenario where there is no writable storage, they
	will likely be disappointed.</p>
	<h4>cascading</h4>
	<p>configurators</p>
	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
	Running out of jars</font></b></td>
	</tr>
	</table>
	<p>running out of jars</p>
	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
	The Console</font></b></td>
	</tr>
	</table>
	<p>using the console</p>
	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
	Setting up your workspace</font></b></td>
	</tr>
	</table>
	<p>Users with existing workspaces should not encounter problems opening them with
	the Equinox runtme. However, since the runtime plug-in structure has changed,
	there some updating of classpaths may be required. In particular, developers
	setting up a runtime workspace (i.e., a workspace containing plug-ins) will
	need to either:</p>
	<ul>
	<li>configure the target platform (Preferences->Plug-in Development->Target
	Platform) to include the required plug-ins and then use PDE "required
	plugin" classpath containers on their projects (recommended) or </li>
	<li>add projects (binary or source) for the required plug-ins and setup explicit
	project dependencies for their projects</li>
	</ul>
	<p>Both of these can be accomplished using the PDE Tools->Update classpath
	project context menu. </p>
	<p>The following projects are needed (in addition to the normal set) :</p>
	<ul>
	<li>org.eclipse.osgi</li>
	<li>org.eclipse.core.runtime.compatibility</li>
	<li>org.eclipse.update.configurator</li>
	</ul>
	<p>If you have an existing runtime workspace containing one of the following pre-existing
	plug-ins, it must be updated to accurately match their new contents</p>
	<ul>
	<li>org.eclipse.core.boot</li>
	<li>org.eclipse.core.runtime</li>
	</ul>
	<p>Note that these plug-ins are only required if your plug-in uses the old runtime
	API. If you have adopted the new API (see <a href="#updating">Updating your
	code</a>) then these projects/plug-ins are not needed.</p>
	<p>There should be no need to modify the launch configurations as the runtime
	is self-discovering.</p>
	<table border=0 cellspacing=0 cellpadding=2 width="100%" >
	<tr>
	<td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font color="#FFFFFF">
	Feedback</font></b></td>
	</tr>
	</table>
	<p> Should you encounter any problems while using the Equinox runtime, you are
	encouraged to either log a bug report in the <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Equinox">Equinox
	Bugzilla database</a> or make a posting to the Core <a href="http://dev.eclipse.org/mailman/listinfo/platform-core-dev">mailing
	list</a> or the Platform <a href="news://news.eclipse.org/eclipse.platform">newsgroup</a>.
	</p>
	</body>
	</html>