Running Wolfram Workbench

After installing the Wolfram Workbench SDK in a directory, you can start the Workbench by running the Wolfram Workbench executable included with the release (you also need a 1.4.2 JRE, not included with the Wolfram Workbench SDK). On Windows, the executable file is called eclipse.exe, and is located in the eclipse sub-directory of the install. If installed at c:\eclipse-SDK-3.5-win32, the executable is c:\eclipse-SDK-3.5-win32\eclipse\eclipse.exe. Note: Set-up on most other operating environments is analogous. Special instructions for Mac OS X are listed below.

Allocating enough memory and solving OutOfMemoryErrors

By default, Wolfram Workbench will allocate up to 256 megabytes of Java heap memory. This should be ample for all typical development tasks. However, depending on the JRE that you are running, the number of additional plug-ins you are using, and the number of files you will be working with, you could conceivably have to increase this amount. Wolfram Workbench allows you to pass arguments directly to the Java VM using the -vmargs command line argument, which must follow all other Wolfram Workbench specific arguments. Thus, to increase the available heap memory, you would typically use:

eclipse -vmargs -Xmx<memory size>

with the <memory size> value set to greater than "256M" (256 megabytes -- the default).

When using a Sun VM, you may also need to increase the size of the permanent generation memory. The default maximum is 64 megabytes, but more may be needed depending on your plug-in configuration and use. When the VM runs out of permanent generation memory, it may crash or hang during class loading. This failure is less common when using Sun JRE version 1.5.0_07 or greater. The maximum permanent generation size is increased using the -XX:MaxPermSize=<memory size> argument:

eclipse -vmargs -XX:MaxPermSize=<memory size>

This argument may not be available for all VM versions and platforms; consult your VM documentation for more details.

Note that setting memory sizes to be larger than the amount of available physical memory on your machine will cause Java to "thrash" as it copies objects back and forth to virtual memory, which will severely degrade your performance.

Selecting a workspace

When the Workbench is launched, the first thing you see is a dialog that allows you to select where the workspace will be located. The workspace is the directory where your work will be stored. If you do not specify otherwise, Wolfram Workbench creates the workspace in your user directory. 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 must explicitly specify the location for your workspace using the dialog (or via the "-data" command line argument).

Specifying the Java virtual machine

Here is a typical Wolfram Workbench command line: 

eclipse -vm c:\jdk1.4.2\jre\bin\javaw

Tip: It's generally a good idea to explicitly specify which Java VM to use when running Wolfram Workbench. This is achieved with the "-vm" command line argument as illustrated above. If you don't use "-vm", Wolfram Workbench will look on the O/S path. When you install other Java-based products, they may change your path and could result in a different Java VM being used when you next launch Wolfram Workbench.

To create a Windows shortcut to an installed Wolfram Workbench:

  1. Navigate to eclipse.exe in Windows Explorer and use Create Shortcut on the content menu.
  2. Select the shortcut and edit its Properties. In the Target: field append the command line arguments.

Opening this shortcut launches Wolfram Workbench. (You can drag the shortcut to the Windows Desktop if you want to keep it in easy reach.)

Mac OS X

On Mac OS X, you start Wolfram Workbench by double clicking the Wolfram Workbench application. If you need to pass arguments to Wolfram Workbench, you'll have to edit the eclipse.ini file inside the Wolfram Workbench application bundle: select the Wolfram Workbench application bundle icon while holding down the Control Key. This will present you with a popup menu. Select "Show Package Contents" in the popup menu. Locate eclipse.ini file in the Contents/MacOS sub-folder and open it with your favorite text editor to edit the command line options.

On MacOS X you can only launch a UI program more than once if you have separate copies of the program on disk. The reason for this behavior is that every UI application on Mac can open multiple documents, so typically there is no need to open a program twice. Since Wolfram Workbench cannot open more than one workspace, this means you have to make a copy of the Wolfram Workbench install if you want to open more then one workspace at the same time (bug 139319).

If you need to launch Wolfram Workbench from the command line, you can use the symbolic link "eclipse" in the top-level eclipse folder. It refers to the eclipse executable inside the application bundle and takes the same arguments as "eclipse.exe" on other platforms.

On Mac OS X 10.4 and later, you may notice a slow down when working with significant numbers of resources if you allow Spotlight to index your workspace. To prevent this, start System Preferences, select the Spotlight icon, then the Privacy tab, then click the Add button ("+") and find your workspace directory in the dialog that appears.

Shared Install

The startup speed of a shared install can be improved if proper cache information is stored in the shared install area. To achieve this, after unzipping Wolfram Workbench distribution, run Wolfram Workbench once with the "-initialize" option from an account that has a write access to the install directory.

Advanced Topics in Running Wolfram Workbench

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

eclipse [platform options] [-vmargs [Java VM arguments]]
Wolfram Workbench Startup Parameters
Command Description Since
-arch architecture
Defines the processor architecture on which the Wolfram Workbench platform is running. The Wolfram Workbench platform ordinarily computes the optimal setting using the prevailing value of Java os.arch property. If specified here, this is the value that the Wolfram Workbench platform uses. The value specified here is available to plug-ins as Platform.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 Wolfram Workbench is run. 1.0
-clean
Cleans cached data used by the OSGi framework and Wolfram Workbench runtime. Try to run Wolfram Workbench once with this option if you observe startup errors after install, update, or using a shared configuration. 3.0
-configuration configURL
The location for the Wolfram Workbench Platform configuration file, expressed as a URL. The configuration file determines the location of the Wolfram Workbench 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 Wolfram Workbench platform is installed or updated. 2.0
-consolelog
Mirrors the Wolfram Workbench platform's error log to the console used to run Wolfram Workbench. Handy when combined with -debug. 1.0
-data workspacePath
The path of the workspace on which to run the Wolfram Workbench platform. The workspace location is also the default location for projects. Relative paths are interpreted relative to the directory that Wolfram Workbench 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
-initialize
Initializes the configuration being run. All runtime related data structures and caches are refreshed. Handy with shared installs: running Wolfram Workbench once with this option from an account with write privileges will improve startup performance. 3.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 Wolfram Workbench was started from. 1.0
-nl locale
Defines the name of the locale on which the Wolfram Workbench platform is running. The Wolfram Workbench platform ordinarily computes the optimal setting automatically. If specified here, this is the value that the Wolfram Workbench platform uses. The value specified here is available to plug-ins as Platform.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 Wolfram Workbench platform is running. The Wolfram Workbench platform ordinarily computes the optimal setting using the prevailing value of Java os.name property. If specified here, this is the value that the Wolfram Workbench platform uses. The value specified here is available to plug-ins as Platform.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 Wolfram Workbench 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 [workspaceName]
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. In 3.2, an optional workspace name argument was added that displays the provided name in the window title bar instead of the location of the workspace. 2.0
-vm vmPath
The location of Java Runtime Environment (JRE) to use to run the Wolfram Workbench platform. If not specified, the launcher will attempt to find a JRE. It will first look for a directory called jre as a sibling of the Wolfram Workbench executable, and then look on the operating system path. Relative paths are interpreted relative to the directory that eclipse was started from. 1.0
-vmargs args
When passed to the Wolfram Workbench, this option is used to customize the operation of the Java VM used to run Wolfram Workbench. 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 Wolfram Workbench startup argument, such as -data, is provided after the Java vm arguments (-vmargs), Wolfram Workbench will not start and you will receive a "JVM terminated. Exit code=1" error.