blob: 011a9b1db3d9f54ab709d945b03a4c44e9aab46c [file] [log] [blame]
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Eclipse Project">
<title>User Settings</title>
<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</head>
<h1>User Settings in Eclipse</h1>
<blockquote>
<p><strong>Summary</strong>:<br>
This document is a first cut at defining how user settings should be managed
in Eclipse (see bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=36965">36965</a>).
It first states how user settings are currently managed. Following this, the
set of known scenarios involving user settings is presented. Finally, a possible
direction for a solution is presented.</p>
<p>Last Modified: June 25, 2003</p>
<p><strong>Table of Contents:</strong></p>
<p><a href="#intro">Introduction</a><br>
<a href="#today">Settings in Eclipse 2.X</a><br>
<a href="#scenarios">Scenarios</a><br>
<a href="#solution">Towards a Solution</a><br>
<a href="#next">What Next</a></p>
</blockquote>
<hr>
<h2><a name="intro">Introduction</a></h2>
<p>Currently in Eclipse, there are many settings that are persisted over workbench
invocations. Some of these settings are specific to the workspace (e.g. may
contain absolute paths to files, etc). while others are independent of the workspace
location and are, hence, sharable. It should be possible to store user settings
that are not specific to a workspace separate from the workspace, so that they
can be used in other workspaces or by other users (see bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=36965">36965</a>).</p>
<p>Some of the settings in Eclipse are already sharable.User preferences set using
the workspace preference pages can be exported and imported. Plugins can also
provide there own mechanisms for sharing settings. Java projects use a .classpath
file in a project to store project compilation information. The Debug component
provides a mechanism for sharing launch configurations by allowing the location
of a file containing the data for a launch configuration to be specified. There
are other settings that could be shared (e.g. CVS repository list) but currently
are not.</p>
<h2><a name="today">Settings in Eclipse 2.X</a></h2>
<p>To better understand the problem, we will first look how settings are handled
in Eclipse 2.x.</p>
<h3>Types of Settings</h3>
<p>The following table lists several different types of user settings that are
found in Eclipse. With each setting type, the table also lists the mechanisms
used to persist and share the settings.</p>
<table width="75%" border="1">
<tr>
<td><strong>setting</strong></td>
<td><strong>persistence</strong></td>
<td><strong>sharing</strong></td>
</tr>
<tr>
<td>User Preferences</td>
<td>IPreferenceStore</td>
<td>Import/Export</td>
</tr>
<tr>
<td><p>Project Preferences<br>(classpath, compiler settings)</p>
</td>
<td>Plugin specific(XML)</td>
<td>File in project (or none)</td>
</tr>
<tr>
<td>Dialog Settings<br>(layout, default field values)</td>
<td>IDialogSettings</td>
<td>none</td>
</tr>
<tr>
<td>View Settings<br>(layout, menu state)</td>
<td>IMemento</td>
<td>none</td>
</tr>
<tr>
<td><p>Workbench Settings<br>(perspectives, working sets)</p>
</td>
<td>IMemento</td>
<td>none</td>
</tr>
<tr>
<td>Plugin Data<br>
(repository lists, launch configuration)</td>
<td><p>Plugin specific (XML)</p>
</td>
<td>Plugin specific (or none)</td>
</tr>
</table>
<p>Except for IMemento, the above mechanisms are really only appropriate for storing
relatively simple values. For more sophisticated data, the plugin developers
are forced to role their own persistence and sharing mechanism. For this reason,
more complex plugin data is often stored directly in the workspace meta data
area in a format chosen by the plugin and is not sharable. Another problem with
this arrangement is that the persistence mechanisms are tied into where the
mechanism is used and not with the types of settings (i.e. local or sharable)
the mechanisms contain.</p>
<h3>Grouping of Settings</h3>
<p>As is indicated by the above table, settings are grouped by the mechanisms
used to persist them. For example, user preferences can be shared because these
preferences are stored using IPreferenceStore and a general import/export mechanism
was built on on top of this. Other sharing mechanisms are plugin specific so
any grouping can not surpass the plugin boundary. This is clearly not ideal
as users may not wish to share all user preferences and they may want to share
configurations for multiple plugins in a single operation.</p>
<p>Better grouping may be possible by considering the scope of a setting. Possible
setting scopes are:</p>
<ul>
<li>setting type (temporary/local/sharable)</li>
<li>resources involved (workspace/project/working set)</li>
<li>feature/plugin/tool (Java, CVS)</li>
<li>working style (accessibility)</li>
</ul>
<p>Perhaps the scope of a setting can be used to give the user control over which
settings are shared.</p>
<h3>How settings are shared</h3>
<p>There are basically two styles of sharing: import/export or shared file.With
import/export, the user explicitly chooses when to export their settings. At
some future time, the user (or another user) explicitly chooses to import the
settings, overriding, at least to some degree, any previous settings. This is
currently how user preferences in Eclipse are shared. One advantage of this
approach is that the user has control over when the export and import take place.
Also, it is straightforward to add capabilities that would allow the user to
limit which settings were included in the import/export operation (although
this is not currently provided in Eclipse). The disadvantage of this approach
is that the user must explicitly indicate when the export or import take place.</p>
<p>The shared file approach involves a file that contains the current settings.
The contents of the file are updated as settings are changed in the workbench.
Conversely, changes to the file made by other sources will be recognized by
the workbench and result in changes in the corresponding settings.This style
of sharing is used in the Java .classpath files. Changes in the classpath of
a project made using JDT will change the contents of the .classpath file and
changes in the .classpath from other sources, such as loading the .classpath
file from a repository, will cause the classpath in the workbench to change
accordingly. The advantage of this approach is that changes in settings can
be easily propagated to other workspaces. The disadvantages are that it can
be difficult to reconcile cases involving conflicting changes (i.e. the file
is changed by two sources at roughly the same time) and all settings in the
file reflect the state of the workspace even if the workspace changes are of
a temporary nature.</p>
<h3>Determining what is shared</h3>
<p>For user preferences, the user can choose when to import or export the preferences
but has no control over which preferences are shared. For plugin or tool specific
data, the plugin/tool can decide if some of its data is sharable (.classpath,
launch configurations). In these cases, the user decides what data is shared
but the granularity of the sharing is determined by the plugin/tool (i.e. the
user can share a launch configuration but cannot choose to share only some of
the settings in the configuration).</p>
<p>A more ideal approach would be for the provider of the setting (plugin/tool)
to indicate the nature of the setting (temporary, local or sharable) and, for
sharable settings, provide a description that would allow a user to decide when
and if the setting should be shared.Such an arrangement gives more control over
how settings are managed. For instance, it would be possible to write a tool
to arrange, share and possibly even modify settings in a configuration file
that could then be used to configure Eclipse.</p>
<h2><a name="scenarios">Scenarios</a></h2>
<p>User settings means different things to different people. Also, there are some
scenarios that, while not technically user settings scenarios, are related in
some way. This section contains the list of known use cases that may be addressed
in 3.0. However, inclusion in this list does not imply that the final solution
will address an included scenario. The purpose here is to know what all the
problems are so an informed decision can be made about which scenarios to address.</p>
<h3><a name="scenario1"></a>Scenario 1: Import/Export of settings from one workspace to another</h3>
<p> A user may wish to persist certain settings so they can be used with other
workspaces. To share settings from one workspace to another, the user performs
an export operation in the source workspace which creates a file containing
the settings. This file can then be imported into another workspace which changes
the settings in the workspace to match those from the imported settings file.</p>
<p>This scenario, in it's simplest form, is what is supported by the Eclipse platform
through it's preference Import/Export facility. However, this operation is really
only adequate for importing preferences into a workspace that is in the same
location as the workspace the preferences were exported from. The reason for
this restriction is that there is no distinction between local and sharable
preferences.</p>
<p>The following is what is needed for a more flexible preference sharing mechanism.</p>
<ul>
<li>A distinction between settings that are local and those that are sharable.</li>
<li>A mechanism by which sharable settings can be defined in terms of other
settings (variables).</li>
<li>A flag to indicate when settings are temporary.</li>
<li> A distinction between settings that are made by the user and those that
are made by another tool in Eclipse.</li>
<li>A mechanism to describe settings so a user can decide what to export or
import.</li>
<li>A mechanism to group settings to give the user a courser granularity for
managing settings when performing the export or import operation.</li>
</ul>
<h3> <a name="scenario2"></a>Scenario 2: Preconfiguration of setting defaults</h3>
<p> An ISV creating a branded product using Eclipse may wish to customize some
settings in their product. For instance, an ISV may wish to customize Java compiler
settings and may even want to include CVS repository locations. A related scenario
can be found in bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37289">37289</a>.</p>
<p>This can be accomplished in Eclipse 2.x by placing a <em>plugin_customization.ini</em>
in the primary feature plug-in. This file is used in the determination of the
default values for preferences. The default value for a preference is determined
by looking in the following places (in the order specified).</p>
<ul>
<li>file specified on the Eclipse command line</li>
<li><em>plugin_customization.ini</em> in the primary feature plug-in</li>
<li><em>preferences.ini</em> file in a plugin</li>
<li>settings made programatically by a plugin</li>
</ul>
<p>Tha is, if a value is assigned to a setting in the <em>plugin_customization.ini</em>
file then it is the defalt, otherwise a value settingin the <em>preferences.ini</em>
of the plugin is used if present. If no setting is there, the default specified
in the code is used.</p>
<p>The contents of the <em>*.ini</em> files can be generated using the export
facility described in <a href="#scenario1">Scenario 1</a> or crafted by hand
as described in various plugin API.These settings must be internationalizable
so each &quot;*.ini&quot; file needs a corresponding &quot;*.properties&quot;
translation file.</p>
<h3><a name="scenario3"></a>Scenario 3: Application related settings</h3>
<p>A plugin may wish to store data in an area that is accessible to and used by
other workspaces associated with the same Eclipse install. Here is a particular
scenario involving the Eclipse Update component:</p>
<blockquote>
<p>Update had a number of problems saving its state (a directory called .config)
in the workspace metadata. We need to take it out and make it independent
from the workspaces (i.e. make it relative to the Eclipse application). A
behavior that would be consistent with our needs would be:</p>
<ol>
<li>We try to save the directory in the eclipse install location first (under
'eclipse' directory). If we succeed, we keep it there.</li>
<li> If the attempt is not successful (e.g. because the install location is
read-only) OR if a shared mode is explicitly requested using the '-shared'
command line argument, we use the following: in the user home location (the
equivalent of System.getProperty(&quot;user.home&quot;)) we create a folder
with some unique name (e.g. Eclipse Settings). Under the folder, we create
a folder with the product unique ID (this ID is obtained from the .eclipseproduct
marker file that every Eclipse product contains). We save our state in the
unique product ID.</li>
</ol>
<p>Although Update can implement this mechanism itself, it sounds like something
that should be general for all the plug-ins that want to save application-specific
state (as opposed to per-workspace).</p>
</blockquote>
<h3> <a name="scenario4" id="scenario4"></a>Scenario 4: Sharing project settings</h3>
<p>It is common for plugins to persist metadata for one or more projects in the
workspace as files within the project. Although not necessarily user settings,
this metadata can still be shared. </p>
<p>Some example of project metadata that is (or could be) persisted in the project
directory are:</p>
<ul>
<li>Project natures and builders: stored in .project XML file in the project
root directory.</li>
<li>Launch configurations: optionally stored in a '&lt;config-name&gt;.launch'
XML file in the content area of an arbitrarily selected project.</li>
<li>Java build path and project references: stored in the .classpath XML file
in the project root directory.</li>
<li>Java compiler options: stored in the workspace metadata area by the JDT
plugin.</li>
<li>Tasks/Bookmarks: stored in the workspace metadata area.</li>
<li>File encodings(new for 3.0): will be associated with project files in some
manner. </li>
</ul>
<p>Any files that are stored within the project directory structure are already
sharable. The .project and .classpath files are often shared with a project
and the *.launch files can also be shared in this way.</p>
<p>There are several complications that arise from this type of sharing:</p>
<ul>
<li>Conflicting changes made to the file by multiple users may be hard to resolve
as the format of the file contents may not be amenable to text compare.</li>
<li>These files may contain local settings that should not be shared. The .project
and .classpath solved this by supporting the use of variables in the settings.</li>
<li>A user may make changes that they want to be local to their workspace or
temporary. This settings will cause the files involved to become outgoing
changes even though the user has no intention to release them to the repository.
Furthermore, if these changes are released, they may not work properly for
other users.</li>
</ul>
<p>Currently, each plugin that wishes to store metadata in a project must implement
their own mechanism from scratch. It would be helpful to provide a core mechanism
for reading and writing the data (most likely in XML) and a common place to
put the data files (such as a project metadata directory). Such a mechanism
would also allow the user to see all the project settings that can be shared
and enable them to decide which ones they would like to share and which ones
they would not.</p>
<p>One of the interesting points about this scenario is that the sharing of settings
occurs in a &quot;live&quot; manner in the sense that the settings in a workspace
may change as a result to the updating of a settings file from the repository.
For instance, if one user releases a change to the .classpath file of a Java
project, the classpath project will change for other users when they load the
change from the repository.</p>
<p>Another interesting point is that there are some project settings that override
workspace settings. An example of this is Java compiler settings. Any setting
made on a project overrides the setting for the workbench. This is related to
<a href="#scenario6">Scenario 6</a>.</p>
<h3> <a name="scenario5" id="scenario5"></a>Scenario 5: Sharing non-project based
settings</h3>
<p>The previous scenario describes how project settings can be shared through
a repository. However, there are some settings that should be shared between
workspaces that are not associated with a project. For example, a user may wish
to have certain settings that are valid regardless of which workspace is used.
Some examples: code templates, editor auto-closing options, file associations
between filetypes and editors. Currently the user must pick a workspace as the
'master', make changes only to that one, export preferences, and import in all
her other workspaces.</p>
<p>Some settings are common for everyone in an organization, so it is a waste
of time to make everyone in the company set them. Also it is a source of tech
support calls if they don't set them right. These settings change slowly over
time, so the initial configuration scenario would not address it. Some examples:
proxy settings, update sites urls, cvs ext connection method variables, team
file content and ignored resources.</p>
<p>In both of the above cases, it seems desirable to be able to both share the
settings and push new settings into the shard space. In the later case, it is
probably also desirable to restrict who can change existing settings.</p>
<h3><a name="scenario6" id="scenario6"></a>Scenario 6: Team Workgroups</h3>
<p>The following scenario was posted to the platform-dev mailing list by Michael
Lipp. </p>
<blockquote>
<p>We have teams working on different projects. Team members may be in different
teams, i.e. may work in different projects (not on a day-by-day basis, but
within a month). Formalisms in the different projects are driven by customer
requests. This means that we have customer specific templates, layout rules
(yes we are not happy about this) and other differences between projects that
must be reflected by the preferences settings within eclipse.</p>
<p>What we need before we can really use eclipse as main IDE is a way to specify
base preferences for each project. It should be possible to specify for each
preference if it may be overridden by a user. Preferences should automatically
be switches when the user toggles between preferences. Team-wide preference
settings should be files checked in to CVS.</p>
</blockquote>
<p>Another way to view this is that each user has their preferred settings while
each project has required settings. Hence, the presence of a setting on a project
would override any setting made by the user.</p>
<h3><a name="scenario7" id="scenario7"></a>Scenario 7: Associating settings with
a mode of operation</h3>
<p> Settings are often connected with the role of a user or the mode of development
the user is in or some other state. It is cumbersome for the user to find every
related preference and change it appropriately. For instance, a user may wish
to change all relevant settings to gain the highest degree of accessibility
and it would be beneficial if they could do this in one click instead of many.
Also, a user may need to change modes often (as in Scenario 6).</p>
<p>There are a couple of ways settings could be associated with modes:</p>
<ul>
<li>A plugin implementer may want to define a mode and assign particular settings
to the mode.</li>
<li>A plugin implement or may wish to associate their settings with modes defined
by other plugins.</li>
<li>A users may wish to associate settings with a particular mode</li>
<li>A user may wish to define a mode and assign settings to it</li>
</ul>
<p> This scenario is complicated by the fact that each mode is not necessarily
mutually exclusive. A user may need high accessibility while performing web
development (which may be a mode with it's own settings). If this is supported,
it is possible that settings from multiple active groups could overlap.</p>
<p>Another consideration is that some modes may have an analog value associated
with them. For instance, a mode for performance may have a slider to pick the
degree of performance the user wants. This analog value may have an effect on
the values of the settings associated with that mode. It may be difficult to
scale settings values in this way. A more reasonable solution may be to have
discrete settings associated with different ranges of the slider.</p>
<h3>Scenario 8: Policy for changing settings</h3>
<p>Some settings may need to be fixed by policy and not changeable. In a large
organization this is helpful to cut down on tech support problems, especially
as less sophisticated users are exposed to Eclipse through RCP applications.
But even for programmers, there are examples such as CVS ext connection method,
C file tabs-vs-spaces setting, or CVS watch/edit setting.</p>
<h2><a name="solution">Towards a Solution</a></h2>
<p>This sections outlines the components of a potential solution for persisting
and sharing user settings. It is purposefully brief as the main goal of this
document is to ensure that all the scenarios are known before a solution is
fully laid out. However, it is included as a starting point for discussing a
solution.</p>
<h3>Unified Settings Storage Mechanism</h3>
<p>The goal of a unified settings storage mechanism in Eclipse would be to allow
plugins to persist any or all of their state information in such a way as to
allow the user (or the workbench) more control over where the settings are stored
on disk and which settings are shared with others.</p>
<p>When persisting the setting, the plugin would specify the following:</p>
<ul>
<li>a unique id consisting of the plugin id and a local name.</li>
<li>the value of the setting.</li>
<li>the scope of the setting: application (<a href="#scenario3">scenario 3</a>),
workspace or a particular project (<a href="#scenario4">scenario 4</a>).</li>
</ul>
<p>The value of a setting could be simple data (as is supported by the current
preferences mechanism in Eclipse today) or could be more complex data. A mechanisms
similar to IMemento and IConfigurationElement could be combined with the preferences
mechanism to simplify the process of persisting more complex data values. Complex
data could be stored as a string in the preferences store (as is done today)
or could be stored in a separate file, potentially as XML.</p>
<p>One interesting aspect of this solution is that it could be retro-fitted under
most of the exiting mechanisms (IPreferenceStore, Preference, IDialogSettings
and IMemento) in a fashion that is transparent to the plugins using these mechanisms.</p>
<h3>Identification of sharable settings</h3>
<p>Given a unified settings store, the task of identifying which settings are
sharable can be accomplished using an XML descriptor file. It seems reasonable
that such a description be done in the plugin.xml of a plugin but it could be
done in a separate xml file if there is a compelling reason. </p>
<p>A setting would have the following information associated with it.</p>
<ul>
<li>id: the id used in the unified settings store</li>
<li>type: local or sharable</li>
<li>label: text that can be shown to the user to identify the setting</li>
<li>description: text that can be shown to the user which describes the setting</li>
</ul>
<p>The label and description would only be required for sharable settings to allow
settings management UI to display information about the settings to the user
to aid in the export/import of settings and the creation of settings groups.</p>
<h3>Grouping settings into modes</h3>
<p>There are two aspects of a settings group: defining the group and adding settings
to the group. These two aspects should be defined separately in order to support
the types of mode creation described in <a href="#scenario7">Scenario 7</a>.
This is important given that the creator of the group cannot be expected to
anticipate all plugins that may have settings that are relevant to the mode
the group represents.</p>
<h3>Change Notification</h3>
<p>A plugin needs to be notified when any of its settings are changed as a result
of a settings import or a settings file update from the repository. The plugin
would respond to the change by obtaining the new value of the setting from the
setting store and adjusting its internal state accordingly. </p>
<h3>Determining the value of a setting</h3>
<p>In this new world of a unified settings store, there are several places where
settings could come from:</p>
<ul>
<li>defaults specified by plugin</li>
<li>install settings (<a href="#scenario2">scenario 2</a>)</li>
<li>application settings (<a href="#scenario3">scenario 3</a>)</li>
<li>user or organizational settings (<a href="#scenario5">scenario 5</a>)</li>
<li>workspace settings (<a href="#scenario1">scenario 1</a>)</li>
<li>group or mode settings (<a href="#scenario7">scenario 7</a>)</li>
<li>project settings (<a href="#scenario4">scenario 4</a>)</li>
</ul>
<p>The above list is in order of more general to more specific and the store could
be traversed in that order to determine the settings to be used in a particular
context. For example, a value assigned to a setting in the install is overridden
by a value assigned to that same setting in the workspace. However, the setting
value determination is complicated by the allowance for overlapping modes. In
this case, the user may need to decide which mode has the highest priority.</p>
<h3>Managing Settings</h3>
<p>The use of a unified setting store makes centralized management of settings
in Eclipse possible. This will make it possible to control and configure where
and how metadata for projects and plugins is stored. Furthermore, this configuration
can be done independently of the plugins that own the settings. </p>
<p>The user will need tools to manage sharable settings. These tools may include:</p>
<ul>
<li>Import/Export of settings</li>
<li>Grouping and mode creation</li>
<li>Configuration of sharing through projects</li>
</ul>
<p>There may be other useful tools as well.This area will be investigated in more
depth as work proceeds in this area.</p>
<p>It may be interesting to allows others to supply implementations for the stores
in various scopes. In some enterprise scenarios for example, application preferences
would be stored on a central server/database. This may also help in controling
sharing in the sense that the store for a particular scope of setting can dictate
whether or not the settings in that scope are shared. </p>
<h3>Security</h3>
<p>The settings information that is stored on disk or shared between users will
not be encoded for security rreasons in any way. It will be up to the plugins
providing the settings to encode them if the information being saved is of a
sensitive nature.</p>
<h3>Java 1.4 Preferences API and OSGI Preferences Service</h3>
<p>It may be possible to make use of APIs that already exist in this area, such
as the Java 1.4 Preferences API or the OSGI Preferences Service. This will definitely
be investigated but will not limit what we do (i.e. if the APIs are not adequate
for the requirements then they will not be used).</p>
<p>It is interesting to note that the Java 1.4 Preferences API separates preferences
into user and system preferences. The system preferences are similar to what
is described in <a href="#scenario3">Scenario 3</a> while the user preferences
are similar to what is described in <a href="#scenario5">Scenario 5</a>. However,
absent from the API is the concept of project preferences (<a href="#scenario4">Scenario
4</a>) and other possible scopes mentioned in this document. </p>
<p>Another factor to consider is that, with the Java API, it is up to the programmer
to choose where a preference lives (system vs. user). In some cases, this makes
sense but may not always be desirable.</p>
<p>Finally, the only method of sharing provided with the Java 1.4 preferences
is import/export as described in <a href="#scenario1">Scenario 1</a>. That is
not to say that addition methods could not be defined.</p>
<h2><a name="next">What Next</a></h2>
<p>This document captures the known use cases for user settings persistence and
sharing and outlines a promising solution. The scenarios will be adjusted based
on feedback from the community and the solution description will be further
modified and refined based on this feedback.</p>