Eclipse Project Release Notes

Release 2.1.2
October 31, 2003

This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative. 

1. Target Operating Environments
2. Compatibility with Previous Releases
3. Known Issues
4. Running Eclipse
5. Upgrading a Workspace from a Previous Release
6. Interoperability with Previous Releases
7. Defects Fixed in Maintenance Releases

1. Target Operating Environments

Most of the Eclipse SDK is "pure" Java code and has no direct dependence on the underlying operating system. The chief dependence is therefore on the Java 2 Platform itself. Like the 2.0 release, the 2.1 release of the Eclipse Project is written and compiled against version 1.3 of the Java 2 Platform APIs, and targeted to run on either version 1.3 or 1.4 of the Java 2 Runtime Environment, Standard Edition.

Eclipse SDK 2.1 has been tested and validated on the following Java 2 Platform implementations:

The following table describes the combinations of operating system and Java 2 Platform used when testing the Eclipse SDK configurations. The status column indicates the level of testing: "Primary" means a full tested configuration; "Secondary" means a configuration which is only lightly tested; "Untested" means a configuration that has received no testing, but which should work. Note that the Mac OS X configuration is considered early access for the 2.1 release; it has been tested, but is not product quality in this release.

Internationalization

The Eclipse Platform is designed as the basis for internationalized products. The user interface elements provided by the Eclipse SDK components, including dialogs and error messages, are externalized. The English strings are provided as the default resource bundles.

Latin-1 locales are supported by the Eclipse SDK on all of the above operating environments; DBCS locales are supported by the Eclipse SDK on the Windows, GTK, and Motif window systems; BIDI locales are supported by the Eclipse SDK only on Windows operating environments.

The Eclipse SDK supports GB 18030, the new Chinese code page standard, on Windows 2000 and XP, and Linux. Note, however, that GB 18030 also requires locale and character encoding support from the Java 2 Runtime Environment; this support is standard in version 1.4, and also available in some 1.3 JREs.

German and Japanese locales have been tested.

BIDI support

The Eclipse SDK is a development environment targeted at technical professionals - not an end user application. However, the Eclipse SDK tools will permit technical professionals who are working in English to build Hebrew/Arabic end user Java programs which are themselves not based on the Eclipse SDK. The BIDI support in the Eclipse SDK allows a Java programmer to work with BIDI strings, code comments, etc. but the Eclipse SDK itself is not designed to be localized for BIDI locales and its widget orientation cannot be changed.

IMPORTANT: The above BIDI support is available only for Windows operating environments.

2. Compatibility with Previous Releases

Compatibility of Release 2.1 with 2.0

API Contract Compatibility: Eclipse SDK 2.1 is upwards contract-compatible with Eclipse SDK 2.0 except as noted in the next section. This means that programs in full compliance with contracts specified in Eclipse SDK 2.0 APIs is automatically in full compliance with Eclipse SDK 2.1 APIs. (API is construed broadly to include such things as plug-in extension points.) Downward contract compatibility is not supported. There is no guarantee that compliance with Eclipse SDK 2.1 APIs ensures compliance with Eclipse SDK 2.0 APIs. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain contract compatibility.

Binary (plug-in) Compatibility: Eclipse SDK 2.1 is upwards binary-compatible with Eclipse SDK 2.0 except as noted in the next section. This means that plug-ins built for Eclipse SDK 2.0 will continue to work correctly in Eclipse SDK 2.1 without change. Downward plug-in compatibility is not supported. Plug-ins for Eclipse SDK 2.1 are unlikely to be usable in Eclipse SDK 2.0. Plug-ins with hard-coded references in their plug-in manifest file to 2.0 versions of prerequisite Eclipse Project plug-ins will work in 2.1 provided the version match rule is "greaterOrEqual" or "compatible" (the default); references using "perfect" or "equivalent" match rules will be broken. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain binary compatibility.

Source Compatibility: Eclipse SDK 2.1 is upwards source-compatible with Eclipse SDK 2.0 except as noted in the next section. This means that source files written to use Eclipse SDK 2.0 APIs can be successfully compiled and run against Eclipse SDK 2.1 APIs. Since source incompatibilities are easy to deal with, maintaining source compatibility is considered much less important than maintaining contract and binary compatibility. Downward source compatibility is not supported. If source files use new Eclipse SDK APIs, they will not be usable with an earlier version of Eclipse SDK.

Workspace Compatibility: Eclipse SDK 2.1 is upwards workspace-compatible with Eclipse SDK 2.0 except as noted in the next section. This means that workspaces and projects created with Eclipse SDK 2.0 can be successfully opened by Eclipse SDK 2.1 and upgraded to a 2.1 workspace.  This includes both hidden metadata, which is localized to a particular workspace, as well as metadata files found within a workspace project (e.g., the .project file), which may propagate between workspaces via file copying or team repositories. Individual plug-ins developed for Eclipse SDK 2.1 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; 2.1 plug-in developers are responsible for ensuring that their plug-ins recognize both 2.1 and 2.0 metadata and process it appropriately. User interface session state may be discarded when a workspace is upgraded. Downward workspace compatibility is not supported. A workspace created (or opened) by Eclipse SDK 2.1 will be unusable with an earlier version of Eclipse SDK. Visible metadata files created (or overwritten) by Eclipse SDK 2.1 will generally be unusable with earlier versions of Eclipse SDK. 

Non-compliant usage of API's: All non-API methods and classes, and certainly everything in a package with "internal" in its name, are considered implementation details which may vary between operating environment and are subject to change without notice. Client plug-ins that directly depend on anything other than what is specified in the Eclipse SDK API are inherently unsupportable and receive no guarantees about compatibility within a single release much less with earlier releases. Refer to How to Use the Eclipse API for information about how to write compliant plug-ins.

2.1 Incompatibilities between release 2.1 and 2.0

Eclipse 2.1 breaks compatibility with Eclipse 2.0 in the following areas.

Note: Bug numbers refer to the Eclipse project bug database at http://dev.eclipse.org/bugs/

Platform - Core

Linked resources

Eclipse 2.1 allows a project in the workspace to bring together contents from several different directories on disk using what are termed linked folders and files. The presence of linked resources changes a fundamental assumption true for earlier versions of Eclipse, namely, that all of a project's files are located under the project's root directory in the local file system. Furthermore, the target of a linked resource is allowed to overlap that of another linked resource, or overlap the root directory of any project. This new potential for overlap means that several distinct files in the workspace might map to the same file in the local file system. In 2.0, there was no way for overlap to happen (project root directories are not allowed to overlap).

These changes have several ramifications at the API:

• IResource.getLocation can return null in more cases than before.
• IWorkspaceRoot.getContainerForLocation and getFileForLocation are no longer sufficient to map from file system path to workspace path in the presence of linked resources, as these calls do not account for linked files or files under linked folders. Two new methods were added to handle the possibility of overlap: IWorkspaceRoot.findContainersForLocation and findFilesForLocation.

Since linked resources and their children appear in the workspace as normal files and folders, client code that works exclusively with the workspace resource tree is not affected. The clients most likely to be impacted are ones that assume that all of a project's files are located together in the local file system under the project's root directory. For example, an export utility that works directly on the local file system might miss some of a project's files if it only looks within the project's root directory.

