Equinox Launcher Plan

The following is a proposal for the new Equinox Launcher in support of the 3.3 plan item for improving the launching experience [1]. This work will need to happen in conjunction with any changes that are being made to startup.jar [2][3]. This new launcher will do the following:

• Use JNI to start the VM [4]
• Allow for updating the launcher
• Allow for SWT widgets in the splash screen [5][6]

JNI Launching

Instead of execing java, the equinox launcher will load the jvm shared library and use JNI to create the vm. To do this the launcher will need to do the following:

• Find the jvm shared library.
• Setup the LD_LIBRARY_PATH on those platforms that require it.
• Find the startup.jar. By default it is simply startup.jar in the root of eclipse. The launcher also supports specifying the jar using the -jar argument.
• Find the Main class. We don't want to parse the manifest to get the Main-Class header. By default we will assume org.eclipse.core.launcher.Main. We should provide an argument -class where this can be specified.
• Start the VM using JNI, and invoke the Main.main(String[]) method.

Finding the shared Library

We have an existing strategy for finding a java executable. We should look for the jvm library in a location relative to the java executable.

• We should also allow the user to specify the library directly using the -vm argument.
• We should also support reading a properties file containing the needed information. The Apache Harmony project [7] has similar requirements.

• Some VMs will contain more than one library (ie client & server, or j9vm & classic). The launcher will need to understand the JRE's arguments that are used to select a particular vm (-client, -server, -hotspot, -Xj9)
• On Windows, we may also need to consult the registry to find the vm library. The key [HKCU|HKLM]\Software\JavaSoft\Java Runtime Environment lists installed jvms by version number.

Adding JNI Callback methods

Using JNI to launch the VM allows us to register native methods that can be called from Java. These methods can be use to avoid having Java exec the launcher in order to pass information back through shared memory. They can also be used in support of an SWT splash screen.

Splitting the Launcher into Executable and Library

We should split the launcher into a small executable and a separate shared library. The executable would simply parse the eclipse.ini file and find the appropriate eclipse shared library. The shared library would do all the other work (showing a splash screen, launching the vm). This will allow the following:

• When the user starts eclipse by invoking Java directly, the startup code can load the eclipse library in order to display a splash screen. One particular use case here is self hosting.
• The shared library can be versioned, allowing us to update the launcher by simply dropping in a new library.
• The shared library can in theory be loaded by others to start eclipse in a custom manner.
• The eclipse.ini can now be used to potentially choose between different launchers

SWT Splash Screen

The launcher should display a static splash screen bitmap as soon as possible.

• The bitmap to display should be specified as an argument (on the command line or in eclipse.ini) If no argument is specified, as can look for a splash.bmp in the root of eclipse. Products should be encouraged to specify this argument as it will enable showing the splash screen earlier than what is currently possible.
• If no bitmap is found, we should register a showSplash method with the VM so that startup.jar can call back with the location of a bitmap to display. This is analagous to the current method of startup.jar execing another launcher with the location of the bitmap to display, except that this is cleaner in that it does not involve a separate process.

The splash screen is displayed natively on the main thread and then we start the VM. The handle to the splash window is passed to java through JNI. Once SWT is loaded, this handle can then be used to create a Shell around the splash screen. This requires support from SWT. The native splash window will need to be created in prescribed manner so that SWT can easily wrap it with a Shell.

Native methods to register with startup.jar include the following:

1. showSplash: display a splash screen or update the bitmap of an existing splash screen
2. dispatchMessages: process any events (ie paint) for the splash that may be waiting
3. closeSplash: close the splash screen
4. getSplashHandle: get the handle of an existing splash screen

Links

1. Bug 154088 Improve the launching experience.
2. Bug 159122 Move the startup.jar code
3. Bug 107738 Investigate if the startup.jar can be delivered as a plugin.
4. Bug 82518 Use JNI to Launch Eclipse
5. Bug 111539 Report splash screen progress based on jobs.
6. Bug 141792 API for custom startup progress reporting.
7. Apache Harmony