The Eclipse Program Launcher

This program performs the launching of the java VM used to start the Eclipse or RCP java application.

Program options

The options that can be specified by the user to the launcher are:

`-vm <javaVM>`	the Java VM to be used
`-os <opSys>`	the operating system being run on
`-arch <osArch>`	the hardware architecture of the OS: x86, sparc, hp9000
`-ws <gui>`	the window system to be used: win32, motif, gtk, ...
`-nosplash`	do not display the splash screen. The java application will not receive the -showsplash command.
`-name <name>`	application name displayed in error message dialogs and splash screen window. Default value is computed from the name of the executable - with the first letter capitalized if possible. e.g. eclipse.exe defaults to the name Eclipse.
`-startup`	the startup jar to execute. The argument is first assumed to be relative to the path of the launcher. If such a file does not exist, the argument is then treated as an absolute path. The default is to execute a jar called startup.jar in the folder where the launcher is located. The jar must be an executable jar. e.g. -startup myfolder/myJar.jar will cause the launcher to start the application: java -jar <launcher folder>/myfolder/myJar.jar
`<userArgs>`	arguments that are passed along to the Java application (i.e, -data <path>, -debug, -console, -consoleLog, etc)
`-vmargs <userVMargs> ...`	a list of arguments for the VM itself

The -vmargs option and all user specified VM arguments must appear at the end of the command line, after all arguments that are being passed to Java application.

Configuration file:

The launcher gets arguments from the command line and/or from a configuration file.
The configuration file must have the same name and location as the launcher executable and the extension .ini. For example, the eclipse.ini configuration file must be in the same folder as the eclipse.exe or eclipse executable.
The format of the ini file matches that of the command line arguments - one argument per line.
In general, the settings of the config file are expected to be overriden by the command line.
- launcher arguments (-os, -arch...) set in the config file are overriden by the command line
- the -vmargs from the command line replaces in its entirety the -vmargs from the config file.
- user arguments from the config file are prepended to the user arguments defined in the config file. This is consistent with the java behaviour in the following case: java -Dtest="one" -Dtest="two" ... : test is set to the value "two"
The sample configuration file 'eclipse.ini' below gives the name and the VM location to the eclipse launcher. Save it in the folder containing the eclipse launcher. Then simply start: eclipse

The following configuration file is equivalent to the command line: eclipse -name "My Java IDE" -vm c:\jre\bin\java.exe

-name
My Java IDE
-vm
c:\jre\bin\java.exe

Implementation details

This program performs the launching of the java VM used to start the Eclipse or RCP java application. As an implementation detail, this program serves two other purposes: display a splash window and write to a segment of shared memory.

The java application receives the following arguments.

	-launcher <launcher absolute name. e.g. d:\eclipse\eclipse.exe>
	-name <application name. e.g. Eclipse>

If the splash window is to be displayed, the java application will receive two extra arguments:

     -showsplash  <splash time out in seconds e.g. 600>

When the Java program starts, it should determine the location of the splash bitmap to be used. The Java program initiates the displaying of the splash window by executing the splash command as follows:

Process splashProcess = Runtime.getRuntime().exec( array );

Where array stores String arguments in the following order:

<launcher absolute name. e.g. d:\eclipse\eclipse.exe>
-name
<application name. e.g. Eclipse>
-showsplash
<splash time out in seconds e.g. 600>
<absolute path of the splash screen e.g. d:\eclipse\splash.bmp>

When the Java program initialization is complete, the splash window is brought down by destroying the splash process as follows:

     splashProcess.destroy();

Therefore, when the splash window is visible, there are actually three processes running:

the main launcher process
the Java VM process (Eclipse or RCP application)
the splash window process.

Similarly, the Java application will receive two other arguments:

    -exitdata <shared memory id>

The exitdata command can be used by the Java application to provide specific exit data to the main launcher process. The following causes another instance of the launcher to write to the segment of shared memory previously created by the main launcher.

 Process exitDataProcess = Runtime.getRuntime().exec( array );
 exitDataProcess.waitFor();

Where array stores String arguments in the following order:

<launcher absolute name. e.g. d:\eclipse\eclipse.exe>
-name
<application name. e.g. Eclipse>
-exitdata
<shared memory id e.g. c60_7b4>
<exit data that either contain a series of characters>

The exit data size must not exceed MAX_SHARED_LENGTH which is 16Kb. The exit data process will exit with an exit code different than 0 if that happens. The interpretation of the exit data is dependent on the exit value of the java application.

The main launcher recognizes the following exit codes from the Java application:

0 - Exit normally.
RESTART_LAST_EC = 23 - restart the java VM again with the same arguments as the previous one.
RESTART_NEW_EC = 24 - restart the java VM again with the arguments taken from the exit data. The exit data format is a list of arguments separated by '\n'. The Java application should build this list using the arguments passed to it on startup. See below.

Additionally, if the Java application exits with an exit code other than the ones above, the main launcher will display an error message with the contents of the exit data. If the exit data is empty, a generic error message is displayed. The generic error message shows the exit code and the arguments passed to the Java application.

The argument order for the new Java VM process is as follows:

<javaVM> <all VM args>
     -os <user or default OS value>
     -ws <user or default WS value>
     -arch <user or default ARCH value>
     -launcher <absolute launcher name>
     -name <application name>
     [-showsplash <splash time out>]
     [-exitdata <shared memory id>]
     <userArgs>
     -vm <javaVM>
     -vmargs <all VM args>

where:

<all VM args> = [<defaultVMargs> | <userVMargs>] -jar <startup jar full path> The startup jar must be an executable jar.