Setup Eclipse for use with Snippets

This article describes how can setup Eclipse to work with the Snippets. It describes how to install the bnd plugin, setup the FileInstall bundle and create a launch configuration for Equinox.

Eclipse and bnd plugin Install

1. download Eclipse from their website and install it according to their instructions.
2. Install the Bnd plugin. You must download the plugin and copy it to the plugins directory from where your eclipse.exe is started (or from the extension folder if used).
3. Restart Eclipse
4. The Eclipse context menu should show "Make Bundle" for *.bnd files. You can also check in Help -> About Eclipse SDK -> Plugin Details, check that you see the bnd plugin (biz.aQute.bnd).

Runtime

To run the code, we need to create a "runtime" project. This project will use the FileInstall bundle as management agent. This bundle tracks the bundles in a folder (load) and will automatically install any bundles in this folders. Removing the bundle from this folder will uninstall the bundle. This makes it very easy to download bundles with a web browser; just save the jar file in the load folder.

To get this started, we need to create a project that can hold the framework jar, the fileinstall.jar and the launch configuration. The launch configuration contains the information to start the Equinox framework. We will start the Equinox framework with a console so we can inspect and manage it from the console.

1. Create a project called runtime (you can of course choose your own name)
2. Create a folder called "jar". This folder will hold the Equinox jar as well as the FileInstall jar. Other bundles will be installed via the load folder created by the FileInstall bundle.
3. Use OBR to download a framework (called system bundle). Save the jar file (named like org.eclipse.osgi_3xxxxx.jar) in the jar folder.
4. Create a launch configuration with Run -> Run as ...
   1. Main class: org.eclipse.core.runtime.adaptor.EclipseStarter
   2. Program Arguments: -console
   3. Classpath: Place the jar/org.eclipse.osgi_3xxx.jar on the user classpath
5. Run! This will create a "jar/configuration" folder that is used by the framework. The Eclipse console now shows "osgi>"
6. Download the FileInstall bundle and place it in the jar folder. We will start this through the console.
7. From the console, start the FileInstall bundle:
   osgi> install file:jar/fileinstall.jar
Bundle id is 1
osgi> start 1
8. This will create a "load" folder in the project. Any bundle in this folder will now be started by the framework.

If you want to know more about the Equinox console, read this article: Explore Eclipse's OSGi console.

Once you have started the Equinox framework, it should normally not be required to restart it. In rare cases this might be necessary, but the normal

To create and run a bundle

The following shows you how to create a bundle with the Bnd tool. This tool is easier to use than the Eclipse PDE, which should therefore not be used. Bnd reads a simple, manifest like, text file and constructs the bundle from this text file. The difference between a manifest is that you can use wildcards. For example, bnd allows you to specify Import-Package: *, bnd will then automatically fill in the import statement from the classes that your code refers to. Bnd also allows you to copy classes and resources from anywhere on the classpath or file system into your bundle.

The development model is therefore as follows. You use Eclipse's JDE (normal Java development, not PDE) for developing your code. Any dependent bundles should be placed on your class path via the project properties. This is plain simple Java development. The bnd tool is a plugin that you can activate through the context menu when selecting a file with the bnd extension: Make Bundle. Activating this entry will create a jar file. This jar file can then be dropped in the load folder to install or update.

1. Create a bnd file with a text editor. A bnd file is a properties file (following the properties format) that acts as a template for the bundle manifest. A minimum bnd file specifies an Export-Package or Private-Package statement. Well designed bnd files also specify the proper Bundle-Description, Bundle-Vendor, Bundle-Copyright etc. headers. Note that the name of the bnd file is used for the Bundle-SymbolicName. For example:
   Export-Package: aQute.helloworld
2. Select the bnd file in the Package Explorer pane and call up the context menu (normally the right mouse button.
   1. Select "Make Bundle"
3. This will create the bundle and store the file in the same directory as the bnd file.
4. Drag the resulting jar into the "load" folder to start it.