Running Eclipse

After you install (unzip) the Eclipse driver in a directory (such as c:\eclipse), start the Workbench by running the Eclipse executable file found in the top level install directory. The executable file is called eclipse.exe on Windows systems and eclipse on Linux systems. Note: the following discussion describes setting up on Windows systems. Setup on Linux is analogous.

If you do not specify otherwise, the platform creates a default workspace directory as a sibling of the executable (for example, c:\eclipse\workspace). This workspace directory is used as the default content area for your projects as well as for holding any required metadata. For shared or multi-workspace installs you should explicitly state the location of your workspace rather than using the default. There are two ways to control the location of your workspace: using the current working directory or using the -data command line argument.

 

Setting the workspace location to be inside the current working directory

In this scenario, the workspace location will be a directory called workspace inside the current working directory.

Perhaps the easiest way of doing this is to create a shortcut using the following steps:

  1. Navigate to eclipse.exe in the Windows Explorer and using a right button drag, create a shortcut to eclipse.exe.
  2. Edit the properties of the shortcut such that the Start in: field identifies the parent directory of your workspace location (for example, c:\users\robert).
  3. Close the properties dialog and double-click on the shortcut (if the provided directory was c:\users\robert, the workspace location would be c:\users\robert\workspace).

Of course you can get the same effect using a command prompt by changing directory to your workspace parent's directory and then running eclipse.exe.

 

Setting a specific location for the workspace with -data

To use the -data command line argument, simply add -data your_workspace_location (for example, -data c:\users\robert\myworkspace) to the Target field in the shortcut properties, or include it explicitly on your command line.

 

Setting the java VM using -vm

It is recommended that you explicitly specify which Java VM to use when running Eclipse. This is achieved with the -vm command line argument (for example, -vm c:\jre\bin\javaw.exe). If you don't use -vm, Eclipse will use the first Java VM found on the O/S path. When you install other products, they may change your path, resulting in a different Java VM being used when you next launch Eclipse.

 

Advanced Topics in Running Eclipse

The Eclipse executable and the platform itself offer a number of execution options of interest to people developing or debugging parts of Eclipse. This is a list of the commonly used options, for a full list see the Eclipse runtime options page in the Platform Plug-in Developer Guide. The general form of running the Eclipse executable is:

eclipse [platform options] [-vmargs [Java VM arguments]]

Eclipse Startup Parameters
Command Description Since 
-arch architecture
Defines the processor architecture on which the Eclipse platform is running. The Eclipse platform ordinarily computes the optimal setting using the prevailing value of Java os.arch property. If specified here, this is the value that the Eclipse platform uses. The value specified here is available to plug-ins as BootLoader.getOSArch(). Example values: "x86", "sparc", "PA-RISC", "ppc". 2.0 
-application applicationId
The application to run. Applications are declared by plug-ins supplying extensions to the org.eclipse.core.runtime.applications extension point. This argument is typically not needed. If specified, the value overrides the value supplied by the configuration. If not specified, the Eclipse Workbench is run. 1.0 
-configuration configurationFileURL
The location for the Eclipse Platform configuration file, expressed as a URL. The configuration file determines the location of the Eclipse platform, the set of available plug-ins, and the primary feature. Note that relative URLs are not allowed. The configuration file is written to this location when the Eclipse platform is installed or updated. 2.0 
-consolelog
Mirrors the Eclipse platform's error log to the console used to run Eclipse. Handy when combined with -debug. 1.0 
-data workspacePath
The path of the workspace on which to run the Eclipse platform. The workspace location is also the default location for projects. Relative paths are interpreted relative to the directory that Eclipse was started from. 1.0 
-debug [optionsFile]
 Puts the platform in debug mode and loads the debug options from the file at the given location, if specified. This file indicates which debug points are available for a plug-in and whether or not they are enabled. If a file location is not given, the platform looks in the directory that eclipse was started from for a file called ".options". Both URLs and file system paths are allowed as file locations. 1.0 
