This is an old revision of the document!
A “Headless Eclipse” is an instance of Eclipse launched without any Graphical User Interface, on the command-line.
You can use a Headless Eclipse to call a plug-in in Eclipse from some external programs. One of the purposes of such a call, as seen with SQUANER, is to automatically delegate processing to Eclipse from a Web application. Indeed, to create the PADL model of a C++ project, SQUANER asks Eclipse to parse the C++ project and to return its model.
First, create your plug-in with the Eclipse IDE, within the Plug-in Development Environment (PDE). In the plugin.xml file of your plug-in (root level of the project), give a specific ID to your plugin. You should have a file like this:
<?xml version=“1.0” encoding=“UTF-8”?>
Then, download a second Eclipse that will be used to run your plug-in, i.e., the Headless Eclipse. From the first Eclipse IDE, export your plugin (right-click on your plugin project > Export > Plug-in Development > Deployable plug-ins and framents). Check all needed plugins and export them to the eclipse root folder of your Headless Eclipse (the plugins will automatically be put in the plugins folder).
Finally, open a shell on the eclipse root folder of your Headless Eclipse and use the following command:
java -cp plugins/org.eclipse.equinox.launcher_1.3.0.v20120522-1813.jar org.eclipse.equinox.launcher.Main -application Name_of_your_plugin_project.Id_of_the_plugin
The version of the JAR archive may change in time; just check the name of the library eclipse/plugin/org.eclipse.equinox.launcher_* and modify the command consequently.
If you see this error in the log file, after launching your headless application, in most cases it means you may have a dependendy issue. Check all the manifest files of your plugin projects and localize all needed resources. Let's remind than a plugin should only depend on other plugins. Not a Java project, not an external library… If you need to use a library, you can create a plugin from the library (in Eclipse IDE, right-click on the Package Exporer > New > Other > Plug-in Development > Plug-in from Existing JAR Archives). Then let your plugin depend on the freshly plug-ined library thanks to the Manifest > Dependencies tab > Required Plug-ins.
It happens that if you use the plugin automatic export, some archives do not contain the class definitions… One solution is to manually export a jar archive of the project with needed class definitions, and rename it to replace the empty archive. One anti-solution is to add the manually exported archive in the class path.
When calling Eclipse programmatically, the reason is often to call from a program some plug-in to perform some computations, thus benefiting from Eclipse rich set of plug-ins, and then get an object as results from these computations to be used in the rest of the program. Exchanging objects between Eclipse and the rest of the program means that Eclipse must be told to use the same classes for these objects as the rest of the program. Hence, it must be told to use the same class-loader for these classes or, really, must be instructed to by-pass its class-loading mechanism to directly as the JVM system class-loader, also called application class-loader, instance of
To instruct Eclipse to by-pass its class-loading mechanism, the plug-in must be configured so that its
MANIFEST.MF file uses the
Import-Package statement to declares which packages will come from “somewhere else”, not a particular plug-in. Then, Eclipse must be run with the osgi.compatibility.bootdelegation property set to
true. Finally, the configuration file
Config.ini of the headless Eclipse workspace must include the org.osgi.framework.system.packages.extra statement must match one-for-one the list of imported packages in the
If there is a discrepancy between the
Config.ini files, Eclipse will use its class-loading mechanism and the objects returned by the plug-in and expected by the program will belong to different classes, because loaded by different class-loaders.
When using the
Import-Package statement and if the plug-in shares some common package with another plug-in, Eclipse gets confused and claims that other plug-in cannot use classes in this package, even if it is exported by all the plug-ins involved. Therefore, it is important to have different packages, which can of defeat the purpose of having plug-in in the first place. It is true, though, that
Import-Package statement, by instructing Eclipse to by-pass its class-loading mechanism, disturb this mechanism.