| <?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); # All on the same line to unclutter the user's desktop' |
| # Begin: page-specific settings. Change these. |
| $pageTitle = "Equinox QuickStart Guide"; |
| $pageKeywords = "equinox, osgi, framework, runtime, resources, quick, start"; |
| $pageAuthor = "Equinox committers"; |
| $html = <<<EOHTML |
| <div id="midcolumn"> |
| <h1><?= $pageTitle ?></h1> |
| |
| <h3>Getting and using the Equinox OSGi implementation</h3> |
| <p>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 <a href="http://download.eclipse.org/eclipse/equinox/">download site</a> 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:</p> |
| <pre> java -jar org.eclipse.osgi_3.2.0.jar -console</pre> |
| <p>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:</p> |
| <ul> |
| <li>install <bundle URL> - Installs the bundle from the given URL</li> |
| <li>start <bundle # or bundle name> - Starts the bundle with the given numeric or symbolic id</li> |
| <li>stop <bundle # or bundle name> - Stops the bundle with the given numeric or symbolic id</li> |
| <li>ss - Reports a summary status of all installed bundles</li> |
| <li>diag <bundle # or bundle name> - Reports any resolution problems for the bundle with the given numeric or symbolic id</li> |
| </li> |
| </ul> |
| |
| <p>If you don't have Eclipse and just want OSGi, click <a href="http://download.eclipse.org/eclipse/equinox/">here</a> to get the JAR from the |
| Equinox download site. </p> |
| |
| |
| <h3>Configurations and all that...</h3> |
| <p>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.</p> |
| <p>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 <em>configuration</em> that |
| lists B1 and B2 as bundles to be installed and started. Set up |
| something like</p> |
| <pre>somedir/ |
| configuration/ |
| config.ini |
| org.eclipse.osgi_3.2.0.jar |
| B1.jar |
| B2.jar</pre> |
| <p>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. </p> |
| <pre> osgi.bundles=B1.jar@start, B2.jar@start |
| eclipse.ignoreApp=true |
| </pre> |
| <p>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 </p> |
| <blockquote> |
| <p> |
| <a href="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/index.html</a></br> |
| <a href="http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html">http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html</a> |
| </p> |
| </blockquote> |
| <p>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</p> |
| <pre>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</pre> |
| <p>Add these bundles on the osgi.bundles list in your config.ini as follows:</p> |
| <pre> osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start</pre> |
| <p>When the Update configurator bundle starts, it automatically discovers and installs all the bundles in the <em>plugins</em> |
| directory that is beside the Equinox JAR. Note that the configurator does not automatically start these bundles.</p> |
| <p>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 <em>plugins</em> directory. |
| Set up something like</p> |
| <pre>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</pre> |
| <p>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.</p> |
| <pre> osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start |
| eclipse.ignoreApp=true |
| osgi.noShutdown=true |
| </pre> |
| <p> |
| Once this is set up you can start equinox with the console using the following command line: |
| </p> |
| <pre> eclipse -console</pre> |
| <p>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</p> |
| <blockquote> |
| <p> |
| <a href="http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/multi_user_installs.html">http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/multi_user_installs.html</a> |
| </p> |
| </blockquote> |
| <p>For those who are interested in some of the Eclipse extensions to OSGi, see</p> |
| <blockquote> |
| <p><a href="http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/bundle_manifest.html">http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.isv/reference/misc/bundle_manifest.html</a></p> |
| </blockquote> |
| <p>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.</p> |
| |
| <h3>Other Information</h3> |
| <ul> |
| <li>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.</li> |
| <li>Log bug reports in the <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Equinox&version=3.3&component=Framework&priority=P3&bug_severity=normal&bug_status=NEW&assigned_to=&cc=&bug_file_loc=&short_desc=&comment=&form_name=enter_bug">Equinox/Framework |
| component</a></li> |
| <li>Questions and comments should go in the <a href="news://news.eclipse.org/eclipse.technology.equinox">equinox</a> newsgroup.</li> |
| <li>Development questions can go to <a href="mailto:equinox-dev@eclipse.org">equinox-dev@eclipse.org</a>.</li> |
| </ul> |
| </div> |
| |
| EOHTML; |
| generateRapPage( $App, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html ); |
| ?> |
