| <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> |