launcher.html - gerrit/www.eclipse.org/swt - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <meta http-equiv="Content-Language" content="en-us">
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <title>The Eclipse Program Launcher</title>
 </head>
 <body>
 <h1>The Eclipse Program Launcher</h1>

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

 <h2>Program options</h2>
 <p>The options that can be specified by the user to the launcher are:</p>
 <table border="1" cellspacing="0" width="800" cellpadding="5">
 	<tr><td><code>-vm &lt;javaVM&gt;</code></td><td>the Java VM to be used</tr>
 	<tr><td><code>-os &lt;opSys&gt;</code></td><td>the operating system being run on</tr>
 	<tr><td><code>-arch &lt;osArch&gt;</code></td><td>the hardware architecture of the OS: x86, sparc, hp9000</tr>
 	<tr><td><code>-ws &lt;gui&gt;</code></td><td>the window system to be used: win32, motif, gtk, ...</tr>
 	<tr><td><code>-nosplash</code></td><td>do not display the splash screen. The java application will
     not receive the -showsplash command.</tr>
 	<tr><td><code>-name &lt;name&gt;</code></td><td>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.</tr>
 	<tr><td><code>-startup</code></td><td>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 &lt;launcher folder&gt;/myfolder/myJar.jar</tr>
 	<tr><td><code>&lt;userArgs&gt;</code></td><td>arguments that are passed along to the Java application
     (i.e, -data &lt;path&gt;, -debug, -console, -consoleLog, etc) </tr>
 	<tr><td><code>-vmargs &lt;userVMargs&gt; ...</code></td><td>a list of arguments for the VM itself</tr>
 </table>
 <p>The <code>-vmargs</code> 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. </p>

 <p>Configuration file:</p>
 	<ul>
 		<li>The launcher gets arguments from the command line and/or from a configuration file.</li>
 		<li>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.</li>
 		<li>The format of the ini file matches that of the command line arguments - one
 		argument per line.</li>
 		<li>In general, the settings of the config file are expected to be overriden by the
 		command line.
 		<ul>
 			<li>launcher arguments (-os, -arch...) set in the config file are overriden by the command line</li>
 			<li>the -vmargs from the command line replaces in its entirety the -vmargs from the config file.</li>
 			<li>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"</li>
 		</ul></li>
 	<li>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
 </ul>

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

 <h2>Implementation details</h2>

 <p>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.

 <p>The java application receives the following arguments.
 <pre>
 	-launcher &lt;launcher absolute name. e.g. d:\eclipse\eclipse.exe&gt;
 	-name &lt;application name. e.g. Eclipse&gt;
  </pre>
 If the splash window is to be displayed, the java application
 will receive two extra arguments:
 <pre>
      -showsplash  &lt;splash time out in seconds e.g. 600&gt;
 </pre>

 <p>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:

 <pre>
 Process splashProcess = Runtime.getRuntime().exec( array );
 </pre>
 Where array stores String arguments in the following order:
 <ol>
 	<li>&lt;launcher absolute name. e.g. d:\eclipse\eclipse.exe&gt;
 	<li>-name
 	<li>&lt;application name. e.g. Eclipse&gt;
 	<li>-showsplash
 	<li>&lt;splash time out in seconds e.g. 600&gt;
 	<li>&lt;absolute path of the splash screen e.g. d:\eclipse\splash.bmp&gt;
 </ol>

 <p>When the Java program initialization is complete, the splash window
  is brought down by destroying the splash process as follows:
 <pre>
      splashProcess.destroy();
 </pre>

 <p>Therefore, when the splash window is visible, there are actually three
  processes running:
 <ol>
 	<li>the main launcher process
 	<li>the Java VM process (Eclipse or RCP application)
 	<li>the splash window process.
 </ol>

 <p>Similarly, the Java application will receive two other arguments:
 <pre>
     -exitdata &lt;shared memory id&gt;
 </pre>

 <p>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.

  <pre>
  Process exitDataProcess = Runtime.getRuntime().exec( array );
  exitDataProcess.waitFor();
  </pre>

  Where array stores String arguments in the following order:
  <ol>
 	<li>&lt;launcher absolute name. e.g. d:\eclipse\eclipse.exe&gt;
 	<li>-name
 	<li>&lt;application name. e.g. Eclipse&gt;
 	<li>-exitdata
 	<li>&lt;shared memory id e.g. c60_7b4&gt;
 	<li>&lt;exit data that either contain a series of characters&gt;
 </ol>

 <p>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.

 <p>The main launcher recognizes the following exit codes from the
  Java application:
 <ul>
     <li><code>0</code> - Exit normally.
     <li><code>RESTART_LAST_EC = 23</code> - restart the java VM again with the same arguments as the previous one.
     <li><code>RESTART_NEW_EC  = 24</code> - 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.
 </ul>

 <p>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.

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

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

  where:
  <ul>
    &lt;all VM args&gt; =
      [&lt;defaultVMargs&gt; | &lt;userVMargs&gt;]
      -jar
      &lt;startup jar full path&gt;
 </ul>
  The startup jar must be an executable jar.

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<meta http-equiv="Content-Language" content="en-us">
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>The Eclipse Program Launcher</title>
	</head>
	<body>
	<h1>The Eclipse Program Launcher</h1>

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

	<h2>Program options</h2>
	<p>The options that can be specified by the user to the launcher are:</p>
	<table border="1" cellspacing="0" width="800" cellpadding="5">
	<tr><td><code>-vm <javaVM></code></td><td>the Java VM to be used</tr>
	<tr><td><code>-os <opSys></code></td><td>the operating system being run on</tr>
	<tr><td><code>-arch <osArch></code></td><td>the hardware architecture of the OS: x86, sparc, hp9000</tr>
	<tr><td><code>-ws <gui></code></td><td>the window system to be used: win32, motif, gtk, ...</tr>
	<tr><td><code>-nosplash</code></td><td>do not display the splash screen. The java application will
	not receive the -showsplash command.</tr>
	<tr><td><code>-name <name></code></td><td>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.</tr>
	<tr><td><code>-startup</code></td><td>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</tr>
	<tr><td><code><userArgs></code></td><td>arguments that are passed along to the Java application
	(i.e, -data <path>, -debug, -console, -consoleLog, etc) </tr>
	<tr><td><code>-vmargs <userVMargs> ...</code></td><td>a list of arguments for the VM itself</tr>
	</table>
	<p>The <code>-vmargs</code> 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. </p>

	<p>Configuration file:</p>
	<ul>
	<li>The launcher gets arguments from the command line and/or from a configuration file.</li>
	<li>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.</li>
	<li>The format of the ini file matches that of the command line arguments - one
	argument per line.</li>
	<li>In general, the settings of the config file are expected to be overriden by the
	command line.
	<ul>
	<li>launcher arguments (-os, -arch...) set in the config file are overriden by the command line</li>
	<li>the -vmargs from the command line replaces in its entirety the -vmargs from the config file.</li>
	<li>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"</li>
	</ul></li>
	<li>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
	</ul>

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

	<h2>Implementation details</h2>

	<p>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.

	<p>The java application receives the following arguments.
	<pre>
	-launcher <launcher absolute name. e.g. d:\eclipse\eclipse.exe>
	-name <application name. e.g. Eclipse>
	</pre>
	If the splash window is to be displayed, the java application
	will receive two extra arguments:
	<pre>
	-showsplash <splash time out in seconds e.g. 600>
	</pre>

	<p>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:

	<pre>
	Process splashProcess = Runtime.getRuntime().exec( array );
	</pre>
	Where array stores String arguments in the following order:
	<ol>
	<li><launcher absolute name. e.g. d:\eclipse\eclipse.exe>
	<li>-name
	<li><application name. e.g. Eclipse>
	<li>-showsplash
	<li><splash time out in seconds e.g. 600>
	<li><absolute path of the splash screen e.g. d:\eclipse\splash.bmp>
	</ol>

	<p>When the Java program initialization is complete, the splash window
	is brought down by destroying the splash process as follows:
	<pre>
	splashProcess.destroy();
	</pre>

	<p>Therefore, when the splash window is visible, there are actually three
	processes running:
	<ol>
	<li>the main launcher process
	<li>the Java VM process (Eclipse or RCP application)
	<li>the splash window process.
	</ol>

	<p>Similarly, the Java application will receive two other arguments:
	<pre>
	-exitdata <shared memory id>
	</pre>

	<p>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.

	<pre>
	Process exitDataProcess = Runtime.getRuntime().exec( array );
	exitDataProcess.waitFor();
	</pre>

	Where array stores String arguments in the following order:
	<ol>
	<li><launcher absolute name. e.g. d:\eclipse\eclipse.exe>
	<li>-name
	<li><application name. e.g. Eclipse>
	<li>-exitdata
	<li><shared memory id e.g. c60_7b4>
	<li><exit data that either contain a series of characters>
	</ol>

	<p>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.

	<p>The main launcher recognizes the following exit codes from the
	Java application:
	<ul>
	<li><code>0</code> - Exit normally.
	<li><code>RESTART_LAST_EC = 23</code> - restart the java VM again with the same arguments as the previous one.
	<li><code>RESTART_NEW_EC = 24</code> - 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.
	</ul>

	<p>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.

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

	<pre>
	<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&gt
	[-showsplash <splash time out>]
	[-exitdata <shared memory id>]
	<userArgs>
	-vm <javaVM>
	-vmargs <all VM args>
	</pre>

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

	</body>
	</html>