This change was made to give certain kinds of users greater flexibility in laying out their projects on disk. The behavior of existing plug-ins is unchanged from 2.0 for projects that do not use linked resources. Depending on the assumptions made, existing plug-ins might misbehave or fail for projects containing linked resources. A plug-in can prohibit linked resources for a project via a project nature (IProjectNatureDescriptor.isLinkingAllowed()), but this should only be done where there is a good reason to deny the user this additional flexibility in laying out a project. Users can disable linked resources via the Workbench > Linked Resources preference page. (bug 6664)

Project build order

The default order in which projects get built was changed in Eclipse 2.1 to improve the handling of mutually-dependent projects. The old method IWorkspace.computePrerequisiteOrder was deprecated and replaced by IWorkspace.computeProjectOrder. Since there are few potential clients of either method beyond the Eclipse Platform itself, it's unlikely that clients will be affected. (bugs 10262, 25952)

Platform - UI

Restructuring of UI plug-ins

In Eclipse 2.1, the API and code for the org.eclipse.ui plug-in was partitioned and parceled out to several new plug-ins (org.eclipse.jface, org.eclipse.text, and org.eclipse.ui.workbench, etc.). Although this looks on the surface to be a breaking change, it is not. These new plug-ins are internal and should not be referenced explicitly. As they always have, plug-ins requiring the Eclipse Platform UI (API found in the org.eclipse.swt.*, org.eclipse.jface.*, and org.eclipse.ui.* packages) should continue to state a dependency on the org.eclipse.ui plug-in.

Platform - Help

Pluggable app server

Eclipse 2.0 provided interim support for pluggable app servers via an undocumented org.eclipse.help.app-server extension point, with interim APIs in the org.eclipse.help package. For 2.1, this support has been made internal, along with the former interim API classes. Because this support was marked as interim for 2.0, this is not considered a breaking API change. Nevertheless, existing clients using the interim support will be broken. Even though the mechanism is not officially supported, clients that are adamant about plugging in a different app server can do so (with all the usual risks of depending on unsupported Eclipse internals).

Pluggable web browser

Eclipse 2.0 provided interim support for pluggable web browsers via the org.eclipse.help.ui.browser extension point, with API in the org.eclipse.help.ui.browser package. For 2.1, this support appears in finished form in different location: the org.eclipse.help.browser extension point, with API in the org.eclipse.help.browser package. Because this support was marked as interim for 2.0, this is not considered a breaking API change. Nevertheless, existing clients using the interim support will need to update the extension point and package names.

Platform - Team

There are some new restrictions that repository providers should be aware of when implementing validateSave/Edit. The first is that the hook can be invoked from a non-UI thread. The provider should use Display.syncExec() if they are affecting any UI components. Also, the hook should not display a progress monitor because there is a good possibility that there already is one open for the operation being performed; opening another will cause deadlock. (bug 33471)

The new support for linked folders and files added in Eclipse 2.1 impacts repository providers because it changes some of the rules about relationships between files in the workspace and their corresponding locations in the local file system. All existing repository providers should be updated to handle linked resources, as described in the 2.1 Team API. If a project is shared via an older 2.0 repository provider, the user will be prohibited from creating linked resources in that project. (bug 26469)

Platform - SWT

Character field in key event

The specification of the Event.character field now makes it clear that the character reflects the outcome after any modifier keys are taken into account (for example, CTRL+A is reduced to the ASCII equivalent character with integer value 1). Since the treatment of modifier keys was completely unspecified before, this change affects clients that make assumptions about how modifiers are handled. (bug 33592)

New key modifier: command

In order to properly support the Mac for Eclipse 2.1, a new SWT.COMMAND key modifier constant was added to represent the Apple command key. On the Mac, the command key plays the same role as the control key plays elsewhere, whereas the control key is used mainly as an additional mouse click modifier. Clients that merely want to check for the appropriate primary modifier for the OS should instead use the new bit mask SWT.MOD1 in favor of either SWT.CONTROL or SWT.COMMAND. The advent of the Mac port of Eclipse affects existing clients that explicitly check for the SWT.CONTROL modifier. In most cases, they should instead check for SWT.MOD1 so that they work appropriately on both Macs and non-Macs. (bug 24393)

OLE variant type exceptions

An SWTError exception is now thrown when a Java type is requested from an empty variant type (VT_EMPTY). Since existing clients should already be handling SWTError exceptions as per the spec for Variant.getInt(), etc., this change should not affect existing clients. (bug 24402)

Multiple drag and drop adapters

An SWTError exception is now thrown if you create a second DragSource (or DropTarget) for a widget. Across various window systems, the results of creating multiple drag source or drop target objects were at best indeterminate. The exception makes it clear that this is not supported. Since existing clients should already be handling SWTError exceptions as per the spec for the DragSource and DropTarget constructors, this change should not impact existing clients. (bug 35214)

Platform - Install/Update

None.

Platform - Ant

None.

Platform - Debug

None.

Platform - Search

Inexact matching

There is a new preference setting that controls whether the search engine should report inexact matches. The user can set this via the Workbench > Search preference page. The new API method SearchUI.arePotentialMatchesIgnored should be used to query the preference setting. Existing clients that contribute a particular search engine (or search page) should consider whether the notion of an inexact match is meaningful in their particular context, and honor this preference if it is. (bug 20663)

Platform - Text

File encoding preserved

FileDocumentProvider now saves a file in the encoding it has been read rather than in the workbench's default encoding.

Key binding scopes

Clients should be aware of key binding scopes, which were introduced in 2.1. TextEditor sets "org.eclipse.ui.textEditorScope" as its key binding scope. Subclasses inherit this setting if they do not override "initializeKeybindingScopes". AbstractTextEditor does not set any key binding scopes; it leaves this to its subclasses.

Action definition ids are mandatory

All actions registered with an instance of AbstractTextEditor should have an action definition id. Otherwise they will not be accessible via accelerators.

Deprecated API

The following class, methods, and constants have been deprecated. The Javadoc indicates what should be used instead.

• Package org.eclipse.ui.texteditor
  • Field AbstractTextEditor.PREFERENCE_FONT
• Package org.eclipse.jface.text.source
  • Constructor AnnotationBarHoverManager(ISourceViewer, IVerticalRuler, IAnnotationHover, IInformationControlCreator)
• Package org.eclipse.jface.text.rules
  • Constructor DefaultDamagerRepairer(ITokenScanner, TextAttribute)
• Package org.eclipse.jface.text.information
  • Method IInformationProvider.getInformation(ITextViewer, IRegion)
• Package org.eclipse.ui.texteditor
  • Constructor IncrementalFindAction(ResourceBundle, String, IWorkbenchWindow, boolean)
  • Constructor MarkerRulerAction(ResourceBundle, String, IVerticalRuler, ITextEditor, String, boolean)
  • Method MarkerRulerAction.getVerticalRuler()
  • Constructor SelectMarkerRulerAction(ResourceBundle, String, IVerticalRuler, ITextEditor)

Platform - Compare

None.

JDT - Core

Multiple output folders

