# Eclipse multi-user installs

Eclipse provides a number of strategies for supporting multi-user installs. Each strategy satisfies a specific scenario. This document covers these strategies, describing when each one should be used. The intended readers are product engineers configuring an Eclipse-based product for distribution, system administrators setting up Eclipse-based products to be used through a network and developers interested in creating plug-ins that are good citizens in such setups.

Last Modified: June 17th, 2005

## Basic concepts

### Locations

As described in the Eclipse Runtime options article, there are three different locations that are important in the context of deploying Eclipse in a multi-user setup:

- install area - the location where the Eclipse Platform is installed. This location can be read-only, since neither the Eclipse runtime nor plug-ins are supposed to write there. However, in a single user scenario, the configuration area, which is typically writable, defaults to a directory called "configuration" stored under the install area.
- configuration area - the location where Eclipse stores essential runtime metadata (such as information about the set of plug-ins installed and the dependencies between them) and cached data in general. Eclipse cannot run without a configuration area. Plug-ins may choose to store data here that should be available regardless the workspace in use (for instance, help index files). User settings shared across workspaces are also stored under this location.
- instance area - the location where user files are stored, commonly called the workspace. It is optional, however most Eclipse-based products require an instance area to work. The instance area cannot be shared, although a single user might maintain multiple instance areas. Inside the instance area there is a special directory called .metadata, where plug-ins store their own workspace-specific metadata and user settings.

### Configuration initialization

Before Eclipse has been run for the first time, the configuration area is basically an empty directory. This location is gradually populated by the Eclipse runtime, and other plug-ins, across Eclipse sessions. Most of the metadata kept by the Eclipse runtime (e.g. plug-in dependencies, the extension registry) is written during the shutdown of the first session. If no changes are made to the set of installed plug-ins, no data has to be written during subsequent sessions. We say the configuration is initialized. When the configuration is in this state, it is even possible to make the configuration area read-only. Making the configuration area read-only is useful in scenarios such as shared configurations (more on this later).

The `-initialize` command-line option allows one to initialize the configuration area without requiring an Eclipse application to run. The initialization procedure forces the creation of any metadata that is written out to the configuration location during the first Eclipse session. However, there are other files kept in the configuration area that are created only when needed. Examples are:

- Help indexes - only created for the first time the Eclipse Help system is opened. After it is created, provided the user locale does not change, no files are ever written again.
- files extracted out of plug-in JARs - plug-ins shipped as JARs often need to access embedded files as plain files on the file system. For that, plug-ins call the Eclipse Runtime API `Platform.asLocalURL(URL)`. The result is that if the URL refers to a file inside a JAR, that file will be extracted to the file system under the configuration area. Once a file is extracted, subsequent calls to `Platform.asLocalURL()` will be able to find it, so no additional extractions will occur for that file. A similar (actually, the original) scenario where `Platform.asLocalURL` is used that has the same consequences relates to making sure remote contents (for instance, a file accessible via a http URL) are available locally.

For these cases (and others that 3rd-party plug-ins might introduce), the initialization procedure is not sufficient to fully initialize the configuration area. There will still be need to write to the configuration area although this need tends to disappear as all the execution paths in the application that cause files to be created in the configuration area are visited. Only after that it can be said the configuration area is fully initialized and no write access to it will ever be required in order for Eclipse to run.

## Scenario #1 - private install

This is actually a single-user scenario. The Eclipse install is used by a single user, and the user has full access privileges to it. The configuration area location defaults to the configuration directory under the install location.

The procedure to set up this scenario requires just making sure the user has full rights to the install location.

## Scenario #2 - shared install

In this scenario, a single install area is shared by many users. The "configuration" directory under the install area is home only to the config.ini as shipped with the product (it is not initialized). Every user has their own local standalone configuration location.

The set up for this scenario requires making the install area read-only for regular users. When users start Eclipse, this causes the configuration area to automatically default to a directory under the user home dir. If this measure is not taken, all users will end up using the same location for their configuration area, which is not supported.

## Scenario #3 - shared configuration

Here users share not only an install area but also a master configuration area. Users still have, by default, their own private writable configuration areas. A user's private configuration area is cascaded to the master configuration and will not contain any interesting data if the master configuration has been fully initialized and no changes to the set of plug-ins to be installed has occurred.

In this scenario, the system administrator initializes the master configuration (typically under the install location), and ensures the whole install and configuration areas are read-only to users. When users run the Eclipse-based product from the shared install location, since they do not have write access privileges to the configuration area under the install area, a local configuration area will be automatically computed and initialized.

The more fully initialized the shared configuration is, the less need there is for files to be created under the local configuration.

### Setting the private configuration area location

The default location for a private configuration area is:

`<user-home-dir>/.eclipse/<product-id>_<product-version>/configuration`

The user home dir is determined by the `user.home` Java system property. The product id and version are obtained from the product marker file `.eclipseproduct` under the Eclipse install.

A non-default configuration area can be defined by setting the `osgi.configuration.area` system property. This property can be set by the end user, but it is more convenient to set it either in the launcher .ini file or in the config.ini file at the base configuration location.

### Updating

#### Shared configuration

Plug-ins can be installed in/removed from the shared configuration. Users will catch up with those changes the next time Eclipse runs. It is necessary to make sure users having the shared configuration as their master configuration are not running Eclipse.

#### Private configuration

Users can modify their local configuration areas by installing additional plug-ins. This does not cause any changes to the shared configuration, so other users will not see the changes. Note that plug-ins configured at the shared configuration cannot be removed. If they are, they will be reinstalled the next time the platform starts.