Following on from our earlier series on getting started with OSGi , we're running a series on getting started with Eclipse plug-ins. In this episode, we'll be looking at getting your first plug-in up and running.

In order to create plug-ins, the Eclipse SDK comes with PDE , the Plug-in Development Environment, which allows plug-ins to be developed and tested within Eclipse itself. It's not necessary to use Eclipse to develop Eclipse plug-ins -- there are those that prefer other IDEs such as IntelliJ -- but it's certainly the most commonly used one. We'll assume in this series that you're using Eclipse to create/edit your plug-ins; if you're using another tool, then a useful piece of advice is to use Eclipse to create/generate/verify any of the metadata, share that in a version control system like Subversion , and then use your other favourite tool for the Java editing/compilation.

Eclipse itself is built upon OSGi, and the term bundle is sometimes used interchangeably with plug-in . You can therefore apply what you know about OSGi bundles to Eclipse applications, and for that matter, vice-versa. Also, on a point of pedantry; plug-in should be hyphenated, although you'll find many references referring to plugin instead.

Let's get started at running our first plug-in with Eclipse. In this case, we'll just let Eclipse create a default one for us with a template to get used to the concepts and running it.

All plug-ins are created with a plug-in project. We'll create a Hello World project using the built in new project wizard, by doing the following:

• File -> New -> Project
• Plug-in project
• Next
• Name: Hello World
• Next
• Next
• Ensure the 'Create a plug-in using one of the templates' is selected, and choose 'Hello, World'
• Finish

Don't worry too much about what the individual options were on the plug-in wizard; this is supposed to be our first plug-in, after all. We'll be covering what each of these mean/do in subsequent episodes.

You should now have a plug-in that contains (amongst others):

plugin.xml
META-INF\MANIFEST.MF
src\hello_world\Activator.java
src\hello_world\actions\SampleAction.java

The plugin.xml contains meta-information for Eclipse, and contains (amongst others) the extension points declared/used by this plug-in (and note, it's plugin.xml and not plug-in.xml ; just one of the reasons why you can't search-and-replace when you're writing documentation on Eclipse plug-ins ...) We'll be talking about extension points in a subsequent post.

The MANIFEST.MF is a standard Jar manifest, but contains meta-information used by Equinox, which is Eclipse's internal OSGi engine. Although there are specific entries in here for Eclipse (such as Eclipse-LazyStart ) the majority of entries here are standard OSGi.

The Activator is run when your plug-in starts, and before any other code that's defined in your bundle is used. You can use this to initialise data structures, start listening to network sockets etc. It's also got a corresponding call when it's stopped, usually when Eclipse shuts down.

Last (but not least), the SampleAction , which just prints out "Hello, Eclipse World" when you click on the little blue Eclipse icon in the toolbar. When we've talked about extension points, we'll dig into how this is called; but for now, it's enough to know that it is called.

Having created our first plug-in, we need to know how to launch it. Eclipse uses the concept of launch configurations ; essentially, they're like individual batch files or shell scripts for launching code (except you don't get to see the command line arguments). Rather, each application type has its own entry (e.g. JUnit test, Java application, Eclipse application) and each has a different set of fields that you can fill in. One gets created for you the first time you do Run As... , and thereafter gets re-used.

So, to launch our first Eclipse application, right-click* on the project, and select Run As... and choose Eclipse Application from the list. A new Eclipse workbench should open, and after dismissing the intro screen, you should see a blue Eclipse logo in the toolbar; clicking on that will bring up the dialog "Hello, Eclipse World".

You can change the message; switch back to the other Eclipse instance (sometimes called the 'development' or 'host' workbench/Eclipse) and open the src\hello_world\SampleAction.java class; change/save the message to something else, like "Hello, Again World", and then save it (so that it gets recompiled). If you switch back to the newly launched Eclipse instance (sometimes called the 'runtime' workbench/Eclipse) and click on the button, nothing changes. Oh well ...

Fortunately, you can use Eclipse to debug a runtime instance, too. Close down the runtime Eclipse instance, and this time, do Debug As... and choose Eclipse Application . It will bring the Eclipse instance up again (albeit possibly slightly slower) and you'll be able to skip the intro page and click on the Eclipse icon in the toolbar to see "Hello, Again World". Now, switch back to the host Eclipse instance, and change the message to say "Hello, There World". Switch to the runtime Eclipse instance, and your new message will be shown in all its glory.

Congratulations, you've just created, run and debugged your first Eclipse plug-in. In the next exciting instalment we'll cover what an extension point is, and how that Eclipse icon was put on the toolbar in the first place.

A copy of the project is attached for those that want to drop it into an eclipse/plugins folder, or want to see the source code in a different editor.

* Fellow Mac users: you can Control-Click to get the pop-up menu; you can also use the menus themselves (Run -> Run As ...) or buy a mighty mouse . The wireless one is cool.