Getting and using the Equinox OSGi implementation

The Equinox OSGi framework implementation forms the underpinnings of the Eclipse RCP and IDE platforms but it is in fact a fully standalone OSGi implementation. To run Equinox OSGi on its own either download the org.eclipse.osgi JAR from the download site or look in your Eclipse install for a file like <install location>/eclipse/plugins/org.eclipse.osgi_3.2.0_xxx.jar. Once you have the Equinox framework JAR, use the following command line:

  java -jar org.eclipse.osgi_3.2.0.jar -console

Once this is running you will see an osgi> prompt. This is the OSGi console waiting for you to type commands. Type '?' at the prompt for command help. The most interesting commands for getting started are:

  • install <bundle URL> - Installs the bundle from the given URL
  • start <bundle # or bundle name> - Starts the bundle with the given numeric or symbolic id
  • stop <bundle # or bundle name> - Stops the bundle with the given numeric or symbolic id
  • ss - Reports a summary status of all installed bundles
  • diag <bundle # or bundle name> - Reports any resolution problems for the bundle with the given numeric or symbolic id

If you don't have Eclipse and just want OSGi, click here to get the JAR from the Equinox download site.

Configurations and all that...

The Equinox OSGi implementation is extremely configurable. One of the most common configuration scenarios is to have the framework automatically install and run a set of bundles when it is started. You do this every time you run Eclipse the IDE. Here's how it works and how you can use it in your situation.

Say you have bundles B1.jar and B2.jar that you want to have installed and started when Equinox is run. As with other OSGi implementations, you can run the framework (see above) and install and start B1 and B2 using the console. This is a manual process but you need only do it the first time you run Equinox (OSGi frameworks remember the installed and started bundles from run to run). To do something completely automated, create a configuration that lists B1 and B2 as bundles to be installed and started. Set up something like

somedir/
  configuration/
    config.ini
  org.eclipse.osgi_3.2.0.jar
  B1.jar
  B2.jar

Where config.ini is a Java properties file that contains the following line. Note that the osgi.bundles property is quite powerful. See the doc for details.

  osgi.bundles=B1.jar@start, B2.jar@start
  eclipse.ignoreApp=true

When Equinox is started using the command line above, B1 and B2 are installed and started. If you want to specify a different configuration, just add -configuration <location> to the command line. Notice that since you are just running your bundles, we added a line to tell Equinox to skip trying to start an Eclipse application. This setting is not critical but without it a scary but otherwise inoccuous message appears in your log. For more information on the set of command-line args and system properties available to set things up, see

http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/index.html
http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html

Now, if you want to make things even easier, you can add in a few Eclipse bundles (i.e., org.eclipse.equinox.common and org.eclipse.update.configurator). This gives you automatic bundle discovery/install. Set up something like

somedir/
  configuration/
    config.ini
  org.eclipse.osgi_3.3.0.jar
  org.eclipse.equinox.common_3.3.0.jar
  org.eclipse.update.configurator_3.2.100.jar
  plugins/
    B1.jar
    B2.jar

Add these bundles on the osgi.bundles list in your config.ini as follows:

  osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start

When the Update configurator bundle starts, it automatically discovers and installs all the bundles in the plugins directory that is beside the Equinox JAR. Note that the configurator does not automatically start these bundles.

Finally, if version 3.3 is used, you can add the equinox launcher to your configuration. The equinox launcher comes in 3 pieces: the native executable (eclipse.exe), a shared library (eclipse_1017.dll) and the launcher jar (org.eclipse.equinox.launcher_1.0.0.jar). The executable lives in the root of the eclipse install. The shared library is in a platform specific fragment (i.e. org.eclipse.equinox.launcher.win32.win32.x86). The shared library and the launcher jar live in the plugins directory. Set up something like

somedir/
  configuration/
    config.ini
  eclipse.exe
  plugins/
    org.eclipse.equinox.common_3.3.0.jar
    org.eclipse.equinox.launcher.win32.win32.x86_1.0.0/
      eclipse_1017a.dll
      [other launcher fragment content]
    org.eclipse.equinox.launcher_1.0.0.jar
    org.eclipse.osgi_3.3.0.jar
    org.eclipse.update.configurator_3.2.100.jar
    B1.jar
    B2.jar

When the equinox launcher is used all bundles (including the framework org.eclipse.osgi) must be placed in the plugins directory which is beside the native executable (eclipse.exe). The equinox launcher is configured by default to run an eclipse application. If an eclipse application is not found then the OSGi framework is shutdown and equinox will exit. To prevent this another property must be added to the config.ini (osgi.noShutdown=true). The final config.ini will look like this.

  osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start
  eclipse.ignoreApp=true
  osgi.noShutdown=true

Once this is set up you can start equinox with the console using the following command line:

  eclipse -console

The steps above should get you running with a reasonably flexible configuration of Equinox and a collection of bundles. Eclipse and Equinox offer a significant set of extensibilty and configuration options that are beyond the scope of a getting started document (e.g., extension registry, application model, shared installs, ...). To use the full power of Eclipse, look at how the Eclipse IDE and RCP applications are structures and check out the Help system links above as well as

http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/multi_user_installs.html

For those who are interested in some of the Eclipse extensions to OSGi, see

http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/bundle_manifest.html

Most of these facilities are experimental. Some general and have been proposed for inclusion in the OSGi R4.1 or R5 specifications while others are Eclipse-specific. All were put in place to solve real problems that we (or our consumers) were having. You may be having related problems.

Other Information

  • The Eclipse SDK includes some very sophisticated tooling for defining, developing, debugging, building and deploying bundles. To use this tooling run the SDK and mentally replace the word "Plugin" with "Bundle" in all the menu/wizard entries. For example, File > New > Plugin Project creates a project suitable for coding OSGi bundles. The "Plugin Editor" is really a bundle editor with some extra support for Eclipse constructs such as the Extension registry.
  • Log bug reports in the Equinox/Framework component
  • Questions and comments should go in the equinox newsgroup.
  • Development questions can go to equinox-dev@eclipse.org.
Buy The Book

Equinox News feed
EclipseRT