Equinox p2 cures Eclipse plug-in headaches

Use the new features in Equinox p2 to install Eclipse and its plug-ins

This article explores the new features of Equinox p2, which debuted in Eclipse V3.4. It looks at the pitfalls of the update manager user interface (UI) that was available in earlier versions of Eclipse and shows how the Equinox p2 framework is an improvement. Specifically, it shows how to use the new features in the Equinox p2 framework to install Eclipse and its plug-ins.

Prashant Deva, Founder, Placid Systems

Prashant Deva is the founder of Placid Systems and the author of the ANTLR Studio plug-in for Eclipse. He also provides consulting related to ANTLR and Eclipse plug-in development. He has written several articles related to ANTLR and Eclipse plug-ins, and he frequently contributes ideas and bug reports to Eclipse development teams. He is currently busy creating the next great developer tool.

14 October 2008

Also available in Japanese

The plug-in update facility was completely rewritten in Eclipse V3.4, and it now uses the Equinox p2 framework instead of the update manager. Equinox p2 is a new and highly advanced provisioning system for installing, searching, and managing Eclipse installs, and it is easier to use than its earlier counterpart. This article reviews what was deficient with the old update manager, and explains the new features Equinox p2 offers for installing and updating Eclipse plug-ins.

Plug-in installation problems prior to Eclipse V3.4

Before Eclipse V3.4, installing Eclipse plug-ins was cumbersome. In fact, it was complex enough that only advanced users installed new plug-ins. There were two methods of installing plug-ins: manual download and graphical user interface (GUI).

Manual download and installation

For manual downloads, you had to download the plug-ins manually, then extract some files into the features folder and others into the plugins folder. The features and plugins folders also contained the default plug-ins. As a result, the folders contained many files. Thus, after installing your custom plug-ins, it was almost impossible to figure out which files were yours and which belonged to Eclipse. If you moved to a new version of Eclipse, you had to comb through the features and plugins folders to find your set of custom plug-ins, then copy them to the new installation.

As if that was not confusing enough, you had to restart Eclipse with the -clean argument for the plug-ins to actually get installed. Oftentimes, people would forget about the -clean requirement and wonder why their plug-ins taunted them by failing to appear.

GUI installation

An installation GUI had noble aims. In reality, this method required more than 15 clicks to install a plug-in, and most sites had tutorial pages with images to guide the user on proper installation GUI use. We won’t go into the details of that GUI here because the images needed to explain it would double the length of this article to prove a minor point. Suffice it to say that the whole process for installing plug-ins was a mess before Eclipse V3.4.

Manually installing Eclipse V3.4 plug-ins

The dropins folder in Eclipse V3.4, shown in Figure 1, is the equivalent for the manual process in previous versions of Eclipse, although with less hassle.

Figure 1. The dropins folder
The dropins folder

The dropins folder is contained inside the eclipse folder. To install plug-ins manually, simply drag the plug-in files to the dropins folder and restart Eclipse. There is no need for the -clean argument. For example, in Figure 2, we install the swt spy plug-in by placing the org.Eclipse.swt.spy_1.0.1.jar file in the dropins folder and restarting Eclipse. That's it!

Figure 2. Installing the swt spy plug-in
Installing the swt spy plug-in

Conversely, to remove a plug-in, simply delete it from the dropins folder and restart Eclipse.

Organizing plug-ins

To better organize plug-ins, we can create a folder called swt spy inside the dropins folder and place a plug-in file within it.

Figure 3. Installing the swt spy plug-in inside the SWT Spy folder
Installing the swt spy plug-in inside the SWT Spy folder

Using this method, you can create a folder for every custom plug-in you want to install and place its files within it. This allows for excellent organization of custom plug-ins because they are kept separate from the others. To move to a different Eclipse installation, simply copy the contents of the dropins folder, and all your custom plug-ins will be available in the new install.

There is one disadvantage to this method: Unless the plug-in you install specifies an update site within its files, Eclipse can't check for its updates automatically.

Sharing plug-ins for multiple Eclipse installations

If you use multiple Eclipse installations, you can configure a central, shared dropins folder where you can put Eclipse plug-ins used by all your Eclipse installations. To configure each Eclipse installation to use the central dropins location:

  1. Create a folder that will serve as the central dropins folder (for example, C:\mydropins).
  2. For each Eclipse installation that will use this location, go to the installation directory and open the eclipse.ini file (for example, open C:\Eclipse\Eclipse.ini).
  3. Add the following line to the end of the eclipse.ini file: -Dorg.Eclipse.equinox.p2.reconciler.dropins.directory=C:\mydropins. (Replace C:\mydropins with the path to your central dropins folder.)
  4. Save the Eclipse.ini file and place the required plug-ins in the C:\mydropins folder, just as you would in the local Eclipse dropins folder.
  5. Restart the configured Eclipse installation. You will find that it now recognizes the plug-ins in the central dropins folder.

Note that each Eclipse installation will now have two dropins folders:

  • A local folder (for example, C:\Eclipse\dropins)
  • A central folder (for example, C:\mydropins)

Now, with the central dropins folder configured, you no longer need to duplicate plug-ins for different Eclipse installations. You can still install plug-ins specific to a certain Eclipse installation in its local dropins folder or by using the Equinox p2 Update UI, which we describe in the next section.

Installing Eclipse V3.4 plug-ins using the Equinox p2 Update UI