-dev [classpathEntries]
Puts the platform in development mode. The optional classpath entries (a comma separated list) are added to the runtime classpath of each plug-in. For example, when the workspace contains plug-ins being developed, specifying -dev bin adds a classpath entry for each plug-in project's directory named bin, allowing freshly generated class files to be found there. Redundant or non-existent classpath entries are eliminated. 1.0 
-keyring keyringFilePath
 The location of the authorization database (or "key ring" file) on disk. This argument must be used in conjunction with the -password option. Relative paths are interpreted relative to the directory that Eclipse was started from. 1.0 
-nl locale
Defines the name of the locale on which the Eclipse platform is running. The Eclipse platform ordinarily computes the optimal setting automatically. If specified here, this is the value that the Eclipse platform uses. The value specified here is available to plug-ins as BootLoader.getNL(). Example values: "en_US" and "fr_FR_EURO". 2.0 
-nosplash
Runs the platform without putting up the splash screen. 1.0 
-os operatingSystem
Defines the operating system on which the Eclipse platform is running. The Eclipse platform ordinarily computes the optimal setting using the prevailing value of Java os.name property. If specified here, this is the value that the Eclipse platform uses. The value specified here is available to plug-ins as BootLoader.getOS(), and used to resolve occurrences of the $os$ variable in paths mentioned in the plug-in manifest file. Example values: "win32", "linux", "hpux", "solaris", "aix". 1.0 
-password password
The password for the authorization database. Used in conjunction with the -keyring option. 1.0 
-perspective perspectiveId
The perspective to open in the active workbench window on startup. If this parameter is not specified, the perspective that was active on shutdown will be opened. 1.0 
-plugincustomization
      propertiesFile
The 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 directory that eclipse was started from. 2.0 
-product productId
The ID of the product to run. The product gives the launched instance of Eclipse its personality, and determines the product customization information used. This replaces -feature, which is still supported for compatibility. 3.0 
-refresh
Option for performing a global refresh of the workspace on startup. This will reconcile any changes that were made in the file system since the platform was last run. 1.0 
-showlocation
Option for displaying the location of the workspace in the window title bar. In release 2.0 this option only worked in conjunction with the -data command line argument. 2.0 
-vm vmPath
The location of Java Runtime Environment (JRE) to use to run the Eclipse platform. If not specified, the JRE is at jre, sibling of the Eclipse executable. Relative paths are interpreted relative to the directory that eclipse was started from. 1.0 
-vmargs args
When passed to the Eclipse, this option is used to customize the operation of the Java VM used to run Eclipse. If specified, this option must come at the end of the command line. The given arguments are dependant on VM that is being run. 1.0

All arguments following (but not including) the -vmargs entry are passed directly through to the indicated Java VM as virtual machine arguments (that is, before the class to run). Note: If an Eclipse startup argument, such as -data, is provided after the Java vm arguments (-vmargs), Eclipse will not start and you will receive a "JVM terminated. Exit code=1" error.

 

Running on Different VMs 

 

Running Eclipse on J9

When running Eclipse on J9 version 1.5, it is recommended that you use the following VM options: 

eclipse.exe [eclipse arguments] -vm path_to_j9w.exe 
            -vmargs -ms:32 -mm:2048 -mo:32768 -moi:32768 -mca:32 -mco:128 -mx:2000000

When running Eclipse on J9 version 2.0, the default arguments chosen by J9W should be suitable. However, to override the parameters which are automatically set internally by the Eclipse executable, specify -vmargs with no following arguments as follows: 

eclipse.exe [eclipse arguments] -vm path_to_j9w.exe -vmargs

Please refer to the J9 VM documentation and help for further information.

 

Running Eclipse on the IBM Developer Kit, Java(TM) Technology Edition VM

The default VM settings for IBM Developer Kit, Java(TM) Technology Edition 1.3 Linux work well for initial exploration, but are not sufficient for large scale development. For large scale development you should modify your VM arguments to make more heap available. For example, the following setting will allow the Java heap to grow to 256MB:  

-vmargs -Xmx256M