| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> |
| <HEAD> |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Running Eclipse</title> |
| </head> |
| |
| <BODY BGCOLOR="#ffffff"> |
| |
| <h1>Running Eclipse</h1> |
| <p>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 <samp>eclipse.exe</samp> on Windows |
| systems and <samp>eclipse</samp> on Linux systems. |
| |
| <b>Note:</b> the following discussion describes setting up on Windows systems. Setup on Linux is |
| analogous.</p> |
| |
| <p>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.</p> |
| |
| <h3>Setting the workspace location to be inside the current working directory</h3> |
| |
| <p>In this scenario, the workspace location will be a directory called <samp>workspace</samp> |
| inside the current working directory.</p> |
| |
| <p>Perhaps the easiest way of doing this is to create a |
| shortcut using the following steps:</p> |
| |
| <ol> |
| <li>Navigate to eclipse.exe in the Windows Explorer and using a right button drag, create a shortcut |
| to eclipse.exe.</li> |
| <li>Edit the properties of the shortcut such that the <b>Start in:</b> |
| field identifies the parent directory of your workspace location (for example, <samp>c:\users\robert</samp>).</li> |
| <li>Close the properties dialog and double-click on the shortcut (if the provided directory was <samp>c:\users\robert</samp>, |
| the workspace location would be <samp>c:\users\robert\workspace</samp>).</li> |
| </ol> |
| <p>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.</p> |
| |
| <h3>Setting a specific location for the workspace with -data</h3> |
| |
| <p>To use the <code>-data</code> command line argument, simply add <code>-data <var>your_workspace_location</var></code> |
| (for example, <code>-data c:\users\robert\myworkspace</code>) |
| to the <b>Target</b> field in the shortcut properties, or include it explicitly on your |
| command line.</p> |
| |
| <h3>Setting the java VM using -vm</h3> |
| |
| <p>It is recommended that you explicitly specify which Java VM to |
| use when running Eclipse. This is achieved with the <code>-vm</code> command line |
| argument (for example, <code>-vm c:\jre\bin\javaw.exe</code>). If you don't use |
| <code>-vm</code>, 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. |
| </p> |
| |
| <h2>Advanced Topics in Running Eclipse </h2> |
| |
| <p>The Eclipse executable and the platform itself offer a number of execution |
| options of interest to people developing or debugging parts of Eclipse. |
| The general form of running the Eclipse executable is:</p> |
| |
| <blockquote> |
| |
| <pre>eclipse [platform options] [-vmargs [Java VM arguments]]</pre> |
| |
| </blockquote> |
| |
| <TABLE width="90%" border=1 height="543"> |
| <caption> |
| <b> |
| Eclipse Startup Parameters |
| </b> |
| </caption> |
| <TBODY> |
| <tr> |
| <th width="33%"> |
| <b>Command</b></th> |
| <th width="65%"><b>Description</b></th> |
| <TD width="2%"><b>Since</b></TD> |
| </tr> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-arch</b> <var>architecture</var></pre></TD> |
| <TD width="65%">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 <code>os.arch</code> |
| 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".</TD> |
| <TD width="2%">2.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-application</b> <var>applicationId</var></PRE></TD> |
| <TD width="65%">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.</TD> |
| <TD width="2%">1.0</TD> |
| </TR> |
| <TR> |
| <TD vAlign=top width="33%"><PRE><b>-boot</b> <var>bootJarURL</var></PRE></TD> |
| <TD width="65%"><i>(Deprecated; replaced by -configuration; supported for |
| 1.0 compatibility)</i>. The location of the Eclipse platform's boot plug-in |
| code (boot.jar), expressed as a URL. If specified, it is used to |
| set the classpath for the class loader that loads the Eclipse platform |
| bootstrap class loader. Only required when changing the relative location |
| of startup.jar and boot.jar. Note that relative URLs are not allowed. |
| </TD> |
| <TD width="2%">*1.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-classloaderproperties</b> <var>[file]</var></pre></TD> |
| <TD width="65%">Activates platform class loader enhancements using the class |
| loader properties file at the given location, if specified. The file argument |
| can be either a file path or a URL. Note that relative URLs are not allowed. |
| Click <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-core-home/docs/classloader-properties/classloader_properties.html">here</a> |
| for more details.</TD> |
| <TD width="2%">2.0.2</TD> |
| </tr> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-configuration</b> <var>configurationFileURL</var></pre> |
| </TD> |
| <TD width="65%">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. |
| </TD> |
| <TD width="2%">2.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%"><PRE><b>-consolelog</b></PRE></TD> |
| <TD width="65%">Mirrors the Eclipse platform's error log to the console |
| used to run Eclipse. Handy when combined with <code>-debug</code>.</TD> |
| <TD width="2%">1.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-data</b> <var>workspacePath</var></PRE></TD> |
| <TD width="65%">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.</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-debug</b> [<var>optionsFile</var>]</PRE></TD> |
| <TD width="65%"> 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. </TD> |
| <TD width="2%">1.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-dev</b> [<var>classpathEntries</var>]</PRE></TD> |
| <TD width="65%">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 <code>-dev bin</code> adds a classpath |
| entry for each plug-in project's directory named <code>bin</code>, |
| allowing freshly generated class files to be found there. Redundant |
| or non-existent classpath entries are eliminated.</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%" height="16"><pre><b>-endsplash</b> <var>params</var></pre></TD> |
| <TD width="65%" height="16">Internal option for taking down the splash screen |
| when the Eclipse platform is up and running. This option has different |
| syntax and semantics at various points along the splash screen processing |
| chain.</TD> |
| <TD width="2%" height="16">2.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-feature</b> <i>featureId</i></pre></TD> |
| <TD width="65%" height="16">The ID of the primary feature. The primary feature |
| gives the launched instance of Eclipse its product personality, and determines |
| the product customization information used.</TD> |
| <TD width="2%" height="16">2.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%"> |
| <pre><b>-keyring</b> <var>keyringFilePath</var></pre></TD> |
| <TD width="65%"> The location of the authorization database (or "key |
| ring" file) on disk. This argument must be used in conjunction |
| with the <code>-password</code> option. Relative paths are interpreted |
| relative to the directory that Eclipse was started from.</TD> |
| <TD width="2%">1.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-nl</b> <var>locale</var></pre></TD> |
| <TD width="65%">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".</TD> |
| <TD width="2%">2.0</TD> |
| </tr> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-nolazyregistrycacheloading</b></pre></TD> |
| <TD width="65%">Deactivates platform plug-in registry cache loading optimization. |
| By default, extensions' configuration elements will be loaded from the registry cache |
| (when available) only on demand, reducing memory footprint. This option will force the |
| registry cache to be fully loaded at startup.</TD> |
| <TD width="2%">2.1</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%"> |
| <pre><b>-noregistrycache</b></pre></TD> |
| <TD width="65%">Bypasses the reading and writing of an internal plug-in |
| registry cache file.</TD> |
| <TD width="2%">2.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-nosplash</b></PRE></TD> |
| <TD width="65%">Runs the platform without putting up the splash screen.</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-os</b> <var>operatingSystem</var></PRE></TD> |
| <TD width="65%">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 <code>os.name</code> 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 <code>$os$</code> variable in paths |
| mentioned in the plug-in manifest file. Example values: "win32", "linux", |
| "hpux", "solaris", "aix".</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%"> |
| <pre><b>-password</b> <var>password</var></pre></TD> |
| <TD width="65%">The password for the authorization database. Used in conjunction |
| with the <code>-keyring</code> option.</TD> |
| <TD width="2%">1.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-perspective</b> <var>perspectiveId</var></PRE></TD> |
| <TD width="65%">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.</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <pre><b>-plugincustomization</b> |
| <var>propertiesFile</var></pre></TD> |
| <TD width="65%">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.</TD> |
| <TD width="2%">2.0</TD> |
| </tr> |
| <TR> |
| <TD vAlign=top width="33%" height="16"><pre><b>-plugins</b> <var>pluginsFileURL</var></pre></TD> |
| <TD width="65%" height="16"><i>(Deprecated; replaced by -configuration; |
| supported for 1.0 compatibility).</i> The location of the file that specifies |
| where the Eclipse platform finds plug-ins, expressed as a URL. The file |
| is in property file format where the keys are arbitrary user defined names |
| and the values are comma separated lists of either explicit paths |
| to plugin.xml files, or paths to directories containing plug-ins. |
| Note that relative URLs are not allowed. If specified, this option causes |
| the creation of a suitable temporary configuration.</TD> |
| <TD width="2%" height="16">*1.0</TD> |
| </TR> |
| <TR> |
| <TD vAlign=top width="33%" height="16"><pre><b>-refresh</b> </pre></TD> |
| <TD width="65%" height="16">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. </TD> |
| <TD width="2%" height="16">1.0</TD> |
| </TR> |
| <TR> |
| <TD vAlign=top width="33%" height="16"><pre><b>-showlocation</b> </pre></TD> |
| <TD width="65%" height="16">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.</TD> |
| <TD width="2%" height="16">2.0</TD> |
| </TR> |
| <TR> |
| <TD vAlign=top width="33%" height="16"><pre><b>-showsplash</b> <var>params</var></pre></TD> |
| <TD width="65%" height="16">Internal option for showing the splash screen |
| (done by the executable Eclipse platform launcher). This option has |
| different syntax and semantics at various points along the splash screen |
| processing chain.</TD> |
| <TD width="2%" height="16">2.0</TD> |
| </TR> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-vm</b> <var>vmPath</var></PRE></TD> |
| <TD width="65%">The location of Java Runtime Environment (JRE) to use to |
| run the Eclipse platform. If not specified, the JRE is at <code>jre</code>, |
| sibling of the Eclipse executable. Relative paths are interpreted relative |
| to the directory that eclipse was started from.</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| <tr> |
| <TD vAlign=top width="33%"> |
| <PRE><b>-ws</b> <var>windowSystem</var></PRE></TD> |
| <TD width="65%">Defines the window system on which the Eclipse platform |
| is running. The Eclipse platform ordinarily computes the optimal setting |
| using the prevailing value of Java <code>os.name</code> property. |
| If specified here, this is the value that the Eclipse platform uses. The |
| value specified here is available to plug-ins as BootLoader.getWS(), used |
| to configure SWT, and used to resolve occurrences of the <code>$ws$</code> |
| variable in paths mentioned in the plug-in manifest file. Example values: |
| "win32", "motif", "gtk".</TD> |
| <TD width="2%">1.0</TD> |
| </tr> |
| </TBODY> |
| </TABLE> |
| |
| <p>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). <b>Note:</b> 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. |
| </p> |
| |
| <h2>Running on Different VMs </h2> |
| <h3>Running Eclipse on J9</h3> |
| <p> |
| When running Eclipse on J9 version 1.5, it is recommended that you use the following VM |
| options: |
| </p> |
| <blockquote> |
| <pre>eclipse.exe [eclipse arguments] -vm <var>path_to_j9w.exe</var> |
| -vmargs -ms:32 -mm:2048 -mo:32768 -moi:32768 -mca:32 -mco:128 -mx:2000000</pre> |
| </blockquote> |
| <p> 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, you must specify -vmargs with no following arguments |
| as follows: </p> |
| <blockquote> |
| <pre>eclipse.exe [eclipse arguments] -vm <var>path_to_j9w.exe</var> -vmargs</pre> |
| </blockquote> |
| <p>Please refer to the J9 VM documentation and help for further information.</p> |
| |
| <h3>Running Eclipse on the IBM Developer Kit, Java(TM) Technology Edition VM</h3> |
| |
| <p>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: |
| </p> |
| <blockquote> |
| <pre>-vmargs -Xmx256M </pre> |
| </blockquote> |
| |
| <p> <br> |
| <a href="../hglegal2003.htm"><img src="../images/ngibmcpy2003.gif" alt="Copyright IBM Corporation and others 2000, 2003" border="0" width="324" height="14"></a> |
| </p> |
| |
| </body> |
| </html> |
