Contributing to Eclipse

Nov 24, 2023 . 4 min read

Contributing to Eclipse: Principles, Patterns, and Plug-Ins by Kent Beck and Erich Gamma is a beautifully crafted book on Eclipse Plugin Development which came out in 2003. Somewhere around 2010 I bought the book; by that time, the example code used in the book for the Eclipse 2 platform was already outdated. How much ever I tried, I could not fix and run the code in Eclipse Platform 3. Without the running plugin, soon I gave up and put away the book.

Thereafter I gave away many of my books but I don’t know why, this one was always stayed in the shelf. Recently, I wanted to develop a plugin for my own software uKnit, a unit test generator. I went through some of the latest books on the subject, but they were not very helpful. Then I dusted this one out, and to my surprise it had many recipes that I wanted. But, on the code front, Eclipse platform has moved on to 4. I thought I will give one more try and fix the sample code. Soon I got the hang and able to bring up the plugin. By the time I finish reading the book, I had the complete working plugins. To my surprise, more than 90% of original e2 code still works in e4 platform; I made small changes here and there. Now the book example is up and running, why not share as it may be useful to some.

This post explains the installation, setup and usage of example code of the book. The original code is slightly refactored to run on Eclipse 3 and 4 platforms.

Installation

The Eclipse Plugins are developed in Eclipse PDE, also known as Eclipse IDE for Eclipse Committers. Download it from the Eclipse download page and install.

To install and run the example plugins use a separate, dedicated workspace. It is better to use dedicated workspace as we are going to directly clone the git repo into it; otherwise your existing projects are shown as untracked files when you run git status. For the sake of explanation, we use $HOME/eclipse-pde-workspace as the dedicated workspace, but any other location or folder is also fine. Create a empty workspace and clone the project from Github,


mkdir $HOME/eclipse-pde-workspace
git clone https://github.com/maithilish/contributing-to-eclipse-example-code.git $HOME/eclipse-pde-workspace

Start the Eclipse PDE (i.e. Eclipse IDE for Eclipse Committers) and choose $HOME/eclipse-pde-workspace as the workspace.

The cloned repo contains three plugin projects - org.eclipse.contribution.hello, org.eclipse.contribution.junit and org.eclipse.contribution.junit.test. You have to import these three project into IDE.

Go to Import -> Plug-in Development -> Plug-ins and Fragments, in the wizard do the following,

  • In Import From dialog, select Directory option, then browse and select the $HOME/eclipse-pde-workspace where you have cloned the plugins.
  • In Import As dialog, select Projects with source folders option; click Next.
  • In Selection dialog, click Add All to add all the three plugins - org.eclipse.contribution.hello, org.eclipse.contribution.junit and org.eclipse.contribution.junit.test; click Finish to complete the import.

Check status with git status and in case, any file is altered by the import, restore them with,


git restore org.eclipse.contribution.*

This step is important else you will not be able to run the plugins. Check the status with git status and it should return the message,‘On branch main, Your branch is up to date’.

The example source is chapter wise branched. As you start reading a new chapter, you can checkout that chapter branch, and you will find the plugin state as appears in that chapter. There are some chapters - Chapter 1, 2, 4, 11, 15 - without any code and there is no branches for such chapters.

There is no code in Chapter 1 and 2, so when you start reading Chapter 3,


cd $HOME/eclipse-pde-workspace
git checkout chapter-3

Read the readme.md; do the setup, and run the plugin as explained in it. Repeat the process for other chapters.

Readme file

Each branch has separate readme.md with instructions specific to that chapter. It explains how to setup, run the tests and the plugin for that chapter. Don’t forget to go through the readme.md after each checkout!

Notes

PDE Workspaces: When you run plugins in $HOME/eclipse-pde-workspace as Eclipse Application, it creates a new workspace $HOME/runtime-EclipseApplication. Similarly, when run tests written for the plugin, it creates another workspace $HOME/junit-workspace. All in all, you will end up with three workspaces when working with Eclipse PDE.

Deprecated code: In Java classes deprecated methods are replaced with the latest ones. If something is discontinued in Eclipse 3 or 4, then they are replaced with workarounds. However, in plugin.xml the deprecated items - such as Action, ActionSet, ObjectContribution etc., - are retained as replacing them with the later alternatives would make the code difficult to follow while reading the book. There are around 12 such items and reported as warnings in PDE Problems view.