Knopflerfish Eclipse Plugin

The Knopflerfish Eclipse Plug-in is a tool for launching and debugging the Knopflerfish OSGi distribution. The goal with the plug-in is to simply the use of Knopflerfish for developers using Eclipse as their IDE.

The current version of the plug-in is 1.2.3

Note: If you are upgrading from an earlier version of the plug-in you may need to consult the upgrading instructions.

You can install the latest release from the Knopflerfish update site using the Eclipse software update mechanism:

Eclipse update site: http://www.knopflerfish.org/eclipse-update/

Eclipse Plugin Changelog

The Knopflerfish Eclipse Plugin is available under the Knopflerfish BSD style license

Creating a bundle project

Creating a new bundle project

Select File/New/Project...
Select Bundle Project and enter project info.
A new project is created.

Editing Bundle Manifest

Double click on the bundle.manifest file in your project. The file will be opened in a special editor, which has one tab for a graphical view of the manifest and one tab for a text view. Not all attributes can yet be set through the graphical view, e.g. Import-Package, Export-Package etc. For now you will have to set these attributes in the text view.

TODO: Add attributes to the graphical view and help setting them.

Using Services

This is not yet supported in the plugin. For now you will have to manually add the JAR file containing the service API to your classpath and also edit the bundle manifest Import-Package attribute, see above.

TODO: Support usage of services, by given the service package, automatically find bundle JARs exporting this package, add it to the build classpath and also update the manifest attribute Import-Package.

Running/Debugging

Create a new launch configuration by selecting 'Run...' or 'Debug...' from the Run menu and thereafter select Knopflerfish from the configurations list and press 'New'.

Launch Configuration

Main Tab

The main tab is used for setting which framework to run and where to store the instance data (the .xargs files and the fwdir).

In the main tab a list of known system properties are listed and their default values. When a predefined property is selected a short description is shown. The value can be changed either by double-clicking or selecting 'Edit...'. When a predefined property is changed from its default value it is marked in bold. To restore a property to its default value, edit the property and in the edit dialog select 'Restore Default'. When running/debugging a framework, only properties that differ from their default values are included in the generated .xargs file.

User properties can be added or removed using the 'Add...' or 'Remove' button.

Known Bug: User properties can not be removed.

Bundles Tab

Under this tab you specify the set of bundles that should be launched together with the framework.

Available Bundles is a tree listing all bundles that are either part of the workspace or available through an installed Knopflerfish distribution. Bundles already selected are filtered from the 'Available' tree. Bundles are added to the selected list by selecting them and pressing 'Add'.

Selected Bundles shows a list of the bundles that are currently selected. For each bundle, the start level, mode and missing packages problems are shown.

By default the start level is set to 1 for Knopflerfish bundles and to 2 for workspace bundles. The start level of a bundle can be changed by selecting the start level cell (click on it).

The default value for mode is determined by the bundle's manifest; if a bundle activator exists, mode is set to 'Start'; otherwise it is set to 'Install'. To change the mode of a bundle, select the mode cell for that bundle by clicking on it.

If a bundle imports packages which are not exported by any of the selected bundles, a red error message will be shown in the 'Missing Packages' column indicating the missing package(s).

Basic configurations

This section lists sets of bundles that are needed to run some commonly used applications.

Log

log_all-1.0.0.jar
console_api-1.0.0.jar
cm_api-1.0.0.jar

Log and TTY console

log_all-1.0.0.jar
console_all-1.0.0.jar (Note: console_all is used instead of console_api)
cm_api-1.0.0.jar
consoletty-1.0.0.jar
frameworkcommands-1.0.0.jar
logcommands-1.0.0.jar

Log, TTY console and CM

log_all-1.0.0.jar
console_all-1.0.0.jar
cm_all-1.0.0.jar (Note: cm_all is used instead of cm_api)
consoletty-1.0.0.jar
frameworkcommands-1.0.0.jar
logcommands-1.0.0.jar
crimson-1.1.3.jar (Note: any XML implementation exporting org.xml.sax packages can be used)

Log, TTY console, CM and desktop

log_all-1.0.0.jar
console_all-1.0.0.jar
cm_all-1.0.0.jar
consoletty-1.0.0.jar
frameworkcommands-1.0.0.jar
logcommands-1.0.0.jar
crimson-1.1.3.jar
desktop_all-1.1.0.jar
util-1.0.0.jar

Note: The desktop can show a busy-wait mouse cursor, if this happens position the cursor last in the Eclipse Console and press return a few times.

Packaging Bundle

The contents of the bundle is specified by the bundle.jar file. A special editor is linked to this file, which is opened when the file is selected. The editor allows the contents to be specified either through a graphical view or by directly editing the underlying XML file.

The graphical view has two sections:

Export
Contents

Export

By selecting export the bundle is packaged and exported to the selected destination. The contents of the bundle is set in the contents section.

The contents section specifies all resources that shall be included and where to store them in the bundle JAR file. Each row in the contents table shows a resource that shall be included and consists of the following:

Resource - The path to a file or folder in the current workspace.
Destination - The path to store the resource in the JAR file. The resource contents is stored in the JAR entry specified by destination. If destination is empty it means the JAR root.
Pattern - An regular expression can be specified to filter the resources to be included

By default the bundle.jar specifies the class-files from the output directory to be included in the JAR file.

 <?xml version="1.0" encoding="UTF-8"?>
 <bundlejar>
 <resource dst="" pattern=".*\.class" src="/positron/out"/>
 </bundlejar>