In Eclipse 2.0, all generated class files (and copied resource files) for a Java project get written to the project's single output folder. As of 2.1, the generated class files (and copied resource files) can be partitioned across several output folders, with each source build path entry specifying which output folder its generated files get written to. This change was made to give certain kinds of users greater flexibility in laying out their Java projects on disk. Clients used to be able to assume that a Java project's output files were in the project's output folder (IProject.getOutputLocation()); now they need to take into account the possibility of other output locations (IClasspathEntry.getOutputLocation()!=null). Existing code appears to work fine until the user exercises the additional flexibility. This change is most likely to affect client code that deploys code directly from the project's output folder (e.g., creates a JAR; launches a Java VM with the output folder on the runtime class path). (bug 24123)

Source folder exclusion patterns

In Eclipse 2.0, all Java source files under a source folder on a project's build class path were compiled and included in the Java model. The notion of exclusion patterns were added in 2.1 to give certain kinds of users greater flexibility in laying out their Java projects on disk  Exclusion patterns associated with a source entry on the build class path (IClasspathEntry.getExclusionPatterns()) cause matching files or subdirectories to be ignored for the purposes of compilation and inclusion in the Java model. Most existing clients traverse the Java model and will continue to work fine. However, clients that directly traverse the corresponding source folder in the local file system need to take into account the possibility that some of the files found there may have been excluded with this new mechanism. (bug 22039)

Code formatter positions

The specification for ICodeFormatter.format was changed to specify that the positions array passed in must be in non-decreasing order. The implementation had always been making this assumption, and there would have been serious performance consequences to specify the method as working with unordered positions. Existing clients are unlikely to be affected. (bug 30417)

Leading comments on AST Statement nodes

Statement.getLeadingComment and setLeadingComment have been deprecated because they were not a particularly good way to deal with the general issue of comments and significant whitespace. Since the implementations of AST.parseCompilationUnit never set the leading comment for any AST nodes they create, the change is moot for most clients. (bug 29176)

Empty array passed to Java model operation

In Eclipse 2.0, certain Java model API operations (IJavaModel.delete, copy, move, and rename) threw an ArrayIndexOutOfBoundsException if passed an empty array. The behavior in this case was completely unspecified. For 2.1, the specification and implementation of these operations have been changed to throw JavaModelException in such cases. Clients need to be aware that the empty array case does indeed trigger an exception. (bug 32219)

Non-Java projects included in Java model 

In Eclipse 2.0, non-Java projects and closed projects were excluded from the Java model. In 2.1, non-Java projects and closed projects are available from the Java model via IJavaModel.getNonJavaResources. Their inclusion in the Java model means that they appear in Java model deltas, under IJavaElementDelta.getResourceDeltas. This change may affect clients that listen for Java element deltas (via JavaCore.addElementChangedListener) if they make overly strong assumptions about triggering conditions and contents. (bug 29274)

Java element changed events for full working copy lifecycle

In Eclipse 2.0, Java element changed events were reported for changes to shared working copies, but not when they were created or destroyed. In 2.1, Java element changed events are uniformly issued for the full lifecycle of working copies and apply equally to non-shared as well as shared working copies. This change may affect clients that listen for Java element deltas (via JavaCore.addElementChangedListener) if they make overly strong assumptions about triggering conditions and contents. (bug 32981)

IJavaProject.isOnClasspath

For Eclipse 2.1, the API predicate IJavaProject.isOnClasspath (both forms) was changed to do the more standard thing of returning false rather than throwing JavaModelException in some cases. While this change is within the original spirit of the original API  contract, it breaks source compatibility because JavaModelException is a checked exception; code that invokes this method and catches JavaModelException may need to be rewritten. (bug 33754)

JDT - UI

None.

PDE

None.

3. Known Issues

3.1 Platform
     3.1.1 Core
     3.1.2 Ant
     3.1.3 Help
     3.1.4 UI
     3.1.5 Text
     3.1.6 SWT
     3.1.7 Team
     3.1.8 Install/Update
     3.1.9 Debug
     3.1.10 Compare
3.2 Java Development Tools (JDT)
3.3 Plug-in Development Environment (PDE)
3.4 Other
     3.4.1 FTP and WebDAV support

Note: Bug numbers refer to the Eclipse project bug database at http://dev.eclipse.org/bugs/

3.1 Platform

Missing translations for certain OS dialogs (Linux GTK only)

OS dialogs for selecting files or folders are only partially translated on GTK 2.0.6 or GTK 2.2. These dialogs and the untranslated messages come from GTK, not from Eclipse. This is a known bug in GTK. (bug 38248)

DBCS support on Linux GTK (Linux GTK only)

The versions of GTK included with RedHat Linux 8.0 and SuSE Linux 8.1 that we tested support Latin-1 locales but not DBCS. The DBCS support in GTK 2.2 should be sufficient, and in principle Eclipse should work on any recent Linux with GTK 2.2. We have verified that Eclipse DBCS support works with RedHat Linux 8.0 and GTK 2.2. However, we were unable to get Eclipse working with SuSE Linux 8.1 and and GTK 2.2, so this remains an open issue.

Using different versions of GTK (Linux GTK only)

Users who download and compile new versions of GTK, for example to gain DBCS support in GTK 2.2.0 on RedHat 8.0, will need to ensure that the correct GTK libraries are listed in the LD_LIBRARY_PATH environment variable. By default, the compiled GTK libraries are put in /user/local/lib/, so the following would need to be executed prior to launching Eclipse (Note: this must be done for every new terminal session):

export LD_LIBRARY_PATH=/usr/local/lib/

Problems in Korean translation on GTK 2.2.0 (Linux GTK only)

Users who download and compile new versions of GTK, for example to gain DBCS support in GTK 2.2.0 on RedHat 8.0, will encounter the following problems using the Korean translation. Some of the text font may get clipped at the top, or windows may resize out of the viewable area. To circumvent this problem, we recommend setting a high screen resolution, for example 1280x1024, and setting the Dialog Font and Banner Font to a gothic font. The latter can be done in the Workbench > Fonts preference page. In addition, in the Properties view, the expand/collapse control ("+"/"-") has no effect. The workaround is to use the arrow keys instead: Left Arrow to collapse, Right Arrow to expand. (bugs 38604 and 38598).

Eclipse process does not exit (HP-UX only)

On HP-UX, the HP JVM process that runs the Eclipse Workbench does not terminate upon closing the workbench. The remedy is to always pass the -XdoCloseWithReadPending to the VM via the Eclipse launcher command line; that is, launch Eclipse with the command line:

eclipse -vmargs -XdoCloseWithReadPending

(bug 18321)

3.1.1 Platform - Core

Declaring package name prefixes improves plug-in class loading speed

A significant (10-15%) speed increase in the time to load a plug-in's classes can be obtained simply by declaring the package name prefixes found in that plug-in's runtime library JARs. This is done in the new Package Prefixes section of the Runtime page in the PDE plug-in manifest editor. (Further information here.)

Invalid characters in install directory prevents Eclipse from starting

Eclipse will fail to launch if installed in a directory whose path contains certain invalid characters, including :%#<>"!. The workaround is to install Eclipse in a directory whose path does not contain invalid characters. (bugs 3109 and 17281)

Problems with classloaders in created threads

There is a known issue with trying to load classes from a newly-created thread using a class loader different from the plug-in class loader. The result will be a ClassNotFoundException. As a workaround, do the following:

