LearningEclipse

About this page

During November 2007 I started to work on a small educational project for an MAS course at the Hochschule Luzern (Lucerne University of Applied Sciences and Arts). The goal of the project was to learn more about the OSGi specification, and specifically plugin development with and for Eclipse. Besides gaining knowledge, the more or less :-) tangible product of the project was the fledgling version of an Eclipse plugin which I dubbed doxystub.

This page tries to give an overview about what I learned. Its main purpose is to serve as a reference point that I can come back to in the future, when I will take up again with enhancing doxystub, or developing some other plugin or software in Eclipse.

Introductory reading

I found the following reading material useful in order to get an introduction to OSGi and how it relates to Eclipse. I present an ordered list because I found the reading order appropriate:

1. OSGi Basics
2. OSGi Technical Whitepaper
3. OSGi and Eclipse
4. Equinox Quickstart
5. OSGi Console of Eclipse

Other documentation

• Eclipse Resources: A number of useful articles of varying depth
• The Official Eclipse FAQs: Not merely one FAQ, but a multitude of them. These are useful at least to get an overview of the main structure of the project.

Update Sites

The online help provides information about the different project types required to set up an update site.

Feature project

• File -> New -> Project -> Plugin Development -> Feature Project
• give the project a useful name, e.g. ch.herzbube.doxystub.feature
• fill any other details of your choice
• select "initialize from the plugins list"
• select the plugin(s) for which you want to have an Update Site
• in the resulting new project, double-click the feature.xml file
  • this opens the "Feature Manifest Editor"
  • help for this editor is available under "Plug-in Development Environment Guide" -> Tools -> Editors -> Feature Manifest Editor
• go to the "overview" tab and enter values for the "update site URL" and "update site name" fields; for instance
  • update site URL = http://www.herzbube.ch/doxystub/
  • update site name = Update site for the doxystub Eclipse plugin
• go to the "plug-ins" tab, select each plugin and make sure that its "version" field is set to the value "0.0.0" (should be the case)
  • "0.0.0" is a special value that will be replaced by the actual version of the plugin when the feature is exported (i.e. when the update site is built)
  • this should work by default; if it doesn't, click the "versions..." button for the plugin and make sure that in the next dialog the "synchronize versions on build" radio button is selected
• go to the "dependencies" tab, then select "Compute" to let Eclipse automatically calculate dependencies for the new plugin; edit the dependencies if the information is not specific enough

Update project

• File -> New -> Project -> Plugin Development -> Update Site Project
• give the project a useful name, e.g. ch.herzbube.doxystub.update
• in the resulting new project, double-click the site.xml file
  • this opens the "Site Manifest Editor"
  • help for this editor is available under "Plug-in Development Environment Guide" -> Tools -> Editors -> Site Manifest Editor
• go to the "site map" tab, then click the "add feature..." button
• select the feature project created above
• go to the "archives" tab, then fill in the fields with appropriate values; for instance
  • URL = http://www.herzbube.ch/doxystub/
  • Description = Update site for the doxystub Eclipse plugin
• go back to the "site map" tab, then click the "build all" button to build all features

Publish the update site

• push the site.xml file and the folders features and plugins to a location where users can reach it through your web server
• choose the same location that you entered for the "update site URL" in the feature project

Note: Plugins and features can be exported manually without an update site project. This happens through File -> Export -> Plugin Development -> Deployable Features / Deployable plugins and fragments. The exported files can be imported by their counterpart importers.

Helpful resources:

• How To Keep Up To Date (Aug. 2003): http://www.eclipse.org/articles/Article-Update/keeping-up-to-date.html. This article is slightly out-of-date, but contains still valid and useful information about the purpose of feature and update site projects, and about the process of providing plugin updates (i.e. adding a new version of the plugin to an update site)
• Put Eclipse features to work for you (Oct. 2003): http://www.ibm.com/developerworks/opensource/library/os-ecfeat/. Haven't read this article yet, citing it here for reference.

OSGi / Equinox

The console

The following command brings up the pure OSGi console of Eclipse in a terminal (example is for Ganymede SR2, replace the .jar file name by something appropriate):

java -jar /Applications/Eclipse/plugins/org.eclipse.osgi_3.4.3.R34x_v20081215-1030.jar -console