Now take a look at using the Equinox p2 Update UI from within Eclipse to install plug-ins. To launch the UI, click Help > Software Updates.

Figure 4. Help menu
Help menu

The Software Updates and Add-ons dialog box shown in Figure 5 is displayed. It contains two tabs: The Installed Software tab allows you to update or remove existing plug-ins, and the Available Software tab allows you to install new plug-ins.

Figure 5. Software Updates and Add-ons dialog box
Software Updates and Add-ons dialog box

To install a plug-in, you need the URL of its update site. An update site contains the files and metadata required by Eclipse to download, install, and update the plug-in as needed. Usually the site offering the plug-in provides the URL of the plug-in's update site.

When you have the URL of the update site, click the Available Software tab and click Add Site. Enter the update site URL in the Location box of the Add Site dialog box, shown in Figure 6, then click OK. The site is added to the Available Software list.

Figure 6. Adding an update site
Adding an update site

You can even drag an update site URL straight from your browser to the Available Software list, and it will be added to the list of sites to check for plug-ins.

Expand a site in the list and select the plug-ins you want to install.

Figure 7. Selecting features to install from the update site
Selecting features to install from the update site

Now click Install and follow the instructions on the dialogs that follow. Eventually, you will be prompted to restart Eclipse. Click yes. After Eclipse restarts, the new plug-ins will be installed and running.

Updating plug-ins

To update plug-ins, go to the update UI again by clicking Help > Software Updates. The Installed Software tab lists all the plug-ins you have installed. Select the ones to update and click Update.

Uninstalling plug-ins

Similarly, to uninstall existing plug-ins, select the plug-ins you want to remove in the Installed Software tab and click Uninstall. You may be prompted to restart Eclipse.

Reverting configuration

Eclipse keeps a snapshot of all the plug-ins you install, update, or uninstall. So, if the latest update to your plug-in seems to be causing problems, or if you accidentally uninstalled a plug-in you shouldn't have, you can always revert the Eclipse configuration back to a point when everything was functioning correctly.

To revert to a previous configuration, click Revert Software Configuration on the Installed Software tab. This opens the Revert Software Configuration dialog, shown in Figure 8, which lists all the previous snapshots of Eclipse plug-in configurations.

Figure 8. The Revert Software Configuration dialog
The Revert Software Configuration dialog

Select the configuration you want to revert to and click Finish. You will be prompted to restart Eclipse; click Yes, and upon restart, your configuration will be reverted. To verify, you can check the list of plug-ins in the Installed Software page after restarting to ensure that the list matches your chosen configuration.

Automating updates

You can configure Eclipse to automatically update your plug-ins when new versions are available. Note that this applies only to plug-ins that have update sites. Plug-ins dropped in the dropins folder may not have a specified update site, so Eclipse may not be able to automatically update them.

To configure automatic updates, go to Window > Preferences > Install Updates > Automatic Updates to open the Automatic Updates page.

Figure 9. Automatic Update page
Automatic Update page

Check the box labeled Automatically find new updates and notify me. This will do as far as automatically updating plug-ins is concerned. However, you can also configure various options for automatic updating. You can configure the update schedule to look for updates each time the platform is started or to do so at a specific interval. You can configure updates to be automatically downloaded when they are available, and you will only be interrupted when Eclipse is ready to install them. To do this, select Download new updates automatically and notify me when ready to install them under Download Options. If, however, you want to be notified even before the updates are downloaded, select Search for updates and notify me when they are available. This way, updates won't be downloaded unless you agree.

The options under When updates are found tell Eclipse when to notify you after it has detected that new updates are available. You can select Notify me once about updates to be notified only once (usually when Eclipse is started), or select the other option to be notified at specific intervals.

Using the legacy update manager in Eclipse V3.4

If you still want to use the old update-manager interface despite all the advantages and backward-compatibility of the Equinox p2 Update UI, you can do so. Go to Window > Preferences > General > Capabilities, select Classic Update, and click OK. This enables the legacy update manager UI along with the new Equinox p2 Update UI. The help menu will contain options for both, as shown below.

Figure 10. After enabling the classic update, the Help menu shows both types of update dialogs
After enabling the classic update, the Help menu shows both types of update dialogs

Equinox p2 installer

There is also a small, separate installer you can use to install Eclipse. Using the Equinox p2 installer to download and install Eclipse offers several benefits over doing so manually:

  • It supports multithreaded downloads, allowing for fast downloads.
  • It uses Pack200 compression for files being downloaded. The files are automatically decompressed after being downloaded.
  • It automatically picks the best-possible mirror and can dynamically switch mirrors in case of failure.
  • It supports code certificate validation to ensure that the download is from a trusted source.

You can get the Equinox installer from the Equinox download page (see Resources). After you download the installer, simply unzip it and run it to install Eclipse. After Eclipse is installed, you can safely delete the installer.


This article looked at the features the Equinox p2 framework offers for installing and managing Eclipse plug-ins and how it has improved from the update manager of Eclipse V3.3. For manual installation, it offers the simplicity of the dropins folder, in addition to a powerful, yet simple-to-use GUI for installing plug-ins from their update sites. The shared dropins folder allows for simplified, central management of plug-ins across multiple Eclipse installations. There is, of course, a lot going on under the hood to allow all this to take place, but the Equinox internals are a subject for another article.



Get products and technologies


  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Open source on developerWorks

Zone=Open source
ArticleTitle=Equinox p2 cures Eclipse plug-in headaches