1. Create a thread in which to run your code.
2. Send yourThread.setContextClassLoader(yourClassLoader); // you can find your classloader by grabbing a class it loaded (YourPluginClass.class.getClassLoader())
3. Run your code in the newly created thread.

If you set the context class loader for the current thread, you are competing with other users of the thread (all of Eclipse), so the results will be unpredictable. However, there should be no problem in practice provided you reset the context class loader back to its original value when your use in the current thread is complete. (bug 8907)

Deadlock creating executable extension in Plugin.startup

If Plugin.startup code is too complex and performs tasks such as creating an executable extension, a deadlock situation can be created. Only simple bookkeeping tasks should be performed in Plugin.startup code. (bugs 12827, 5875, 16141)

3.1.2 Platform - Ant

Xerces JARs no longer required on runtime Ant classpath

Explicitly adding the Xerces JARs to the runtime Ant classpath is no longer required and can cause problems. The Xerces classes are loaded from the org.apache.xerces plug-in provided with Eclipse. For most Ant distributions, the Xerces JARs cannot even be in the same physical location as the ant.jar and optional.jar. This results from the Ant JARs containing manifest files which contain classpath entries pointing to the Xerces JARs. (bugs 33664, 33117, 34151)

Custom Ant tasks and Ant types must be separate from plug-in library JARs

