| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <meta http-equiv="Content-Language" content="en-us"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <link REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Eclipse runtime options</title> |
| </head> |
| |
| <body> |
| |
| <h1>The Eclipse runtime options</h1> |
| <p>Version 3.1 - Last revised June 15, 2005</p> |
| <p>The Eclipse platform is highly configurable. Configuration input takes the |
| form of command line arguments and System property settings. In many cases |
| the command line arguments are simply short cuts for setting the related System |
| properties. In fact, there are many more System property settings than command |
| line arguments. </p> |
| <h2><a name="commandline"></a>Command line arguments </h2> |
| <p>Listed below are the command line arguments processed by various parts of |
| the Eclipse runtime. Many of these values can also be specified using System |
| properties either on the command line using -D VM arguments, by specifying |
| their values in a config.ini file or by using a <launcher>.ini file. |
| Using the two latter techniques it is possible to customize your Eclipse without |
| using command line arguments at all.</p> |
| <p>For each argument in the list, its corresponding System property key is given |
| (in {}). Also given is the Eclipse runtime layer in which the command line |
| argument is processed (in ()). This is useful for people replacing parts of |
| the runtime to suit special needs.</p> |
| <dl> |
| <dt>-application <id> (Runtime)</dt> |
| <dd>equivalent to setting <a href="#eclipseapplication">eclipse.application</a> |
| to <id></dd> |
| <dt>-arch <architecture> (OSGi) </dt> |
| <dd>equivalent to setting <a href="#osgiarch">osgi.arch</a> to <architecture></dd> |
| <dt>-clean (OSGi) </dt> |
| <dd>equivalent to setting <a href="#osgiclean">osgi.clean</a> to "true"</dd> |
| <dt>-configuration <location> (Main)</dt> |
| <dd>equivalent to setting <a href="#osgiconfigurationarea">osgi.configuration.area</a> |
| to <location></dd> |
| <dt>-console [port] (OSGi) </dt> |
| <dd>equivalent to setting <a href="#osgiconsole">osgi.console</a> to [port] |
| or the empty string if the default port is to be used (i.e., when the port |
| is not specified)</dd> |
| <dt>-consoleLog (Runtime)</dt> |
| <dd>equivalent to setting <a href="#eclipseconsolelog">eclipse.consoleLog</a> to |
| "true"</dd> |
| <dt>-data <location> (OSGi)<br> |
| </dt> |
| <dd>equivalent to setting <a href="#osgiinstancearea">osgi.instance.area</a> |
| to <location></dd> |
| <dt>-debug [options file] (OSGi)</dt> |
| <dd> equivalent to setting <a href="#osgidebug">osgi.debug</a> to [options |
| file] or the empty string to simply enable debug (i.e., if the options file |
| location is not specified)</dd> |
| <dt>-dev [entries] (OSGi)</dt> |
| <dd>equivalent to setting <a href="#osgidev">osgi.dev</a> to [entries] or |
| the empty string to simply enable dev mode (i.e., if entries are not specified)</dd> |
| <dt>-endSplash <command> (Main)</dt> |
| <dd>specifies the command to use to take down the splash screen. Typically |
| supplied by the Eclipse executable.</dd> |
| <dt>-feature <feature id> (Runtime)</dt> |
| <dd>equivalent to setting <a href="#eclipseproduct">eclipse.product</a> |
| to <feature id></dd> |
| <dt>-framework <location> (Main) </dt> |
| <dd>equivalent to setting <a href="#o.pngramework">osgi.framework</a> to |
| <location></dd> |
| <dt>-initialize (Main)</dt> |
| <dd>initializes the configuration being run. All runtime related data structures |
| and caches are refreshed. Any user/plug-in defined configuration data is |
| not purged. No application is run, any product specifications are ignored |
| and no UI is presented (e.g., the splash screen is not drawn)</dd> |
| <dt>-install <location> (Main)</dt> |
| <dd>equivalent to setting <a href="#osgiinstallarea">osgi.install.area</a> to |
| <location></dd> |
| <dt>-keyring <location> (Runtime)</dt> |
| <dd>the location of the authorization database on disk. This argument has to |
| be used together with the -password argument. </dd> |
| <dt>-name <string> <em>NEW</em></dt> |
| <dd>The name to be displayed in task bar item when the application starts up. When not set, the name is the name of the executable.</dd> |
| <dt>-nl <locale> (OSGi)</dt> |
| <dd>equivalent to setting <a href="#osginl">osgi.nl</a> to <locale></dd> |
| <dt>-noExit (OSGi)</dt> |
| <dd>equivalent to setting <a href="#osginoshutdown">osgi.noShutdown</a> to "true"</dd> |
| <dt>-noLazyRegistryCacheLoading (Runtime) </dt> |
| <dd>equivalent to setting <a href="#eclipsenolazyregistrycacheloading">eclipse.noLazyRegistryCacheLoading</a> |
| to "true"</dd> |
| <dt>-noRegistryCache |
| (Runtime) </dt> |
| <dd>equivalent to setting <a href="#eclipsenoregistrycache">eclipse.noRegistryCache</a> |
| to "true"</dd> |
| <dt>-noSplash (Executable, Main)</dt> |
| <dd>controls whether or not the splash screen is shown</dd> |
| <dt>-os <operating system> (OSGi) </dt> |
| <dd>equivalent to setting <a href="#osgios">osgi.os</a> to <operating system></dd> |
| <dt>-password <password> (Runtime) </dt> |
| <dd>the password for the authorization database </dd> |
| <dt> -pluginCustomization <location> (Runtime) </dt> |
| <dd>equivalent to setting <a href="#eclipseplugincustomization">eclipse.pluginCustomization</a> to |
| <location></dd> |
| <dt> -product <id> (OSGi) </dt> |
| <dd>equivalent to setting <a href="#eclipseproduct">eclipse.product</a> to |
| <id></dd> |
| <dt>-showSplash <command> (Main)</dt> |
| <dd>specifies the command to use to show the splash screen. Typically supplied |
| by the Eclipse executable.</dd> |
| <dt>-startup <location> (Executable) <em>NEW</em></dt> |
| <dd>The location of jar used to startup eclipse. The jar referred to must have the Main-Class attribute set. |
| If this parameter is not set, the startup.jar located in the same folder than the executable is used.</dd> |
| <dt>-user <location> (OSGi) </dt> |
| <dd>equivalent to setting <a href="#osgiuserarea">osgi.user.area</a> to <location></dd> |
| <dt>-vm <path to java executable> (Executable, Main) </dt> |
| <dd>when passed to the Eclipse executable, this option is used to locate the |
| Java VM to use to run Eclipse. It must be the full file system path to an |
| appropriate Java executable. If not specified, the Eclipse executable uses |
| a search |
| algorithm to locate a suitable VM. In any event, the executable then passes |
| the path to the actual VM used to Java Main using the -vm argument. Java |
| Main then stores this value in <a href="#eclipsevm">eclipse.vm</a>.</dd> |
| <dt>-vmargs [vmargs*] (Executable, |
| Main) </dt> |
| <dd>when passed to the Eclipse, this option is used to customize the operation |
| of the Java VM to use to run Eclipse. If |
| specified, this option must come at the end of the command line. Even if |
| not specified on the executable command line, the executable will automatically |
| add the relevant arguments (including the class being launched) to the command |
| line passed into Java using the -vmargs argument. |
| Java Main then stores this value in <a href="#eclipsevmargs">eclipse.vmargs</a>.</dd> |
| <dt>-ws <window system> (OSGi) </dt> |
| <dd>equivalent to setting <a href="#osgiws">osgi.ws</a> to <window system></dd> |
| </dl> |
| <h3>Obsolete command line arguments </h3> |
| <p>The following command line arguments are no longer relevant or have been superceded |
| and are consumed by the runtime and not passed on to the application being |
| run to maintain backward compatibility. .</p> |
| <dl> |
| <dt> -boot</dt> |
| <dd>see -configuration</dd> |
| <dt>-classLoaderProperties</dt> |
| <dd>no longer relevant</dd> |
| <dt>-firstUse</dt> |
| <dd>no longer relevant</dd> |
| <dt>-newUpdates</dt> |
| <dd>no longer relevant</dd> |
| <dt>-noPackagePrefixes</dt> |
| <dd>no longer relevant</dd> |
| <dt>-noUpdate</dt> |
| <dd>no longer relevant</dd> |
| <dt>-plugins</dt> |
| <dd>no longer relevant</dd> |
| <dt>-update</dt> |
| <dd>no longer relevant</dd> |
| </dl> |
| <h3>Others</h3> |
| <p>The following command line arguments are defined by various Eclipse plug-ins |
| and are only supported if the defining plug-in is installed, resolved and activated.</p> |
| <dl> |
| <dt>-noVersionCheck (workbench)</dt> |
| <dd><description></dd> |
| <dt>-perspective (workbench)</dt> |
| <dd><description></dd> |
| <dt>-refresh (org.eclipse.core.resources)</dt> |
| <dd><description></dd> |
| <dt>-showLocation (org.eclipse.ui.ide.workbench)</dt> |
| <dd><description></dd> |
| <dt>-allowDeadlock</dt> |
| <dd><description></dd> |
| </dl> |
| <h2>System properties</h2> |
| <p>The following System properties are used by the Eclipse runtime. Note that |
| those starting with "osgi" are specific to the OSGi framework implementation |
| while those starting with "eclipse" are particular to the Eclipse |
| runtime layered on top of the OSGi framework. </p> |
| <p>Many of these properties have command line equivalents (see the <a href="#commandline">command |
| line arguments</a> section and the value in braces {}). Users are free to |
| use either command line or property settings to specify a value. Properties |
| can |
| be set |
| in |
| the |
| following |
| ways:</p> |
| <ul> |
| <li>use -DpropName=propValue as a VM argument to the Java VM</li> |
| <li>set the desired property in the config.ini file in the appropriate configuration |
| area</li> |
| </ul> |
| <dl> |
| <dt><a name="eclipseapplication" id="eclipseapplication"></a>eclipse.application {-application}</dt> |
| <dd>the identifier of the application to run. The value given here overrides |
| any application defined by the product (see <a href="#eclipseproduct">eclipse.product</a>) being run</dd> |
| <dt><a name="eclipsecommands" id="eclipsecommands"></a>eclipse.commands</dt> |
| <dd>a new-line separated list of all command-line arguments passed in when launching |
| Eclipse </dd> |
| <dt><a name="eclipseconsolelog" id="eclipseconsolelog"></a>eclipse.consoleLog</dt> |
| <dd>if "true", any log output is also sent to Java's System.out (typically |
| back to the command shell if any). Handy when combined with -debug </dd> |
| <dt><a name="eclipsedebugstartuptime" id="eclipsedebugstartuptime"></a>eclipse.debug.startupTime</dt> |
| <dd>the time in milliseconds when the Java VM for this session was started</dd> |
| <dt><a name="eclipseexitcode" id="eclipseexitcode"></a>eclipse.exitcode</dt> |
| <dd><description></dd> |
| <dt><a name="eclipseexitdata" id="eclipseexitdata"></a>eclipse.exitdata</dt> |
| <dd><description></dd> |
| <dt><a name="eclipselogbackupmax" id="eclipselogbackupmax"></a>eclipse.log.backup.max</dt> |
| <dd>the max number of backup log files to allow. The oldest backup log file will be deleted |
| after the max number of backup log files is reached as a result of rotating the log file. |
| The default value is "10". A negative or zero value will cause the default |
| value to be used.</dd> |
| <dt><a name="eclipselogsizemax" id="eclipselogsizemax"></a>eclipse.log.size.max</dt> |
| <dd>the max size in Kb that the log file is allowed to grow. The log file is rotated when |
| the file size exceeds the max size. The default value is "1000". |
| A negative value will cause the default value to be used. A zero value indicates |
| no max log size.</dd> |
| <dt><a name="eclipsenoextensionmunging" id="eclipsenoextensionmunging"></a>eclipse.noExtensionMunging</dt> |
| <dd>if "true", legacy registry extension are left as-is. By default such extensions |
| are updated to use the new extension point ids found in Eclipse 3.0.</dd> |
| <dt><a name="eclipsenolazyregistrycacheloading" id="eclipsenolazyregistrycacheloading"></a>eclipse.noLazyRegistryCacheLoading {-noLazyRegistryCacheLoading}</dt> |
| <dd>if "true", the platform's plug-in registry cache loading optimization is |
| deactivated. By default, configuration elements are loaded from the registry |
| cache (when available) |
| only on demand, reducing memory footprint. This option forces the registry |
| cache to be fully loaded at startup. </dd> |
| <dt><a name="eclipsenoregistrycache" id="eclipsenoregistrycache"></a>eclipse.noRegistryCache {-noRegistryCache}</dt> |
| <dd>if "true", the internal extension registry cache is neither read or written</dd> |
| <dt><a name="eclipseplugincustomization" id="eclipseplugincustomization"></a>eclipse.pluginCustomization {-pluginCustomization}</dt> |
| <dd>the file system location of a properties file containing default settings |
| for plug-in preferences. These default settings override default settings |
| specified in the primary feature. Relative paths are interpreted relative |
| to the current working directory for eclipse itself.</dd> |
| <dt><a name="eclipseproduct" id="eclipseproduct"></a>eclipse.product {-product}</dt> |
| <dd>the identifier of the product being run. This controls various branding |
| information and what application is used.</dd> |
| <dt><a name="eclipsestarttime" id="eclipsestarttime"></a>eclipse.startTime</dt> |
| <dd>This property is set at the time eclipse is started. The value of this property a string |
| representation of the value returned by System.currentTimeMillis(). This value is not |
| intended to be set by users.</dd> |
| <dt><a name="eclipsevm" id="eclipsevm"></a>eclipse.vm {-vm}</dt> |
| <dd>the path to the Java executable used to run Eclipse. This information is |
| used to construct relaunch command lines.</dd> |
| <dt><a name="eclipsevmargs" id="eclipsevmargs"></a>eclipse.vmargs {-vmargs}</dt> |
| <dd>lists the VM arguments used to run Eclipse. This |
| information is used to construct relaunch command |
| lines.</dd> |
| <dt><a name="osgiadaptor"></a>osgi.adaptor</dt> |
| <dd>the class name of the OSGi framework adaptor to use.</dd> |
| <dt><a name="osgiarch"></a>osgi.arch {-arch}</dt> |
| <dd>see -arch</dd> |
| <dt><a name="osgibaseconfigurationarea"></a>osgi.baseConfiguration.area</dt> |
| <dd>specifies a base configuration that is used when |
| <a href="#osgiconfigurationarea">osgi.configuration.area</a> is not specified.</dd> |
| <dt><a name="osgibundles"></a>osgi.bundles</dt> |
| <dd>The comma-separated list of bundles which are automatically installed |
| and optionally started |
| once the system is up and running. Each entry is of the form:<br> |
| <pre> <URL | simple bundle location>[@ [<start-level>] [":start"]]</pre> |
| If the start-level (>0 integer) is omitted then the framework will use the |
| default start level for the bundle. If the "start" tag is added |
| then the bundle will be marked as started after being installed. |
| Simple bundle locations are interepreted as relative to the framework's |
| parent directory. |
| The start-level indicates the OSGi start level at which the bundle should |
| run. If this value is not set, the system computes an appropriate default. </dd> |
| <dt><a name="osgiclean"></a>osgi.clean</dt> |
| <dd>if set to "true", any cached data used by the OSGi framework and eclipse runtime |
| will be wiped clean. This will clean the caches used to store bundle |
| dependency resolution and eclipse extension registry data. Using this option |
| will force eclipse to reinitialize these caches.</dd> |
| <dt><a name="osgiconfigurationcascaded"></a>osgi.configuration.cascaded</dt> |
| <dd>if set to "true", this configuration is cascaded to a parent |
| configuration. The parent configuration is specified by the <a href="#osgisharedconfigurationarea">osgi.sharedConfiguration.area</a>. |
| See the section on <a href="#locations">locations</a> for more details.</dd> |
| <dt><a name="osgiconfigurationarea"></a>osgi.configuration.area {-configuration}</dt> |
| <dd>the configuration location for this run of the platform. The configuration |
| determines what plug-ins will run as well as various other system settings. |
| See the section on <a href="#locations">locations</a> for |
| more details.</dd> |
| <dt><a name="osgiconfigurationareadefault" id="osgiconfigurationareadefault"></a>osgi.configuration.area.default</dt> |
| <dd>the default configuration location for this run of the platform. The configuration |
| determines what plug-ins will run as well as various other system settings. |
| This value (i.e., the default setting) is only used if no value for the osgi.configuration.area |
| is set. See the section on <a href="#locations">locations</a> for |
| more details.</dd> |
| <dt><a name="osgiconsole"></a>osgi.console {-console} </dt> |
| <dd>if set to a non-null value, the OSGi console (if installed) is enabled. |
| If the value is a suitable integer, it is interpreted as the port on which |
| the console listens and directs its output |
| to the |
| given port. |
| Handy for investigating |
| the state of the system. </dd> |
| <dt><a name="osgiconsoleclass"></a>osgi.console.class</dt> |
| <dd>the class name of the console to run if requested</dd> |
| <dt><a name="osgidebug"></a>osgi.debug {-debug}</dt> |
| <dd>if set to a non-null value, the platform is put in debug mode. If the value |
| is a string it is interpreted as the location of the |
| .options file. This file indicates what debug |
| points are |
| available |
| for a plug-in and whether or not they are enabled. If a location is not specified, |
| the platform searches for the .options file under the install directory.</dd> |
| <dt><a name="osgidev"></a>osgi.dev {-dev}</dt> |
| <dd>if set to the empty string, dev mode is simply turned on. This property |
| may also be set to a comma-separated class path entries |
| which are added to |
| the class |
| path of each |
| plug-in or a URL to a Java properties file containing custom classpath additions |
| for a set of plug-ins. For each plug-in requiring a customized dev time classpath |
| the file will contain an entry of the form<br> |
| <pre> <plug-in id>=<comma separated list of classpath entries to add></pre> |
| where plug-in id "*" matches any plug-in not otherwise mentioned.</dd> |
| <dt><a name="o.pngramework"></a>osgi.framework</dt> |
| <dd>the URL location of the OSGi framework. Useful if the Eclipse install |
| is disjoint. See the section on <a href="#locations">locations</a> for more details. </dd> |
| <dt><a name="o.pngrameworkclasspath"></a>osgi.frameworkClassPath</dt> |
| <dd>a comma separated list of classpath entries for the OSGi framework implementation. |
| Relative locations are interpreted as relateve to the framework location |
| (see <a href="#o.pngramework">osgi.framework</a>)</dd> |
| <dt><a name="osgiframeworkextensions"></a>osgi.framework.extensions</dt> |
| <dd>a comma-separated list of framework extensions. Each entry is of the form:<br> |
| <pre> <URL | simple bundle location></pre> |
| If a simple bundle location is specified (not a URL) then a search is done in parent directory of the |
| org.eclipse.osgi bundle. Framework extensions may be used to run Eclipse with a different |
| framework adaptor. The framework extension may contain an eclipse.properties file to set |
| system properties. For example, a framework extension that provides a framework adaptor |
| implementation can specify what the adaptor class is by setting the |
| <a href="#osgiadaptor">osgi.adaptor</a> property.</dd> |
| <dt><a name="osgiframeworkshape"></a>osgi.framework.shape</dt> |
| <dd>set to the shape of the Eclipse OSGi Framework implementation. This property is set when |
| the Eclipse platform is started and is not intended by be set by the user. The value |
| "jar" indicates that the Eclipse OSGi Framework is contained in a single jar. |
| The value "folder" indicates that the Eclipse OSGi Framework is contained in a |
| directory.</dd> |
| <dt><a name="osgijavaprofile"></a>osgi.java.profile</dt> |
| <dd>a URL to the JRE profile file to use. A JRE profile contains values for the properties |
| org.osgi.framework.system.packages and org.osgi.framework.bootdelegation. If |
| the osgi.java.profile is not set then a profile is selected based on the |
| java.specification.version value of the running JRE.</dd> |
| <dt><a name="osgijavaprofilebootdelegation"></a>osgi.java.profile.bootdelegation</dt> |
| <dd> |
| a java profile <a href="#osgijavaprofile">osgi.java.profile</a> may contain a |
| "org.osgi.framework.bootdelegation" property. This value may be used to set the system |
| property "org.osgi.framework.bootdelegation". The osgi.java.profile.bootdelegation |
| indicates the policy for bootdelegation to be used. The following values are valid |
| (default is ignore): |
| <ul type=disc> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>ignore</b> - indicates that |
| the "org.osgi.framework.bootdelegation" value in the java profile should be ingored. |
| The system property "org.osgi.framework.bootdelegation" will be used to |
| determine which packages should be delegated to boot. |
| </li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>override</b> - |
| indicates that the "org.osgi.framework.bootdelegation" in the java profile should |
| override the system property "org.osgi.framework.bootdelegation". |
| </li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>none</b> - |
| indicates that the "org.osgi.framework.bootdelegation" in the java profile AND |
| the system properties should be ignored. This is the most strict option. |
| Running with this option causes the framework to use the OSGi R4 strict boot |
| delegation model. |
| </li> |
| </ul> |
| </dd> |
| <dt><a name="osgiinstallarea" id="osgiinstallarea"></a>osgi.install.area {-install}</dt> |
| <dd>the install location of the platform. This setting indicates the location |
| of the basic Eclipse plug-ins and is useful if the Eclipse install is disjoint. |
| See the section on <a href="#locations">locations</a> for more details. </dd> |
| <dt><a name="osgiinstancearea"></a>osgi.instance.area {-data}</dt> |
| <dd>the instance data location for this session. Plug-ins use this location |
| to store their data. For example, the Resources plug-in uses this as the |
| default location for projects (aka the workspace). See the section on <a href="#locations">locations</a> for |
| more details.</dd> |
| <dt><a name="osgiinstanceareadefault" id="osgiinstanceareadefault"></a>osgi.instance.area.default</dt> |
| <dd>the default instance data location for this session. Plug-ins use this |
| location to store their data. For example, the Resources plug-in uses this |
| as the |
| default location for projects (aka the workspace). This value (i.e., the |
| default setting) is only used if no value for the osgi.instance.area |
| is set. See the section on <a href="#locations">locations</a> for |
| more details.</dd> |
| <dt><a name="osgilocking"></a>osgi.locking</dt> |
| <dd>the locking type to use for this run of the platform. The valid locking types |
| are "java.io", "java.nio", and "none". The default value is |
| "java.nio" unless the JRE does not support "java.nio" then "java.io" |
| is the default.</dd> |
| <dt><a name="osgimanifestcache"></a>osgi.manifest.cache</dt> |
| <dd>the location where generated manifests are discovered and generated. The |
| default is in the configuration area but the manifest cache can be stored |
| separately.</dd> |
| <dt><a name="osginl"></a>osgi.nl {-nl}</dt> |
| <dd>the name of the locale on which Eclipse platform will run. NL values should |
| follow the standard Java locale naming conventions.</dd> |
| <dt><a name="osginoshutdown"></a>osgi.noShutdown {-noExit}</dt> |
| <dd>if "true", the VM will not exit after the eclipse application has ended. This |
| is useful for examining the OSGi framework after the eclipse application has ended.</dd> |
| <dt><a name="osgios"></a>osgi.os {-os}</dt> |
| <dd>the operating system value. The value should be one of the Eclipse processor |
| architecture names known to Eclipse (e.g., x86, sparc, ...).</dd> |
| <dt><a name="osgiparentclassloader"></a>osgi.parentClassloader</dt> |
| <dd>the classloader type to use as the parent classloader for all bundles installed |
| in the Framework. The valid types are the following: |
| <ul type=disc> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>app</b> - the application classloader.</li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>boot</b> - the boot classloader.</li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>ext</b> - the extension classloader.</li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'><b>fwk</b> - the framework classloader.</li> |
| </ul> |
| </dd> |
| <dt><a name="osgirequiredjavaversion"></a>osgi.requiredJavaVersion</dt> |
| <dd>The minimum java version that is required to launch Eclipse. The default value is |
| "1.4.1".</dd> |
| <dt><a name="osgiresolvermode"></a>osgi.resolverMode</dt> |
| <dd>the mode used to resolve bundles installed in the Framework. A value of |
| "strict" puts the resolver in strict mode. The default resolver |
| mode is not strict. When the resolver is in strict mode the Framework will |
| enforce access restriction rules when loading classes and resources from |
| exported packages which specify the x-internal or x-friends directives.</dd> |
| <dt><a name="osgisharedconfigurationarea"></a>osgi.sharedConfiguration.area</dt> |
| <dd>the shared configuration location for this run of the platform. If the |
| <a href="#osgiconfigurationcascaded">osgi.configuration.cascaded</a> property is set |
| to "true" then shared configuration area is used as the parent configuration.</dd> |
| <dt><a name="osgisplashlocation"></a>osgi.splashLocation</dt> |
| <dd>the absolute URL location of the splash screen (.bmp file) to to show while |
| starting Eclipse. This property overrides any value set in <a href="#osgisplashpath">osgi.splashPath</a>.</dd> |
| <dt><a name="osgisplashpath"></a>osgi.splashPath</dt> |
| <dd>a comma separated list of URLs to search for a file called splash.bmp. |
| This property is overriden by any value set in <a href="#osgisplashlocation">osgi.splashLocation</a>.</dd> |
| <dt><a name="osgisyspath"></a>osgi.syspath</dt> |
| <dd>set to the path where the eclipse OSGi Framework (org.eclipse.osgi) implementation |
| is located. For example, "<eclipse install path>/eclipse/plugins". |
| This property is set when the Eclipse platform is started and is not intended by be |
| set by the user.</dd> |
| <dt><a name="osgiuserarea"></a>osgi.user.area {-user}</dt> |
| <dd>the location of the user area. The user area contains data (e.g., preferences) |
| specific to the OS user and independent of any Eclipse install, configuration |
| or instance. See the section on <a href="#locations">locations</a> for more |
| details.</dd> |
| <dt><a name="osgiuserareadefault" id="osgiuserareadefault"></a>osgi.user.area.default</dt> |
| <dd>the default location of the user area. The user area contains data (e.g., |
| preferences) specific to the OS user and independent of any Eclipse install, |
| configuration |
| or instance. This value (i.e., the default setting) is only used if no value |
| for the osgi.user.area is set. See the section on <a href="#locations">locations</a> for |
| more details.</dd> |
| <dt><a name="osgiws"></a>osgi.ws {-ws}</dt> |
| <dd>the window system value. The value should be one of the Eclipse window |
| system names known to Eclipse (e.g., win32, motif, ...).</dd> |
| </dl> |
| <h2><a name="locations"></a>Locations |
| </h2> |
| <p>The Eclipse runtime defines a number of <i>locations</i> which give plug-in |
| developers context for reading/storing data and Eclipse users a control over |
| the scope of data sharing and visibility. Eclipse defines the following notions |
| of location:</p> |
| <dl> |
| <dt>User (-user) {<a href="#osgiuserarea">osgi.user.area</a>} [@none, @noDefault, @user.home, @user.dir, |
| filepath, url]</dt> |
| <dd>User locations are specific to, go figure, users. Typically the user |
| location is based on the value of the Java <code>user.home</code> system |
| property but this can be overridden. Information such as user scoped preferences |
| and login information may be found in the user location.</dd> |
| <dt>Install (-install) {osgi.install.area} [@user.home, @user.dir, filepath, |
| url]</dt> |
| <dd>An install location is where Eclipse itself is installed. In practice |
| this location is the directory (typically "eclipse") which is |
| the parent of the startup.jar or eclipse.exe being run. This location should |
| be considered read-only to normal users as an install may be shared by |
| many users. It is possible to set the install location and decouple startup.jar |
| from the rest of Eclipse.</dd> |
| <dt>Configuration (-configuration) {osgi.configuration.area} [@none, @noDefault, |
| @user.home, @user.dir, filepath, url]</dt> |
| <dd>Configuration locations contain files which identify and manage the (sub)set |
| of an install to run. As such, there may be many configurations per install. |
| Installs may come with a default configuration area but typical startup |
| scenarios involve the runtime attempting to find a more writable configuration |
| location. </dd> |
| <dt>Instance (-data) {osgi.instance.area} [@none, @noDefault, @user.home, |
| @user.dir, filepath, url]</dt> |
| <dd>Instance locations contain user-defined data artifacts. For example, |
| the Resources plug-in uses the instance area as the workspace location |
| and thus the default home for projects. Other plugins are free to write |
| whatever files they like in this location.</dd> |
| </dl> |
| <p>While users can set any of these locations, Eclipse will compute reasonable |
| defaults if values are not given. The most common usecase for setting location |
| is the instance area or, in the IDE context, the workspace. To run the default |
| Eclipse configuration on a specific data set you can specify:</p> |
| <pre> eclipse -data c:\mydata</pre> |
| <h3>More detail</h3> |
| <p>Locations are URLs. For simplicity, file paths are also accepted and automatically |
| converted to file: URLs. For better control and convenience, there are also |
| a number of predefined symbolic locations which can be used. Note that not |
| all combinations of location type and symbolic value are valid. A table below |
| details which combinations are possible. Since the default case is for all |
| locations to be set, valid and writable, some plug-ins may fail in other setups |
| even if they are listed as possible. For example, it is unreasonable to expect |
| a plugin focused on user data (e.g., the Eclipse Resources plug-in) to do much |
| if the instance area is not defined. It is up to plug-in developers to choose |
| the setups they support and design their function accordingly.</p> |
| <dl> |
| <dt>@none</dt> |
| <dd>Indicates that the corresponding location should never be set either |
| explicitly or to its default value. For example, an RCP style application |
| which has no user data may use osgi.instance.area=@none to prevent |
| extraneous files being written to disk. @none must not be followed by any |
| additional path segments.</dd> |
| <dt>@noDefault</dt> |
| <dd>Forces a location to be undefined or explicitly defined (i.e., Eclipse |
| will not automatically compute a default value). This is useful where you |
| want to allow for data in the corresponding location but the Eclipse default |
| value is not appropriate. @noDefault must not be followed by any |
| additional path segments.</dd> |
| <dt>@user.home</dt> |
| <dd>Directs Eclipse to compute a location value relative to the user's home |
| directory. @user.home can be followed |
| by additional path segments. In all cases, the string "@user.home" is |
| simply replaced with the value of the Java "user.home" System |
| property. For example, setting<br> |
| osgi.instance.area=@user.home/myWorkspace<br> |
| results in a value of |
| <br> |
| file:/users/bob/myWorkspace</dd> |
| <dt>@user.dir</dt> |
| <dd>Directs Eclipse to compute a location value relative to the current working |
| directory. @user.dir can be followed |
| by additional path segments. In all cases, the string "@user.dir" is |
| simply replaced with the value of the Java "user.dir" System |
| property. For example, setting<br> |
| osgi.instance.area=@user.dir/myWorkspace<br> |
| results in a value of <br> |
| file:/usr/share/eclipse/myWorkspace</dd> |
| </dl> |
| <table width="100%" border="0" bgcolor="#FFFFFF"> |
| <tr bgcolor="#CCCCCC"> |
| <td width="10%">location/value</td> |
| <td width="17%"><div align="center">supports default</div></td> |
| <td width="17%"><div align="center">file/URL</div> |
| </td> |
| <td width="17%"><div align="center">@none</div> |
| </td> |
| <td width="17%"><div align="center">@noDefault</div> |
| </td> |
| <td width="17%"><div align="center">@user.home</div> |
| </td> |
| <td width="17%"><div align="center">@user.dir</div> |
| </td> |
| </tr> |
| <tr> |
| <td bgcolor="#CCCCCC"><div align="center">instance</div> |
| </td> |
| <td><div align="center">yes</div></td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes (default)</div> |
| </td> |
| </tr> |
| <tr> |
| <td bgcolor="#CCCCCC"><div align="center">configuration</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes*</div> |
| </td> |
| <td><div align="center">yes*</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| </tr> |
| <tr> |
| <td bgcolor="#CCCCCC"><div align="center">install</div> |
| </td> |
| <td><div align="center">no</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">no</div> |
| </td> |
| <td><div align="center">no</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| </tr> |
| <tr> |
| <td bgcolor="#CCCCCC"><div align="center">user</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| <td><div align="center">yes</div> |
| </td> |
| </tr> |
| </table> |
| <p>* indicates that this setup is technically possible but pragmatically quite |
| difficult to manage. In particular, without a configuration location the Eclipse |
| runtime may only get as far as starting the OSGi framework.</p> |
| |
| <h3>Read-only Locations</h3> |
| |
| <p> |
| A location may be specified as a read-only location by appending ".readOnly" |
| to the location property and setting it to the value "true". The following properties |
| can be used to specify their corresponding locations as read-only:</p> |
| <ul type=disc> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'> |
| osgi.configuration.area.readOnly <a href="#osgiconfigurationarea">osgi.configuration.area</a> |
| </li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'> |
| osgi.sharedConfiguration.area.readOnly <a href="#osgisharedconfigurationarea">osgi.sharedConfiguration.area</a> |
| </li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'> |
| osgi.instance.area.readOnly <a href="#osgiinstancearea">osgi.instance.area</a> |
| </li> |
| <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; |
| mso-list:l2 level1 lfo3;tab-stops:list .5in'> |
| osgi.user.area.readOnly <a href="#osgiuserarea">osgi.user.area</a> |
| </li> |
| </ul> |
| |
| <h2><a name="launcher"></a>Launcher ini file</h2> |
| <p> |
| The eclipse.exe and more generally executables for RCP applications now read their parameters from an associated |
| ini file. This file offers a platform independent way to pass in arguments that previously had to be specified directly on |
| the command line such as vm or vm arguments. Although all parameters can be specified in this file, it recommend for maintainability |
| and consistency across various installations to only specifiy the vm location and the vm arguments in this ini file and use the config.ini |
| file for others.</p> |
| |
| <h3>File format</h3> |
| <p>This file must be named after the executable name (for example, eclipse.exe will read eclipse.ini, whereas launcher.exe will read launcher.ini) and every parameter |
| must be specified on a new line in the file. Here is an example of such a file specifying the vm location and some parameters:</p> |
| <pre>-vm |
| c:/myVm/java.exe |
| -vmargs |
| -Dms40M |
| </pre> |
| </body> |
| </html> |
