The Eclipse runtime options
Last modified 14:45 Wednesday August 4, 2004
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.
Command line arguments
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 or by specifying
there values in a config.ini file.
Using this latter technique it is possible to customize your Eclipse without
using command line arguments at all.
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.
- -application <id> (Runtime)
- equivalent to setting eclipse.application
to <id>
- -arch <architecture> (OSGi)
- equivalent to setting osgi.arch to <architecture>
- -clean (OSGi) NEW
- equivalent to setting osgi.clean to "true"
- -configuration <location> (Main)
- equivalent to setting osgi.configuration.area
to <location>
- -console [port] (OSGi) NEW
- equivalent to setting osgi.console to [port]
or the empty string if the default port is to be used (i.e., when the port
is not specified)
- -consoleLog (Runtime)
- equivalent to setting eclispe.consoleLog to
"true"
- -data <location> (OSGi)
- equivalent to setting osgi.instance.area
to <location>
- -debug [options file] (OSGi)
- equivalent to setting osgi.debug to [options
file] or the empty string to simply enable debug (i.e., if the options file
location is not specified)
- -dev [entries] (OSGi)
- equivalent to setting osgi.dev to [entries] or
the empty string to simply enable dev mode (i.e., if entries are not specified)
- -endSplash <command> (Main)
- specifies the command to use to take down the splash screen. Typically
supplied by the Eclipse executable.
- -feature <feature id> (Runtime)
- equivalent to setting eclipse.product
to <feature id>
- -framework <location> (Main) NEW
- equivalent to setting osgi.framework to
<location>
- -initialize (Main)
- 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)
- -install <location> (Main)
- equivalent to setting osgi.install.area to
<location>
- -keyring <location> (Runtime)
- the location of the authorization database on disk. This argument has to
be used together with the -password argument.
- -nl <locale> (OSGi)
- equivalent to setting osgi.nl to <locale>
- -noLazyRegistryCacheLoading (Runtime)
- equivalent to setting eclipse.noLazyRegistryCacheLoading
to "true"
- -noRegistryCache
(Runtime)
- equivalent to setting eclipse.noRegistryCache
to "true"
- -noSplash (Executable, Main)
- controls whether or not the splash screen is shown
- -os <operating system> (OSGi)
- equivalent to setting osgi.os to <operating system>
- -password <password> (Runtime)
- the password for the authorization database
-
- -pluginCustomization <location> (Runtime)
- equivalent to setting eclipse.pluginCustomization to
<location>
- -product <id> (OSGi) NEW
- equivalent to setting eclipse.product to
<id>
- -showSplash <command> (Main)
- specifies the command to use to show the splash screen. Typically supplied
by the Eclipse executable.
- -user <location> (OSGi) NEW
- equivalent to setting osgi.user.area to <location>
- -vm <path to java executable> (Executable, Main) NEW
- 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 filesystem 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 eclipse.vm.
- -vmargs [vmargs*] (Executable,
Main) NEW
- 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 eclipse.vmargs.
- -ws <window system> (OSGi)
- equivalent to setting osgi.ws to <window system>
Obsolete command line arguments
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. .
- -boot
- see -configuration
- -classLoaderProperties
- no longer relevant
- -firstUse
- no longer relevant
- -newUpdates
- no longer relevant
- -noPackagePrefixes
- no longer relevant
- -noUpdate
- no longer relevant
- -plugins
- no longer relevant
- -update
- no longer relevant
Others
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.
- -noVersionCheck (workbench)
- <description>
- -perspective (workbench)
- <description>
- -refresh (org.eclipse.core.resources)
- <description>
- -showLocation (org.eclipse.ui.ide.workbench)
- <description>
- -allowDeadlock
- <description>
System properties
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.
Many of these properties have command line equivalents (see the command
line arguments 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:
- use -DpropName=propValue as a VM argument to the Java VM
- set the desired property in the config.ini file in the appropriate configuration
area
- eclipse.application {-application}
- the identifier of the application to run. The value given here overrides
any application defined by the product (see eclipse.product) being run
- eclipse.commands
- sdf
- eclipse.consoleLog
- 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
- eclipse.debug.startupTime
- the time in milliseconds when the Java VM for this session was started
- eclipse.exitcode
- <description>
- eclipse.exitdata
- <description>
- eclipse.manifestConverter
- the class name of the manifest converter class to use when converting legacy
plugin.xml files to manifest.mf files
- eclipse.noExtensionMunging
- 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.
- eclipse.noLazyRegistryCacheLoading {-noLazyRegistryCacheLoading}
- 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.
- eclipse.noRegistryCache {-noRegistryCache}
- if "true", the internal extension registry cache is neither read or written
- eclipse.pluginCustomization {-pluginCustomization}
- 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.
- eclipse.product {-product}
- the identifier of the product being run. This controls various branding
information and what application is used.
- eclipse.vm {-vm}
- the path to the Java executable used to run Eclipse. This information is
used to construct relaunch command lines.
- eclipse.vmargs {-vmargs}
- lists the VM arguments used to run Eclipse. This
information is used to construct relaunch command
lines.
- osgi.adaptor
- the class name of the OSGi framework adaptor to use.
- osgi.arch {-arch}
- see -arch
- osgi.baseConfiguration.area
- asf
- osgi.bundles
- 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:
<URL | simple bundle location>[@ [<start-level>] [":start"]]
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.
- osgi.clean
- 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.
- osgi.configuration.cascaded
- if set to "true", this configuration is cascaded to a parent
configuration. See the section on locations for
more details.
- osgi.configuration.area {-configuration}
- 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 locations for
more details.
- osgi.configuration.area.default
- 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 locations for
more details.
- osgi.console {-console}
- 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.
- osgi.console.class
- the class name of the console to run if requested
- osgi.debug {-debug}
- 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.
- osgi.dev {-dev}
- 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
<plug-in id>=<comma separated list of classpath entries to add>
where plug-in id "*" matches any plug-in not otherwise mentioned.
- osgi.framework
- the URL location of the OSGi framework. Useful if the Eclipse install
is disjoint. See the section on locations for more details.
- osgi.frameworkClassPath
- a comma separated list of classpath entries for the OSGi framework implementation.
Relative locations are interpreted as relateve to the framework location
(see osgi.framework)
- osgi.install.area {-install}
- 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 locations for more details.
- osgi.instance.area {-data}
- 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 locations for
more details.
- osgi.instance.area.default
- 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 locations for
more details.
- osgi.manifest.cache
- the location where generated manifests are discovered and generated. The
default is in the configuration area but the manifest cache can be stored
separately.
- osgi.nl {-nl}
- the name of the locale on which Eclipse platform will run. NL values should
follow the standard Java locale naming conventions.
- osgi.os {-os}
- the operating system value. The value should be one of the Eclipse processor
architecture names known to Eclipse (e.g., x86, sparc, ...).
- osgi.splashLocation
- the absolute URL location of the splash screen (.bmp file) to to show while
starting Eclipse. This property overrides any value set in osgi.splashPath.
- osgi.splashPath
- a comma separated list of URLs to search for a file called splash.bmp.
This property is overriden by any value set in osgi.splashLocation.
- osgi.user.area {-user}
- 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 locations for more
details.
- osgi.user.area.default
- 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 locations for
more details.
- osgi.ws {-ws}
- the window system value. The value should be one of the Eclipse window
system names known to Eclipse (e.g., win32, motif, ...).
- osgi.syspath
- <xxx still used? fix the name>
Locations
The Eclipse runtime defines a number of locations 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:
- User (-user) {osgi.user.area} [@none, @noDefault, @user.home, @user.dir,
filepath, url]
- User locations are specific to, go figure, users. Typically the user
location is based on the value of the Java
user.home
system
property but this can be overridden. Information such as user scoped preferences
and login information may be found in the user location.
- Install (-install) {osgi.install.area} [@user.home, @user.dir, filepath,
url]
- 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.
- Configuration (-configuration) {osgi.configuration.area} [@none, @noDefault,
@user.home, @user.dir, filepath, url]
- 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.
- Instance (-data) {osgi.instance.area} [@none, @noDefault, @user.home,
@user.dir, filepath, url]
- 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.
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:
eclipse -data c:\mydata
More detail
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.
- @none
- 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.
- @noDefault
- 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.
- @user.home
- 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
osgi.instance.area=@user.home/myWorkspace
results in a value of
file:/users/bob/myWorkspace
- @user.dir
- 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
osgi.instance.area=@user.dir/myWorkspace
results in a value of
file:/usr/share/eclipse/myWorkspace
location/value |
supports default |
file/URL
|
@none
|
@noDefault
|
@user.home
|
@user.dir
|
instance
|
yes |
yes
|
yes
|
yes
|
yes
|
yes (default)
|
configuration
|
yes
|
yes
|
yes*
|
yes*
|
yes
|
yes
|
install
|
no
|
yes
|
no
|
no
|
yes
|
yes
|
user
|
yes
|
yes
|
yes
|
yes
|
yes
|
yes
|
* 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.
