Multi-user Installs of Eclipse-based Products

Last revised 15:30 Monday May 6, 2002

There are special considerations when a product is installed somewhere in a shared file system so that the installed base of files can be used simultaneously by several users. Doing this requires making and maintaining a clear separation between files containing information that should be common across users from files containing user-specific information, for which each user will need personal copies. It helps to think of the installed based of files as being read-only (which they often are), and imagine that these installed files can only be created or changed when the product is installed (or updated). The user-specific files are stored elsewhere in some read-write user space.

This note describes how shared, multi-user installs of Eclipse-based products work.

What product developers need to know

When an Eclipse-based product is installed on a disk, various files are laid out in the product install directory (denoted <install>) which is specified at the time the product is installed. Installed files directly related to Eclipse are in the <install>/eclipse/ subdirectory. Installed files are neither written nor deleted during the normal course of operating the Eclipse-based product.

When an Eclipse-base product is installed, special one-time initialization is initiated with the -initialize option. This invocation creates and modifies files in <install>/eclipse/. These files ensure that the product starts quickly, with the correct splash screen, on subsequent occasions. Once installed and initialized, the <install> directory can be write-protected without impacting the ability for a user to successfully operate the product stored there. The product installer and the Eclipse update manager are the only parties that alter the installed base of files. 

Running an Eclipse-based product requires a read-write "workspace" area (denoted <workspace>) to hold Eclipse platform and plug-in data. The user can specify the location of the workspace area explicitly with -data <workspace> on the command line. If not specified on the command line, the location of the workspace defaults to <current working directory>/workspace/. The user can have any number of workspaces for use with a given product. Because of this, a single user with several workspaces is the small scale version of a multi-user install; the only significant difference is that in the former case the user is likely to also have write access to the installed base of files.

To make things confusing, a common Windows shortcut to <install>/eclipse/eclipse.exe will default <current working directory> to the directory holding the executable. As a direct consequence, the default workspace will appear inside the install directory (!), at <install>/eclipse/workspace/. Similarly, a Windows shortcut to <install>/myproduct.exe will cause the default workspace to appear up one directory level, at <install>/workspace/. Both arrangements work fine for a single-user install, but are problematic for a shared, multi-user install.

For a multi-user install, <current working directory> should be a read-write directory in user space, apart from the <install> directory. This ensures that the default workspace location is a different place for each user. With a multi-user install, a user without write access to the install directory would be unable to run the product installer or use the Eclipse update manager to change the product install (however, it is still possible to use the update manager to install and configure new features and product updates, just not into the <install> directory).

What product developers do not need to know

N.B. The details in this section are not Eclipse platform API, and may change over time. Do not rely on anything described in this section.

(0) Initial launch behavior

(1) New workspace - precomputed configuration in install (no <workspace>/.metadata/.config/platform.cfg; but <install>/eclipse/.config/platform.cfg present)

(2) New workspace - no precomputed configuration in install (no <workspace>/.metadata/.config/platform.cfg; no <install>/eclipse/.config/platform.cfg either)

(3) Existing workspace (<workspace>/.metadata/.config/platform.cfg)

Note that the above behavior is independent of whether the install is single-user or multi-user.

Using Eclipse update manager to update an install

Using Eclipse update manager to update in the context of a single workspace