equinox
adoption guide

 

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

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

  1. Download and unzip an Eclipse 3.0 build from 20031111 or later
  2. Download the appropriate Equinox runtime and unzip over the previously installed Eclipse build. When prompted to overwrite, answer Yes to all.
    Note that this destructively modifies the original Eclipse install. The only option for reversing this operation is to re-unzip the original Eclipse installation.
  3. Run Eclipse as normal
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:

http://dev.eclipse.org/viewcvs/index.cgi

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.

Class/Package name changes

In some cases it was necessary to rename packages and/or classes. Below are the mappings from orignal package/class to new package/class:

Method signature changes

While we attempted to avoid gratuitous name changes, certain concepts and structures were eliminated/changed such that references to their related terms had to be removed from the API. This manifests itself in changes to method signatures (method name, return type, argument count/types). The list below details the mapping from original methods to new methods.

Model changes

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.