The following command also displays an OSGi console, but actually tries to launch the Eclipse application in parallel. This one is good to debug problems with plugins that prevent Eclipse from launching. The -noExit argument prevents the OSGi console from quitting after the Eclipse GUI terminates (e.g. after you have confirmed the GUI error message box that tells you that something went wrong).

/Applications/Eclipse/Eclipse.app/Contents/MacOS/eclipse -console -noExit

A couple of useful commands:

• help
• close: terminate the console in a controlled fashion; exit also does this, but is more forceful
• ss: displays installed bundles ("short status")
• diag nnn: prints diagnostics about bundle nnn (nnn is the numeric reference to the bundle; you get this when you issue the ss command)
• bundle nnn: prints interesting details about bundle nnn
• sl nnn: prints the start level of bundle nnn (or of the OSGi framework if no bundle ID is specified)
• uninstall nnn: uninstalls bundle nnn; remains uninstalled when you run the application the next time

Glossary

Eclipse terms:

RCP 

Rich Client Platform

EMF 

Eclipse Modeling Framework

GEF 

Graphical Editor Framework

Mylyn 

Plugin for task-focused development

WST 

Web Standard Tools

PDE 

Plugin Development Environment

ECF 

Eclipse Communication Framework

DLTK 

Dynamic Languages Toolkit

WTP 

Web Tools Platform

RSE 

Remote System Explorer, which is a part of the "Target Management" project (which in its own turn is a subproject of the DSDP project)

DTP 

Data Tools Platform (part of JEE and Reporting packages)

JDT 

Java Development Tools

CDT 

C/C++ Development Tools

PDT 

PHP Development Tools

DSDP 

Device Software Development Platform

UDC 

Usage Data Collector

SWT 

The Standard Widget Toolkit

Eclipsepedia 

The eclipse.org Wiki

Eclipse Project 

Quoting from Eclipsepedia: "The unfortunately named "Eclipse Project" is the project dedicated to producing the Eclipse SDK. This name made sense back when there were only two or three projects at Eclipse, but now it is frequently referred to as the "Eclipse top-level project" to reduce confusion (or just "The Platform" when we're feeling grandiose). This project in turn is composed of four sub-projects: Platform, Java development tools (JDT), Plug-in Development Environment (PDE), and Eclipse/Incubator. Until the Ganymede release, the Eclipse project also contained the Equinox subproject, but this project has since moved to the RT top level project. There is a proposed fifth sub-project, code-named e4, exploring technologies for the next generation of the Eclipse platform."

Eclipse Project SDK 

An entry that can be seen in "The Eclipse Project Updates" update site for Ganymede. I don't know what this is. The information dialog shows the identifier org.eclipse.sdk.feature.group

Eclipse Platform SDK 

An entry that can be seen in "The Eclipse Project Updates" update site for Ganymede. I don't know what this is. The information dialog shows the identifier org.eclipse.platform.sdk

Eclipse SDK 

An entry that can be seen in "The Eclipse Project Updates" update site for Ganymede. I don't know what this is. The information dialog shows the identifier org.eclipse.sdk.ide

JFace 

Quoting from the FAQ: "JFace is a Java application framework based on SWT. The goal of JFace is to provide a set of reusable components that make it easier to write a Java-based GUI application. Among the components JFace provides are such familiar GUI concepts as wizards, preference pages, actions, and dialogs. [...] JFace does not make use of such Eclipse-specific concepts as extensions and extension points."

Links

• EasyEclipse: Eclipse distribution that promises stability (using plugin versions that go together), simple installation & upgrade

Plugin notes

Subclipse

• Installation notes: http://subclipse.tigris.org/faq.html
• Introductory article: http://www-128.ibm.com/developerworks/opensource/library/os-ecl-subversion/
• JavaHL on Mac OS X
  • when first installed, Subclipse is configured to use the "JavaHL" interface to Subversion
  • on Mac OS X this interface is not readily available
  • I have therefore configured Subclipse to use the alternative "SVNKit" interface (Preferences->Team->SVN)
  • possible sources where JavaHL can be obtained:
    • part of the CollabNet binaries: http://downloads.open.collab.net/binaries.html
    • or can be installed through fink: package name is svn-javahl

Examples

Install the Eclipse SDK examples

• Using the update site "The Eclipse Project Updates"
• Install "Uncategorized -> Eclipse SDK Examples"

After installation the examples are available through

• Window->Show View->Other->SWT Examples->SWT Example Launcher