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
For those who are interested in some of the Eclipse extensions to OSGi, see
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.
Equinox News 