Including the class files for custom Ant tasks or Ant types in the regular code JAR for your plug-in causes problems. These class files must be provided in a separate JAR that is contributed to the org.eclipse.ant.core.antTasks or antTypes extension point (and not declared as a library in the plug-in's manifest). This ensures that the Ant tasks and types are loaded by the special Ant class loader and not by a plug-in classloader. (bug 34466).

Concurrent Ant builds not supported

Eclipse runs Ant in the same JVM as the rest of Eclipse. Several aspects of Ant and its use of global Java resources (such as System.out and System.err), make it unsafe to run more than one Ant build concurrently. (bug 24129).

Running certain Ant tasks cause memory leakage

Certain Ant tasks are known to leak memory. Please see the bug report for details, patches, and possible workarounds. (bug 24448)

Tasks that require input lock up workspace

As with using Ant from the command line, prompts for input from the console is not handled. This is not the same as making use of the <input> task, which works correctly within Eclipse. (bug 21748)

Ant Editor code completion based on Ant 1.5

Code completion provided by the Ant editor does not respect the user-specified version of org.eclipse.ant.core plug-in or ANT_HOME. Code completion proposals are always based on Ant 1.5. (bug 30886).

3.1.3 Platform - Help

Help documents not displayed in a browser or very slow document loading (Windows only)

1. In the Control Panel, open Internet Options, select the Connections tab and choose LAN Settings.
2. If your host was configured to use DHCP for IP assignment, make sure that the "Automatically detect settings" check box is cleared.
3. If you use a proxy server, ensure that the "Bypass proxy server for local addresses" is selected.
4. In "Advanced" settings for proxies, add "127.0.0.1;localhost" to the "Exceptions" if these addresses are not listed.
5. If you are using an automatic configuration script for proxy settings, and are not sure that the script is correct, clear the "Use automatic configuration script" check box.

If the above steps do not fix your problem, try changing the port and host properties on the Help > Help Server preference page. In general, setting host to localhost or 127.0.0.1 should work. Also, especially when running a firewall, you may want to specify port 80 or some other firewall-friendly value. (bugs 7036, 9418, 11394)

Working disconnected from the network (Windows only)

Using Internet Explorer in offline mode (Windows only)

Help topics not highlighted in High Contrast mode (Windows only)

Windows High Contrast settings are not consistently picked up by Internet Explorer when they are set from the Accessibility Options utility as opposed to when they are set using the predefined schemes. On Windows XP, it is recommended to set High Contrast as follows: Right click the desktop, chose properties, select Windows Classic style from the Windows and buttons drop down on the Appearance tab, and choose your scheme (for example High Contrast Black) from Color Scheme drop down. (bug 28609)

3.1.4 Platform - UI

Minimum display resolution

A number of dialogs in Eclipse, such as the Preferences dialog, require a minimum display resolution of at least 1024 x 768.

Manual refresh required when files modified outside Eclipse

When files within a project are added or removed outside of Eclipse, or when an external editor is used to modify a file within a project, a manual refresh must be done in order for the changes to show up in the Workbench. To do this, select the project in the Navigator view and choose Refresh from the pop-up menu. This refreshes only the selected project. Alternatively, activate the Navigator view and press F5, which refreshes all projects.

Default text file encoding may be detected incorrectly (Windows XP/2000 only)

The "Text file encoding" value displayed in the Preferences dialog under "Editors" may be wrong on platforms running Windows XP (or 2000) when the user locale and system locale differ. 

Example of the manifestation of the bug: A Japanese user using Japanese Windows 2000 works in New York, United States. The user has selected English (United States) as the user locale. The "Text file encoding" value displayed by Eclipse is incorrect: "Cp1252" (English). It should display the system locale "MS932" (Japanese).

Workaround: The user can modify the user locale so that user locale and system locale are identical. In the example above, this means the user should set Japanese as the user locale. Then restart Eclipse. The "Text file encoding" value will then be correct: "MS932" (Japanese).

For Windows XP:

• To check the system locale: Open the Control Panel. Go to Regional and Language Options. Switch to the Advanced tab. The system locale is specified in "Language for non-Unicode programs".
• To change the user locale: Open the Control Panel. Go to Regional and Language Options. The user locale can be modified by changing the language in "Standards and formats".

For Windows 2000:

• To check the system locale: Open the Control Panel. Go to Regional Options. Look up the items in the General tab, inside the "Language settings for the system" group. The system locale is the item marked as (Default).
• To change the user locale: Open the Control Panel. Go to Regional Options. The user locale can be modified by changing the location in "Settings for the current user".

(bug 20641)

KDE takes Ctrl+Fn keys

When using the KDE desktop on Linux systems, the Ctrl+Fn key sequences are used for switching between virtual desktops. This means that Eclipse commands bound to these key sequences do not get activated, including Ctrl+F1 (Help), Ctrl+F4 (File > Close) and Ctrl+F6 (Next Editor).

These keys can be reassigned in KDE using the Control Center. Choose Look & Feel > Shortcuts > Shortcut Sequences > Shortcut Sequences > System > Desktop Switching, and set all items to None or to a different key sequence such as Ctrl+Alt+Fn. The other alternative is to assign different key sequences in Eclipse using the Workbench > Keys preference page. (bug 26361)

JAWS screen reader does not read Eclipse dialog boxes properly

There is a known problem with the JAWS screen reader (up to version 4.5) whereby its "Read Box in Tab Order" command (Ins+B) does not read all controls in Eclipse dialogs. (bug 18518)

Dirty state not tracked properly for OLE documents (Windows only)

The dirty state for an OLE document is not updated properly. This causes Eclipse to prompt to save the contents of the editor when the document is closed, even if the contents have already been saved. (bug 2564)

OLE document crashes can cause Eclipse to also crash (Windows only)

If an OLE document crashes, Eclipse can crash, or the workbench menus can become inconsistent.

3.1.5 Platform - Text

Overwrite mode cannot be disabled for AbstractTextEditor and subclasses

When removing the key binding for the "Toggle Overwrite Mode" command on the Workbench > Keys preference page, the mode is still toggled when pressing the "Insert" key. The mode indication in the editor's status line is then out of sync with the actual mode. (bug 35248)

3.1.6 Platform - SWT

Printing and drag and drop not available on Mac (Mac OS X Carbon only)

The Mac OS X Carbon implementation of SWT does not yet support printing or drag and drop. (bugs 33637, 30104)

Unable to drag data between applications in simplified Chinese locale (Motif only)

When configured for the simplified Chinese locale, it is not possible to drag data between applications running on the Motif window system. This is a known limitation of the Open Motif library. (bug 29777)

Hang opening font or color dialogs (Mac OS X Carbon only)

When running with J2SE 1.4.1 for Mac OS X, opening a font or color dialog can hang Eclipse. This is a bug in Apple's J2SE 1.4.1 involving Cocoa-based dialogs. Note that J2SE 1.3.1 for Mac OS X does not have this problem. (bug 30021)

Crash when attempting to launch file browser (AIX Motif only)

There is a known AIX graphics bug affecting certain levels of AIX releases. Ensure that the AIX install includes the necessary service updates as described in the "Install notes/requirements for Eclipse on AIX" attachment to the Eclipse bug report. (bug 34524)

Available colors on 8-bit Linux (Linux only)

Typically, in Gnome Linux installs running with 8-bit visuals (i.e. 256 color mode), before the Eclipse application is started there are no free colors. This may mean that Eclipse is unable to allocate the default widget background color, causing it to display a white background. The functionality, however, is otherwise unaffected.

List and ComboBox on Windows NT (Windows NT only)

On Windows NT only, you should avoid creating items in a List or ComboBox with strings longer than 1000 characters. Doing so may result in a General Protection Fault. This has been fixed in more recent versions of Windows.

Excessive CPU consumption  (Linux GTK only)

When using Linux GTK 2.2.1, there are some scenarios where the CPU usage goes to 100% for no good reason. When this occurs, resizing or closing the dialog seems to return the CPU usage to normal. (bug 35443)

IME-related crash (Linux Motif only)

When using Linux Motif and GB18030 IME "chinput", Eclipse can crash if the IME client window is left open when the parent window is disposed. (bug 32045)

Problems with Japanese IME (Linux Motif only)

On Linux Motif, the Japanese IME Wnn7 Personal is not working properly with Eclipse: the pre-edit text does not appear in the text widget, making it unusable. The IME that we tested - Kinput2 on the client + Canna on the server side (default IME in RedHat 8.0) - works fine. (bug 31754)

BiDi and DBCS support (Windows only)

On Windows XP and Windows 2000, if StyledText determines that it is running on a BiDi platform, characters from DBCS languages (e.g., Japanese) and complex script languages (e.g., Thai) will not render properly. A platform is considered BiDi if a BiDi language is installed and if a BiDi input locale is installed (e.g., a Hebrew keyboard layout is specified). (bugs 25691)

Cursor constructor arguments

In the constructor Cursor(Device device, ImageData source, ImageData mask, int hotspotX, int hotspotY), when both a source and mask argument are specified (that is, the mask is not null), the meaning of the two arguments is reversed. That is, the "mask" argument should be the source image and the "source" argument should be the mask image. (bug 4809)

Using IBM J9 VM (Photon and AIX)

On QNX Photon and IBM AIX, the SWT library will not be found when running with an IBM J9 1.5 VM. This is a bug in the IBM J9 class library in version 1.5. You can workaround this problem by adding the SWT library directory to your LD_LIBRARY_PATH environment variable.

Missing permissions for SWT native libraries in workspace (HP-UX only)

When retrieving the SWT Motif fragment into an Eclipse workspace, the permissions of the native libraries are reset. This creates a problem on HP-UX because shared libraries need to have execute permission. Attempting to self-host with this fragment throws an UnsatisfiedLinkError...Permission Denied error. You must manually change the permissions to make these libraries accessible (assume the workspace is at /workspace):

cd /workspace/org.eclipse.swt.motif/os/hpux/PA_RISC
chmod 555 *.sl

(bug 20305 describes a related problem)

JAWS requires MSAA for List Views to read checkboxes in Tables (Windows only)

In order for JAWS to detect the checkbox information in Tables, MSAA support for List Views must be activated as follows:

1. Open Eclipse and hit INSERT + F2.
2. In the Run JAWS Manager dialog select Configuration Manager.
3. In the Jaws Configuration Manager that opens up, select Set Options and then select Advanced Options.
4. Check "Rely on MSAA for List views".
5. Hit the OK button.
6. Choose File > Save from the menu bar.

3.1.7 Platform - Team - CVS

The following are known problems with the CVS repository provider only, and do not apply to other repository providers. Additional information on how to use CVS from Eclipse can be found in the Eclipse CVS FAQ.

Incompatible with CVS server version 1.11.7 or later

Due to unanticipated changes in CVS version 1.11.7, Eclipse only works with CVS server versions 1.11.1p1 through 1.11.6. Eclipse parses the messages returned from the CVS server. The format of these messages changed abruptly with the recent CVS server version 1.11.7, rendering the current parser ineffective. (bug 45138)

Cached authorization information lost when workspace is upgraded

The Platform's internal authorization database file format has changed for 2.1. Because of this, authorization information cached with a workspace created with an earlier version of Eclipse will be unusable, and the user will need to reauthenticate. (bug 32899)

"extssh" is not a supported command line method

Since the "extssh" connection method is not a supported command line method, you cannot use the command line tool when a project uses this method. Instead, use the Eclipse supported "ext" method and set the appropriate environment variables so that the command line tool will work. (bug 7943)

Connection cannot be found after initially missing

If a connection initially fails due to a network problem, the connection may continue to fail even when the network problem is fixed. In order to establish the connection you must exit and restart Eclipse. (bug 9295)

CVS meta-folders appear in some cases

There are some cases where CVS folders are not hidden from the UI as the user would expect. For instance, CVS folders will appear if a user imports a CVS project into Eclipse before the CVS plug-in is loaded. To avoid this, open the CVS Repositories view (thus loading the CVS plug-in) before importing CVS projects into Eclipse. (bug 21128)

"Received broken pipe signal" error from server

Eclipse sometimes performs multiple commands within a single connection to the server. This may cause problems with CVS servers that are running server scripts in response to certain commands. (bugs 23575 and 23581)

"Terminated with fatal signal 10" error from server

There is a bug in the CVS server related to some compression levels. If you get this error, changing the compression level on the CVS preference page may help. (bug 15724)

"Unknown response" error using ext connection method

There are a few situations that can result in an "Unknown response" error messages when using the ext connection method. One situation involves using an external communications client (e.g. rsh or ssh) that adds CRs to the communications channel (bug 21180). Another involves Eclipse not properly reading the stderr output of the external communications tool (bug 11633).

No way to update folder excluding subfolders

There is currently no way in Eclipse to run a non-recursive update on a folder (i.e., there is nothing equivalent to the cvs -l option). (bug 33210).

3.1.8 Platform - Install/Update

Update manager claims that a cycle has been detected in a multiple path case

When a feature includes other features, it is an error to have multiple paths from the parent to any of its children (there must be exactly one path from the root to any of the included features). Update manager reports the error but is not capable of differentiating cycles (when a child includes a parent) and multiple paths. Consequently, it will claim that there is a cycle in both cases. (bug 26808)

Bundled e-fixes that patch the same feature can clash

When patches (e-fixes) are created by bundling (including) several patches, care must be taken that they do not carry different versions of the same feature. If they do, both features may end up disabled. (bug 31407)

Update manager does not support https protocol

Update manager currently cannot open connections to the remote update sites if the provided URL has https protocol. (bug 31979)

Internal Error in Update Manager while installing/updating when features include the same plug-in

If two or more features in the feature tree formed by inclusion have the same plug-in entry, install or update will fail. This happens because update manager attempts to install the same plug-in more than once and fails to rename files since they already exist. To work around this problem, ensure that no two features in the single feature hierarchy (starting from the root feature) reference the same plug-in (have a plug-in entry with the same id and version). (bug 33937)

Non-responsive sites may use all free threads

Prior to Eclipse 2.1, if the connection to an update site did not respond (the site did not exist or was down), the workbench became non-responsive until the connection request timed out. In 2.1, connections are made by a separate thread so that the UI stays responsive. Typically, unresponsive connections eventually time out and these threads terminate. In rare cases, servers accept the connection but never send a response, thereby keeping the connection thread live indefinitely. Update manager limits the number of active connection threads and will refuse to create more once the limit is reached. To work around the problem, exit and restart Eclipse. (bugs 18598, 19775)

URL validity checking on input

URL syntax is currently not completely checked on input. Ensure that the entered URL uses forward  slash ('/') separators and does not contain invalid characters. (bugs 19685, 20247)

Running "headless" applications that do not handle restart

When install changes are detected, the changes are automatically processed and the workbench restarts. The executable launcher supplied with the application correctly handles the restart. However, if you have applications that directly call the platform (eg. by calling the BootLoader APIs) and do not handle restart, the startup reconciliation processing can be suppressed by specifying -noupdate command line option. In this case, the application will start with the set of features and plug-ins that were processed and configured on the previous start. If prior configuration cannot be found, the application will start with the full set of plug-ins found in the installation location.

Link file entry with trailing blanks is invalid

If a link file used to connect product extensions with products contains an entry with trailing blank characters, it will be considered invalid. The workaround is to ensure that the entry ends with an end-of-line character (bug 22993).

Enabling two versions of the same feature

Care should be taken when enabling and disabling multiple versions of the same feature. If they include other features and the inclusion is set with a match attribute that is not "perfect", disabling old feature version may have a consequence of disabling new children. To avoid this situation, disable the new version first, then enable the old one; i.e., never have two versions of the same feature simultaneously enabled (bug 25236).

Upgrading very old workspaces

If you upgrade to 2.1 from a pre-2.0 workspace that existed prior to the introduction of features, the next time you add a feature you will be prompted on startup with a dialog asking which features to install. If you de-select all features and click OK, then all features are disabled. This prevents you from ever using that workspace again (since the Eclipse Platform feature is disabled). The solution is to delete the .config subdirectory in the workspace's metadata area and then restart Eclipse. (bug 35703)

3.1.9 Platform - Debug

None. (Known problems with the Java debugger appear below in the JDT section.)

3.1.10 Platform - Compare

None.

3.2 Java Development Tools (JDT)

Running Java programs with non-Latin-1 characters in package or class names

Cannot run or debug class in a project with GB18030 characters in project name

Most class libraries do not properly support the creation of a system process (via java.lang.Runtime.exec(...)) when the specified command line contains GB18030 characters. This limitation means the debugger cannot launch applications when the command line it generates contains GB18030 characters. (bug 32206)

Unable to debug stack overflows

If a debug session suspends on a java.lang.StackOverflowError exception (due to an exception breakpoint), the debugger may not be able to retrieve any debug information from the target JVM. As well, the debugger may not be able to reliably interact with the target JVM past this point. (bug 19217)

Evaluation limitation

The debugger uses threads in the target JVM to perform evaluations (both explicit evaluations that the user requests, and implicit evaluations such as toString() invocations in the Variables view). The Java Debug Interface (JDI) requires that the thread in which an evaluation is performed be suspended by a user event (that is, a breakpoint or step request). Evaluations cannot be performed on threads suspended by the suspend action. As well, when a breakpoint is configured to suspend the JVM rather than just the individual thread, the threads which did not encounter the breakpoint are not in a valid state to perform an evaluation. When an evaluation is attempted in a thread that is not in a valid state to perform an evaluation, an error message will appear to the effect of "Thread must be suspended by step or breakpoint to perform method invocation". (bug 34440)

Breakpoints outside of the build class path

Breakpoints can only be created on Java elements that are contained on the build class path of a project. The Java debugger automatically deletes breakpoints if their associated Java element is removed from the build path of a project. However, if the Java debug plug-in is not loaded when a build path is changed, such breakpoints will remain in the workspace, and can cause errors when the user attempts to go to the file associated with the breakpoint, from the Breakpoints view. (bug 34845)

Missing debug attributes

Setting breakpoints

Using Hot Code Replace

Note that hot code replace and stepping on JDK 1.4.0 VMs was unreliable. The underlying VM problems were fixed in JDK 1.4.1.

Scrapbook

When a snippet is run in the scrapbook which directly or indirectly calls System.exit(int), the evaluation cannot be completed, and will result in a stack trace for a com.sun.jdi.VMDisconnectedException being displayed in the scrapbook editor.

Terminating a scrapbook page while it is performing an evaluation results in a com.sun.jdi.VMDisconnectedException being displayed in the scrapbook editor.

Debugging over slow connections

Updating of inspected values

Stepping over native methods that perform I/O

VM and process termination running on IBM 1.3 JVM on Linux (Linux only)

Searching for constant field references

Quick fix and imports from default packages

Quick fix does not handle imports from default packages. Note that importing from a default package is no longer supported in JDK 1.4 (bug 19487)

Javadoc hover in the Java editor

The Javadoc hover help shown when hovering over identifiers in the Java editor does not handle links inside of Javadoc comments properly. (bug 20644)

Cut, copy, paste not working for linked resources in views showing Java elements

The cut, copy, and paste actions do not work for linked files and folders appearing in views that show Java elements, including the Package Explorer. The workaround is to use these actions from the Navigator view instead. (bug 34568)

Java working sets not working correctly for elements from JRE system library container

Appling a working set consisting entirely of elements from the JRE System library container as a filter to the packages view might result in an empty Package Explorer. (bug 35395)

Cannot generate Javadoc for packages with GB18030 characters in the name

Most class libraries do not properly support the creation of a system process (via java.lang.Runtime.exec(...)) when the specified command line contains GB18030 characters. Since Javadoc is created using the Javadoc executable provided with the JDK, generating Javadoc fails if the package or class name contains GB18030 characters. (bug 32215)

Linked editing does not work correctly in overwrite mode

Linked editing is used for renaming elements within a single compilation unit and for templates with multiple occurrences of the same template variable. Linked editing does not work correctly in overwrite mode. (bug 35216)

Catch block code generation template must end with newline if last line is line comment

If the last line of the catch block code generation template is a line comment then the line must be terminated with a newline. Otherwise the closing curly bracket ends up on the comment line, resulting in a compilation error. (bug 35746)

Problem opening class file editor

If the "Use classpath containers" preference has been enabled on the Plug-in Development > Java Build Path Control preference page, you may not be able to open a class file editor for a class file contained in a JAR in the "Required plug-in entries" container. One way to work around the problem is to expand the class file in the Packages Explorer; this displays the class file's structure just as the editor would. If a source code zip is available for the JAR, another option is to attach source to the JAR file.

To attach source to a JAR in the "Required plug-in entries" container, follow these steps:

1. In the Package Explorer, select the project and open Project > Properties from the context menu
2. Select the Java Build Path page
3. Flip to the Libraries page
4. Expand the "Required plug-in entries" item
5. Expand the item for the JAR
6. Select "Source Attachment" and press Edit
7. Enter the location of the corresponding source zip
8. OK to acknowledge

(bug 35769)

3.3 Plug-in Development Environment (PDE)

PDE source page colors do not take effect on Apply

Changes to the colors PDE uses for source pages of its multi-page editors are not immediately visible in opened editors after pressing the Apply button on  the Plug-in Development > Editors preference page. To work around this problem, close the editor and and reopen it. (bug 33640)

Icons folder not included in bin.includes of some PDE templates

PDE provides a number of templates that can be used to create fully functioning plug-in projects and/or extensions. When projects are created, the build.properties file is created with the initial content, which includes the property 'bin.includes' listing the plug-in manifest and its code JARs. However, it omits mention of other files created by the template, such as the icons/ folder. As a request, these extra files do not end up in the plug-in when built using Ant build file or exported using 'Export deployable plug-ins and fragments' wizard. To work around this problem, add these files and directories manually in build.properties file. (bug 35554)

Emacs key bindings do not work in manifest editor fields

Non-default key bindings currently do not work in fields on non-source pages of the PDE manifest editors. (bug 19482)

Comments in source pages of PDE XML editors

PDE provides a number of multi-page editors that include a raw source page. Editors that handle XML files (plug-in, fragment and feature manifests) will preserve comments in most cases. However, comments will not be preserved if added before the root XML element, or if added after the last child element contained in the parent element. (bug 8000)

Plug-in import wizard does not allow plug-ins of different versions to be imported

The Eclipse platform allows two plug-ins with the same ID but different versions to coexist if the only thing they contribute is run-time libraries. However, PDE cannot handle these plug-ins because it creates project names using plug-in IDs during binary project import. (bug 18500)

PDE nature required for plug-in manifest syntax checking

PDE will only be able to provide syntax checking and error/warning markers for plug-in manifests if the plug-in project has the PDE plug-in nature. A plug-in project automatically gets this nature when created by a PDE wizard. This situation can only occur if a regular Java project has been used to host a plug-in. The problem can be fixed by converting it into a PDE project. (bug 19248)

PDE does not preserve original manifest file layout

When non-Source page of a PDE manifest editor is used, PDE will convert changes back into XML by regenerating the file. Although the overall content and the comments are preserved, the actual file layout is not. This may cause problems by showing false changes during file compare. If file layout is important, perform all editing in the Source page. Alternatively, avoid using Source pages altogether. Since XML files are generated in a way that respects and preserves the relative order of major elements (extensions, extension points etc.), changes made in a non-Source page of a PDE manifest editor do not result in false deltas during file compare. (bug 19251)

Go To Line in manifest editor causes Outline view to go blank

When the Source > Go To Line command is invoked in the Source page of a PDE manifest editor, the Outline view will become gray. Since the Source page does not have a functional outline, there is no actual loss of function. (bug 19361)

3.4 Other

3.4.1 FTP and WebDAV support

When mapped to a target, the project folder is ignored

Ignoring the project folder is by design. Normally with target management you put/get the contents of the project, not the actual project. The place you pick in the site explorer is where the project contents will go. This allows your local project to have a different name than the container in the WebDAV/FTP server. If you want to map several projects to the same site location, you create a new folder for each one. This is why "New Folder" is in the mapping page. (bug 17657)

FTP messages cause an exception

With some servers, the FTP client may receive messages that it did not anticipate. These will cause an exception. Trying the operation again usually works. (bug 18108)

FTP problems with spaces in resource names

FTP does not work properly when file or folder name contains spaces. (bug 20220)

FTP problems retrieving remote timestamps with NT server

Problems have occurred with some servers (NT server Serv-U FTP-Server v2.5k ) when trying to obtain the timestamp of a newly uploaded file. This causes a "file does not exist" error. The workaround is to Synchronize again and continue. (bug 19715)

4. Running Eclipse

After installing the Eclipse SDK in a directory, you can start the Workbench by running the Eclipse executable included with the release (you also need a JRE, included with the Eclipse SDK). On Windows, the executable file is called eclipse.exe, and is located in the eclipse subdirectory of the install. If installed at c:\eclipse-SDK-2.1-win32, the executable is c:\eclipse-SDK-2.1-win32\eclipse\eclipse.exe. Note: Set-up on other operating environments is analogous.

If you do not specify otherwise, Eclipse creates a default workspace in a subdirectory as a sibling of the executable (that is, at, c:\eclipse-SDK-2.1-win32\eclipse\workspace). 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 "-data" command line argument; for example, 

eclipse -data c:\myworkspace -vm c:\jdk1.4.1_01\jre\bin\javaw

Tip: It's generally a good idea to explicitly specify which Java VM to use when running Eclipse. This is achieved with the "-vm" command line argument as illustrated above. If you don't use "-vm", Eclipse 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 Eclipse.

To create a Windows shortcut to an installed Eclipse and a particular workspace (e.g., c:\myworkspace):

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 -data option followed by the location of the workspace (e.g., "-data c:\myworkspace").

Opening this shortcut launches Eclipse on the specified workspace. (You can drag the shortcut to the Windows Desktop if you want to keep it in easy reach.)

5. Upgrading Workspace from a Previous Release

If you are upgrading to a newer release of Eclipse from an older release, there are simple steps to follow to migrate your workspace to the new release. Your workspace is the directory on disk that contains all of your project files, as well as metadata such as preferences you may have customized. The steps to follow for upgrading depend on whether or not you used the "-data" command line argument when starting Eclipse. The "-data" argument is recommended because it clearly specifies the location of your workspace. If this argument is not used, Eclipse will place the workspace in the current working directory at the time Eclipse was launched.

Note that if you installed additional features and plug-ins into your older Eclipse, you should re-install them in the new Eclipse prior to upgrading workspaces.

Tip: It doesn't hurt to make a backup copy of your workspace before upgrading. After you've upgraded your workspace, you won't be able to use it again with an older version of Eclipse. If you ever want to go "back in time" to an earlier release, you'll need that backup!

Users who don't use "-data"

If you weren't previously using "-data" to specify your workspace, follow these steps to upgrade:

1. Find the workspace directory used by your old version of Eclipse. Typically this is located inside the directory in which Eclipse was installed in a subdirectory called "workspace". If you are using a shortcut or script to launch Eclipse, then it will be under the current working directory of that shortcut or script in a subdirectory called "workspace". For Windows users, this is specified by the Start in: argument in your shortcut properties.
2. Copy this workspace directory to a new, empty location outside of any Eclipse install directory.
3. Install the new version of Eclipse in a new location, separate from any old version of Eclipse.
4. Start this new version of Eclipse, using the "-data" command line argument to point to the workspace location.
5. Say OK to the Different Workspace Warning dialog to allow the workspace to be upgraded. (Note: this dialog was added in 2.1.1.)

Users who do use "-data"

If you were previously using the "-data" argument to start Eclipse, your upgrade path is much easier:

1. Install the new version of Eclipse in a new location, separate from any old versions of Eclipse.
2. Start this new version of Eclipse, using the "-data" command line argument to point to your old workspace location.
3. Say OK to the Different Workspace Warning dialog to allow the workspace to be upgraded. (Note: this dialog was added in 2.1.1.)

6. Interoperability with Previous Releases

6.1 Interoperability of Release 2.1 and 2.0

Sharing projects between heterogeneous Eclipse 2.0 and 2.1

Special care is required when a project in a team repository is being loaded and operated on by developers using Eclipse-based products based on different feature or plug-in versions. The general problem is that the existence, contents, and interpretation of metadata files in the workspaces may be specific to a particular feature or plug-in version, and differ between versions. The workspace compatibility guarantees only cover cases where all developers upgrade their Eclipse workspaces in lock step. In those cases there should be no problem with shared metadata. However, when some developers are working in Eclipse 2.1 while others are working in Eclipse 2.0, there are no such guarantees. This section provides advice for what to do and to not do. It addresses the specific issues with the Eclipse SDK.

The typical failure mode is noticed by the 2.1 user. 2.1 metadata is lost when a 2.0 user saves changes and then commits the updated metadata files to the repository. Here's how things typically go awry:

• A user working in Eclipse 2.1 creates or modifies a project in a way that results in changes to a shared metadata file that rely on 2.1-specific information. The user then commits the updated project files, including the shared metadata file, to the shared repository.
• Another user working in Eclipse 2.0 shares this project from the same repository. The 2.1-specific information in the shared metadata file is not understood by Eclipse 2.0, and is generally discarded or ignored without warning. The user modifies the project in a way that results in changes to the shared metadata file, causing the shared metadata file to be rewritten without any of the 2.1-specific information. The user commits the updated project files, including the shared metadata file, to the shared repository. The user is generally unaware that shared information has just been lost as a result of their actions.
• A user working in Eclipse 2.1 picks up the changes to a project from the shared repository, including the updated shared metadata file. The user may be unaware that they have just taken a retrograde step until later when things start to malfunction.

Here are a list of things to watch out for when the project is to be shared between users of Eclipses 2.1 and 2.0:

• Linked folders and files
  This support was added in 2.1. Information about linked resources is recorded in the project's .project file. Recommendation: do not use. Better still, disable linked resources via the Workbench > Linked Resources preference page.
• External tool (Ant) builders
  Information about external tool builder is recorded in the project's .project file. The format of the information changed between 2.0 and 2.1. Builders created or changed in 2.1 use the new format, which is not understood by a 2.0 workspace. Builders created in 2.0 use the old format and continue to work in 2.1. Recommendation: Always create or edit external tools builders from a 2.0 workspace.
• Optional exclusion patterns on Java source entries on the build class path
  This support was added in 2.1. This information is recorded in the project's .classpath file. Recommendation: do not specify exclusion patterns.  Better still, disable exclusion patterns via the Java > Compiler > Build Path  preference page.
• Output folders associated with Java source entries on the build class path
  This support was added in 2.1. This information is recorded in the project's .classpath file. Recommendation: do not specify anything other than the default (project-wide) output folder.  Better still, disable multiple output locations via the Java > Compiler > Build Path  preference page.
• Source attachment root path associated with Java library entries on the build class path
  When attaching a source ZIP to a library JAR on the Java build path, the source root path prefix is inferred automatically. This has changed from 2.0, where it could be explicitly set via the UI and explicitly recorded in the project's .classpath file. Consequently, a Java project created in a 2.1 workspace might not find the attached source. Recommendation: Use 2.0 to specify the source attachment root path. There is additional source attachment flexibility provided in 2.1: you can provide a folder instead of a JAR or zip as a source attachment, and you can attach source to a class file folder; this functionality is not available in 2.0 (where the 2.1 information is ignored).  Recommendation: Use 2.0 to specify the source attachment.
• PDE classpath containers for dependent plug-ins
  PDE's use of classpath containers was added in 2.1. Classpath containers are recorded in the project's .classpath file. If PDE classpath containers are used, then a 2.0 workspace will have unresolved classpath entries and therefore most Java capabilities (including compilation, search, run, debug) will not produce the expected results. Recommendation: Ensure that the setting on the Plug-in Development > Java Build Path Control preference page for using classpath containers is disabled before creating any new plug-in (or fragment) projects.

Using Eclipse 2.1 to develop plug-ins that work in Eclipse 2.0

It is also possible (and reasonable) to use Eclipse 2.1 to develop a plug-in intended to work in Eclipse 2.0. Use the Plug-in Development > Target Platform preference page to locate non-workspace plug-ins in an 2.0 Eclipse install. This ensures that the code for your plug-in is being compiled and tested against Eclipse 2.0 APIs, extension points, and plug-ins. (The above list of concerns do not apply since they affect the layout and interpretation of files in the plug-in project but none affect the actual deployed form of the plug-in.)

7. Defects Fixed in Maintenance Releases

7.1 Defects fixed in release 2.1.2 since 2.1.1

Release 2.1.2 is a maintenance release to fix serious defects present in release 2.1.0 and 2.1.1. These changes only affect some plug-ins and features. Modified plug-ins have version id "2.1.2"; plug-ins unchanged since the 2.1 release still have version id "2.1.0"; plug-ins unchanged since the 2.1.1 release still have version id "2.1.1". Note, however, that all features now have version id "2.1.2" (even if none of their plug-ins changed).

Maintenance release 2.1.2 includes all fixes made in 2.1.1 (see next section) and contains additional fixes for the following defects:

Note: the above table was generated with the Bugzilla query: http://bugs.eclipse.org/bugs/buglist.cgi?product=JDT&product=PDE&product=Platform&target_milestone=2.1.2&resolution=FIXED&order=bugs.bug_id

7.2 Defects fixed in release 2.1.1 since 2.1.0

Release 2.1.1 was the first maintenance release to fix serious defects present in release 2.1.0.

Maintenance release 2.1.1 fixes the following defects present in release 2.1.0, all of which are also included in 2.1.2:

Note: the above table was generated with the Bugzilla query: http://bugs.eclipse.org/bugs/buglist.cgi?product=JDT&product=PDE&product=Platform&target_milestone=2.1.1&resolution=FIXED&order=bugs.bug_id

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

IBM is a trademark of International Business Machines Corporation in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Apple and Mac OS are trademarks of Apple Computer, Inc., registered in the U.S. and other countries.

QNX, Neutrino, and Photon are trademarks or registered trademarks of QNX Software Systems Ltd.

Other company, product, and service names may be trademarks or service marks of others.

(c) Copyright IBM Corp. and others 2003