Running

Running

After installation (unzipping) the workbench is started by running the executable found in the top-level install directory. Note, the following discussion details the setup on Windows systems.  The Linux setup is analogous.

If you don't specify differently, the platform creates a default workspace directory as a sibling of the executable.  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.

Perhaps the easiest way of using the current working directory is to create a shortcut using the following steps:

  1. Navigate to the executable in the Windows Explorer and using a right button drag, create a shortcut to the executable.
  2. Edit the properties of the shortcut such that the "Start in:" box identifies the location of your workspace (e.g., c:\myworkspace).
  3. Close the properties dialog and double-click on the shortcut.
Of course you can get the same effect using a command prompt by changing directory to your workspace directory and then running the executable.

To use the -data command line argument, simply add -data <your workspace location> (e.g., -data c:\myworkspace) to the "Target:" line in the shortcut or include it explicitly on your command prompt command line.

Advanced topics

The executable and the platform itself offers a number of execution options of interest to people developing or debugging plugins.  The general form of running the executable is:
platform [platform options] [-vmargs [Java VM arguments]]
where platform is the name of the executable found in the top leve; directory of your install.

where the valid platform options are:
 

-application <app id> Identifies the application to run.  If not specified, the workbench is run.  Applications are declared by plug-ins supplying extensions to the org.eclipse.core.runtime.applications extension point.
-boot <boot code path> Defines the path to the boot plug-in code (i.e., boot.jar).  Only required when changing the relative location of startup.jar and boot.jar. 
-consolelog Mirrors the platform's error log to the console used to run the platform.
-data <workspace path> Defines the path of the workspace on which to run the platform.
-debug [options file path] Puts the platform in debug mode and loads the debug options in the specified file.  If a file path is not given, the platform looks in the platform install directory and in the workspace's metadata directory for a file called ".options".
-dev [classpath entries] Puts the platform in development mode.  The optional classpath entries (a comma-separated list) are added to each plug-in's classpath.  For example, when developing plug-ins, use "-dev bin" to add the Java tooling's bin directory for each plug-in.  Redundant or non-existant classpath entries are eliminated.
-nosplash Runs the platform without putting up the splash screen.
-os <os-id> Defines the operating system on which the platform is running.  Typically the platform can detect the OS but some situations may require explicit specification.  The value specified here is related to Platform.getOS().
-vm <vm path> Specifies the Java VM to use to run the platform.  If not specified, a Java VM is located relative to the executable.
-ws <ws-id> Defines the window system on which the platform is running.  In many cases the platform can detect the window system but some situations may require explicit specification.  The value specified here is related to Platform.getWS().
All arguments following (but not including) the -vmargs entry are passed directly through to the indicated Java VM as virtual machine arguments (i.e., before the class to run).  All arguments preceding the -vmargs entry (with the exception of -vm and -nosplash) are passed directly through to the platform for interpretation.

Running on Different VMs

Running on J9

When running on J9, it is recommended that you use the following VM options.  Please refer to the J9 VM documentation and help for further information:
platform [arguments] -vm <path to j9w.exe> 
            -vmargs -ms:20 -jit -mo:32000 -mx:200000
where platform is the name of the executable found in the top leve; directory of your install and arguments are those arguments to be passed to the platform.

NOTE: the -vmargs flag and the actual vm arguments must come at the end of the line.

Running 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 larger scale development. For large-scale development you should  modify your vm arguments to make more heap available:
-vmargs -Xmx256M
will allow the Java heap to grow to 256MB.