Eclipse Launcher

Description

Eclipse contains a native executable launcher that is used to start Eclipse. There is more to the launcher than just the eclipse executable in the root of the install.

The launcher and its shared library

The launcher executable comes in 2 pieces: the executable (eclipse.exe), and a shared library (eclipse_1017.dll). The executable lives in the root of the eclipse install. The shared library is in a platform specific fragment, org.eclipse.equinox.launcher.[config], in the plugins directory.

Having the majority of the launcher code in a shared library that lives in a fragment means that that portion of the launch code can now be updated from an update site. Also, when starting from java, the shared library can be loaded via JNI in order to display the splash screen.

The launcher bundle

Previous versions of Eclipse had a startup.jar JAR file in the root of the install. In 3.3, this code has been moved to a plug-in org.eclipse.equinox.launcher in the plugins directory. Eclipse can still be started directly with java using, for example:

java -jar plugins/org.eclipse.equinox.launcher_1.0.0.v20070606.jar

Launching Eclipse involves 3 main pieces: the native executable, the launcher platform specific fragment and the launcher jar. In the example below, notice that the launcher fragment is in folder form, this is necessary so that the native eclipse.exe can load the shared library:

eclipse/ 
	eclipse.exe
	plugins/
		org.eclipse.equinox.launcher_1.0.0.v20070606.jar
		org.eclipse.equinox.launcher.win32.win32.x86_1.0.0.v20070523/
			eclipse_1017a.dll

The version numbers above are for illustration purposes only (e.g. 1.0.0.v20070606). The actual version numbers may vary depending on the version of Eclipse you are using.

Finding a VM and using the JNI Invocation API

The Eclipse launcher is capable of loading the Java VM in the eclipse process using the Java Native Interface Invocation API. The launcher is still capable of starting the Java VM in a separate process the same as previous version of Eclipse did. Which method is used depends on how the VM was found.

No -vm specified

When no -vm is specified, the launcher looks for a virtual machine first in a jre directory in the root of eclipse and then on the search path. If java is found in either location, then the launcher looks for a jvm shared library (jvm.dll on Windows, libjvm.so on *nix platforms) relative to that java executable.

If a jvm shared library is found the launcher loads it and uses the JNI invocation API to start the vm.
If no jvm shared library is found, the launcher executes the java launcher to start the vm in a new process.

-vm specified on the command line or in eclipse.ini

Eclipse can be started with "-vm <location>" to indicate a virtual machine to use. There are several possibilities for the value of <location>:

directory: <location> is a directory. We look in that directory for: (1) a java launcher or (2) the jvm shared library. If we find the jvm shared library, we use JNI invocation. If we find a launcher, we attempt to find a jvm library in known locations relative to the launcher. If we find one, we use JNI invocation. If no jvm library is found, we exec java in a new process.
java.exe/javaw.exe: <location> is a path to a java launcher. We exec that java launcher to start the vm in a new process.
jvm dll or so: <location> is a path to a jvm shared library. We attempt to load that library and use the JNI Invocation API to start the vm in the current process.

Exceptions

linux.ppc, linux.x86_64, aix.ppc: The launcher is not able to load some older vms using the JNI invocation API. By default on these platforms the launcher will prefer to execute java in a separate process. To force the launcher to load the vm using JNI, specify a -vm option pointing directly to the vm's shared library (libjvm.so).
MacOSX: The launcher uses the system JavaVM framework and will always load the vm in-process using the JNI invocation API.