equinox |
Summary
This document details how to move from running the standard Eclipse runtime to using the new Equinox runtime. Any API changes are documented in the Migration Guide and information on how to use the new runtime is contained in the Users Guide.
Last Modified: 2300 November 25, 2003As of the nightly build on Nov 25, 2003, Eclipse includes the Equinox runtime as standard. That is, the original runtime has been replaced. M5 and the integration builds for Nov 25/26 still contain the original runtime. All later integration builds will contain the Equinox runtime.
Getting/installing the Equinox Runtime |
The Equinox project has developed an alternate runtime for Eclipse. Depending
on the Eclipse build you are using the Equinox runtime may already be included.
To check, look for a plug-in called org.eclipse.osgi in your install's plugins
directory. If you have Equinox already, you can skip these steps.
The Equinox runtime is plug compatible with the standard Eclipse runtime subject to the changes detailed in the Migration Guide. To get, install and use the Equinox runtime, follow the steps below.
Setting up your workspace |
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:
Both of these can be accomplished using the PDE Tools->Update classpath project context menu.
The following projects are needed (in addition to the normal set) :
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
Note that org.eclipse.core.boot, org.eclipse.core.runtime and org.eclipse.core.runtime.compatibility are only required if your plug-in uses the old runtime API. If you have adopted the new API (see Updating your code) then these projects/plug-ins are not needed.
There should be no need to modify the launch configurations as the runtime is self-discovering.
Updating your build.xml files |
Developers maintaining scripts (e.g., Ant build.xml files) which compile code will most likely have to update the classpath entries for their <javac> tasks. In particular, a number of new plug-ins were introduced and some code moved around. For most people these changes are transparent.
If you have custom build.xml scripts which compile code against org.eclipse.core.runtime, you will need to update the scripts. Typically your script will contain a classpath entry in a <javac> task that references org.eclipse.core.runtime as follows:
../org.eclipse.core.runtime/bin;../org.eclipse.core.runtime/runtime.jar
The runtime plug-in is now empty. The code has been replaced or moved to a number of other plug-ins/jars. While the complete set is listed below, typical uses require only a subset on the classpath at compile time. You should remove the runtime entries add the entries below as needed to make your <javac> tasks run without errors. As usual, the inclusion of the /bin directories is at your discretion. The entries are given here in logical groupings by supplying plug-in:
While you are updating the script, you should also take the opportunity to
clean up (i.e., remove) references to org.eclipse.core.boot. This plugin
no longer contains any code. You can leave the entries on the classpath but
they serve no purpose so should probably be removed. Look to remove:
../org.eclipse.core.boot/bin;../org.eclipse.core.boot/boot.jar
Getting the source |
Source is included in the Eclipse SDK drops as well as the Equinox alternative runtime drops. Developers can also browse the source in the CVS repository at:
Or check-out the appropriate projects using anonymous access to the CVS repo as follows:
:pserver:anonymous@dev.eclipse.org/home/eclipse
In either case, the projects of interest are listed below:
The following projects/plug-ins form the compatibility layer:
Updating your code |
The new runtime is 99% binary compatible with the original Eclipse runtime. As such, most existing plug-ins will continue to run unchanged.
Having said that, there are costs associated with the compatibilty layer and the full power of the new runtime is not available. Plug-in developers interested in additional performance and function should consider adopting the new APIs and removing their dependence on the compatibility layer.
As outlined above, the following plug-ins are deprecated and are no longer part of the official runtime API:
All of the code in these plug-ins has been marked as deprecated so you should see compiler warnings if you are using the old function. If your code is typical and has not been migrated, you will see a number of the deprecations listed below. Also listed are the steps for updating your code to use the new API.
In some cases it was necessary to rename packages and/or classes. Below are the mappings from orignal package/class to new package/class:
Model changes are more fundamental. They represent a new way of doing something. Typically requiring new structures, new classes/methods and new algorithms.
Plugin registry
Updating your plugin.xml/fragment.xml |
The new runtime is based on an implementation of the OSGi framework specification. The OSGi specificaiton mandates the use of manifest.mf files to define the execution of a plug-in. This conflicts with the Eclipse notion of plugin.xml as far as <runtime> and <requires> are concerned. To address this, the new runtime allows for either style of manifest.
Feedback |
Should you encounter any problems while using the Equinox runtime, you are encouraged to either log a bug report in the Equinox Bugzilla database or make a posting to the Core mailing list or the Platform newsgroup.