Eclipse Project Release Notes

Release 3.5.1
Last revised April 7, 2010

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 since Previous Release

1. Target Operating Environments

In order to remain current, each Eclipse Project release targets reasonably current 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 Platform itself. Portions are targeted to specific classes of operating environments, requiring their source code to only reference facilities available in particular class libraries (e.g. J2ME Foundation 1.0, J2SE 1.3 and 1.4, etc.).

In general, the 3.5 release of the Eclipse Project is developed on a mix of Java 1.4, Java 5 and Java 6 VMs. As such, the Eclipse SDK as a whole is targeted at all modern, desktop Java VMs. Full functionality is available for 1.4 level development everywhere, and extended development capabilities are made available on the VMs that support them.

Appendix 1 contains a table that indicates the class library level required for each bundle.

There are many different implementations of the Java Platform running atop a variety of operating systems. We focus our testing on a handful of popular combinations of operating system and Java Platform; these are our reference platforms. Eclipse undoubtedly runs fine in many operating environments beyond the reference platforms we test. However, since we do not systematically test them we cannot vouch for them. Problems encountered when running Eclipse on a non-reference platform that cannot be recreated on any reference platform will be given lower priority than problems with running Eclipse on a reference platform.

Eclipse 3.5 is tested and validated on the following reference platforms

As stated above, we expect that Eclipse works fine on other current Java VM and OS versions but we cannot flag these as reference platforms without significant community support for testing them.

Internationalization

The Eclipse SDK 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 and DBCS locales are supported by the Eclipse SDK on all reference platforms; BIDI locales are supported by the Eclipse SDK everywhere but on Motif.

The Eclipse SDK supports GB 18030 (level 1), the Chinese code page standard, on Windows XP and 2000, Linux/GTK and the Macintosh.

German and Japanese locales are tested.

2. Compatibility with Previous Releases

Compatibility of Release 3.5 with 3.4

Eclipse 3.5 is compatible with Eclipse 3.4 (and all earlier 3.x versions).

API Contract Compatibility: Eclipse SDK 3.5 is upwards contract-compatible with Eclipse SDK 3.4 except in those areas noted in the Eclipse 3.5 Plug-in Migration Guide . Programs that use affected APIs and extension points will need to be ported to Eclipse SDK 3.5 APIs. Downward contract compatibility is not supported. There is no guarantee that compliance with Eclipse SDK 3.5 APIs would ensure compliance with Eclipse SDK 3.4 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 3.5 is upwards binary-compatible with Eclipse SDK 3.4 except in those areas noted in the Eclipse 3.5 Plug-in Migration Guide . Downward plug-in compatibility is not supported. Plug-ins developed for Eclipse SDK 3.5 will not be usable in Eclipse SDK 3.4. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain binary compatibility.

Source Compatibility: Eclipse SDK 3.5 is upwards source-compatible with Eclipse SDK 3.4 except in the areas noted in the Eclipse 3.5 Plug-in Migration Guide . This means that source files written to use Eclipse SDK 3.4 APIs might successfully compile and run against Eclipse SDK 3.5 APIs, although this is not guaranteed. Downward source compatibility is not supported. If source files use new Eclipse SDK APIs, they will not be usable with an earlier version of the Eclipse SDK.

Workspace Compatibility: Eclipse SDK 3.5 is upwards workspace-compatible with earlier 3.x versions of the Eclipse SDK unless noted. This means that workspaces and projects created with Eclipse SDK 3.0 to 3.4 can be successfully opened by Eclipse SDK 3.5 and upgraded to a 3.5 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 3.5 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; 3.5 plug-in developers are responsible for ensuring that their plug-ins recognize metadata from earlier versions 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 a product based on Eclipse 3.5 will be unusable with a product based on an earlier version of Eclipse. Visible metadata files created (or overwritten) by Eclipse 3.5 will generally be unusable with earlier versions of Eclipse.

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.

3. Known Issues

3.1 General problems
     3.1.1 Startup
     3.1.2 GCJ
     3.1.3 64-bit Java HotSpot(TM) VM
3.2 Platform
     3.2.1 Core
     3.2.2 Ant
     3.2.3 User Assistance
     3.2.4 UI
     3.2.5 Text
     3.2.6 SWT
     3.2.7 Team and CVS
     3.2.8 Install/Update
     3.2.9 Debug
     3.2.10 Compare
3.3 Java development tools (JDT)
3.4 Plug-in Development Environment (PDE)

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

3.1 General problems

3.1.1 General - Startup

Installation/Configuration issues that can cause Eclipse to fail start

Here are some common problems that can cause Eclipse not to start:

• As shown above, Eclipse 3.5 requires at least a 1.4.2 VM. Perhaps an older version of the VM is being found in your path. To explicitly specify which VM to run with, use the Eclipse -vm command-line argument. (See also the Running Eclipse section below.)
• Running Eclipse on Gentoo Linux may result in the following error message:
  * run-java-tool is not available for sun-jdk-1.6 on i686
  * IMPORTANT: some Java tools are not available on some VMs on some architectures
  If this occurs, start Eclipse by specifying a -vm argument, either specify the path to a java vm or use: eclipse -vm `java-config --java` (bug 176021)
• Eclipse must be installed to a clean directory and not installed over top of a previous installation. If you have done this then please re-install to a new directory. If your workspace is in a child directory of your old installation directory, then see the instructions below on "Upgrading Workspace from a Previous Release".
• Java sometimes has difficulty detecting whether a file system is writable. In particular, the method java.io.File.canWrite() appears to return true in unexpected cases (e.g., using Windows drive sharing where the share is a read-only Samba drive). The Eclipse runtime generally needs a writable configuration area and as a result of this problem, may erroneously detect the current configuration location as writable. The net result is that Eclipse will fail to start and depending on the circumstances, may fail to write a log file with any details. To work around this, we suggest users experiencing this problem set their configuration area explicitly using the -configuration command line argument. (bug 67719)

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)

Hanging during class loading when out of permanent generation memory

The Sun VM may hang indefinitely during class loading if it runs out of permanent generation memory. This will cause CPU usage to stay at 100% until the process is ended. See the section Running Eclipse for details on addressing this VM problem.

3.1.2 General - GCJ

GCJ is an effort by the GCC team to provide an open source Java compiler and runtime environment to interpret Java bytecode. Unfortunately, the GCJ runtime environment is not an environment that is often tested on by Eclipse developers.

The most common problems surrounding GCJ are:

• Eclipse does not start at all
• Eclipse throws a 'java.lang.ClassNotFoundException: org.eclipse.core.runtime.Plugin' that can be found in the logs (located in workspace/.metadata/.log)

The workspace's log file is a good place to check to identify whether GCJ is being used or not. Every Eclipse log session is prepended with information about the runtime environment that was used to run Eclipse. The log may include something like the following:

If Eclipse does start, one can check which runtime environment is being used to run Eclipse by going to Help > About Eclipse SDK > Installation Details > Configuration. The About dialog itself can also provide other information, the build identifier can be of particular interest as it is tagged by some distributions. This allows the user to identify whether Eclipse was downloaded through the distribution's package management system or directly from the eclipse.org website.

The two most common workarounds are:

• download the Eclipse binary from eclipse.org directly
• run Eclipse using an alternate Java runtime environment

To download Eclipse, try one of the links below:

• http://www.eclipse.org/downloads/
• http://download.eclipse.org/eclipse/downloads/

eclipse-SDK-3.5-linux-gtk.tar.gz (32-bit)
eclipse-SDK-3.5-linux-gtk-x86_64.tar.gz (64-bit)

To run Eclipse with an alternate Java runtime environment, the path to the Java virtual machine's binary must be identified. With an Eclipse installation from the distribution, altering the $PATH variable to include the path to the alternate Java runtime environment is often not enough as the Eclipse that Linux distributions package often performs a scan internally to pick up GCJ by itself whilst ignoring what's on the $PATH. An example of the terminal's output is shown below:

Once the path to the virtual machine's binary has been identified, try running Eclipse with the following command:

For an actual example, it might look something like the following:

If this seems to solve the problem, it is likely that the problem really was related to the use of GCJ as the Java runtime for running Eclipse. The eclipse.ini file located within Eclipse's folder can be altered to automatically pass this argument to Eclipse at startup. An example of its content is presented below:

Note that every argument must be on its own line. More information about the eclipse.ini file can be found at http://wiki.eclipse.org/Eclipse.ini.

If problems persists after downloading an installation of Eclipse from eclipse.org and using a supported Java runtime environment (a list of which may be found above), you can seek further assistance through the newsgroups, the IRC channel, and/or bugzilla.

3.1.3 General - 64-bit Java HotSpot(TM) VM

There is a known issue with the Java HotSpot(TM) 1.6.0 VM compiler which causes eclipse to crash (see Sun bug http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6614100, and Eclipse bug 214092). The crash usually occurs within a VM CompilerThread when attempting to compile the method org.eclipse.core.internal.dtree.DataTreeNode.forwardDeltaWith.

This problem has been addressed in Sun Java 6 update 11, so the simplest resolution is to obtain the latest JRE release for your platform. To work around the issue you can exclude the method org.eclipse.core.internal.dtree.DataTreeNode.forwardDeltaWith from being compiled with the following VM argument:

This VM argument can be placed in the eclipse.ini file after the -vmargs line like the following:

There have been reports of other classes that cause the compiler to crash. If all else fails you can disable the compiler with the VM arg "-Xint".

3.2 Platform

3.2.1 Platform - Core

Installing plug-ins by unzipping them into the plugins directory

New plug-ins can be installed into the system by unzipping them into the plugins directory. However this is not recommended, and the dropins directory should be used for this purpose instead. Note that unzipping a different version of a plug-in that is already installed will have no effect. To change the version of a plug-in installed in your system, you need to either perform an update, or install a feature patch.

XML files with UTF-8 byte order mark fail to have content type detected

Eclipse will fail to detect the proper content type for XML files that have a UTF-8 byte order mark if Crimson is the XML parser (as it is on Sun 1.4 JREs, but not on Sun 1.5 JREs). This problem will prevent actions normally available when files of the affected content types are selected from being presented to the user. The workaround is to ensure the default XML parser supports UTF-8 BOMs (such as Xerces does). (bug 67048)

No branding with old config.ini

If you have an old config.ini file and use it with a new Eclipse build, you may not get the correct product branding. This is because the id of the standard Eclipse product changed. Users in shared install scenarios may end up in this situation as previous builds of Eclipse automatically generated config.ini files in some cases. The work around is either to delete the local config.ini or update the eclipse.product line to read eclipse.product=org.eclipse.platform.ide.

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. (bug 5875)

Potential Problems Converting Plug-in Manifests

If your plug-in ships with a plug-in manifest and not an OSGi bundle manifest, is shipped as a JAR file, and contains a nested JAR file then there may be problems in the automatic generation of the bundle manifest file. The packages defined in the nested JAR may not be exported correctly in the Export-packages bundle manifest header. To work around this you should ship your plug-in with a bundle manifest. (bug 97689)

Location for Debug Options File on Mac OS

If you are running in debug mode on Mac OS, the default location for the .options file is inside the application bundle in the Eclipse.app/Contents/MacOS directory (like the eclipse.ini). (bug 88782)

Issues with JNI that use FindClass

There may be issues when using a JNI implementation that uses FindClass in a function where the JNIEnv pointer is not available, such as in a C callback (bug 125250). The reason is that FindClass, in this case, uses the application class loader to find the class. If the desired class is in the classpath used for the application classloader (e.g. defined by the VM argument -cp <classpath>), as it would typically be in a stand-alone application, there is no problem. However, under Eclipse, the application classloader does not have access to classes contained in plug-ins. Eclipse uses its own class loader to find classes contained in plug-ins.

The proper plug-in class loader is used by FindClass in JNI functions which are passed the JNIEnv pointer, but not when you have to use AttachCurrentThread to get the JNIEnv pointer. In this case the application classloader is used.

For example, the following will fail because AttachCurrentThread is used to get the JNIEnv pointer:

static JavaVM* jvm;  // Global variable

void myCallback(void) {
    JNIEnv* env;
    jvm->AttachCurrentThread((void**)&env, NULL);
    // Fails if some/class is not in the application classloader:
    jclass cls = env->FindClass("some/class");
    jmethodID methodID = env->GetMethodID(cls, "methodName",
      "(Ljava/lang/String;)V or whatever signature");
    env->CallVoidMethod(callback, methodID, ...);
    jvm->DetachCurrentThread();
  }
}

A solution is to cache the method ID, for example:

static jmethodID mid;  // Global variable

JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
...
  // Store the JavaVM pointer
    jvm = vm;

  // Find the class and store the method ID
  // Will use the class loader that loaded the JNI library
    jclass cls = env->FindClass(className"some/class");
    if(!cls) goto ERR;

    mid = env->GetMethodID(cls, "methodName",
      "(Ljava/lang/String;)V or whatever signature");
    if(!mid) goto ERR;
...
}

void myCallback(void) {
    JNIEnv* env;
    jvm->AttachCurrentThread((void**)&env, NULL);
    env->CallVoidMethod(callback, mid, ...);
     // Handle error ...
    jvm->DetachCurrentThread();
  }
}

3.2.2 Platform - Ant

UTF-8 encoded buildfiles with Byte Order Mark

UTF-8 encoded buildfiles with byte order marks will fail to be parsed correctly depending on the XML parser being used for the build. Therefore a valid buildfile will fail to build with an error message similar to: "BUILD FAILED: C:\workspace\bom.xml:1: Document root element is missing.". To succeed in building with these files, ensure to include Xerces jars on the Ant runtime classpath so that the Xerces parser is used to parse the XML. As well the context menu for these files in the Navigator or Package Explorer will not have the run shortcuts for Ant builds. (bug 67048)

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 can run 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 in the same JVM. (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)

"version" property is always set when running Ant in the same VM as Eclipse

The Xalan libraries set system properties including a version property. These get set as properties within the Ant build and therefore the "version" property cannot be set within an Ant buildfile due to the immutable nature of Ant properties. This property will always be set to "2.4.1" for Ant builds in the same VM as Eclipse. (bug 45717)

XDoclet support from within Eclipse

Since there are differences when running Ant from the commandline and within Eclipse, some extra steps may be needed to have XDoclet support function correctly within Eclipse. Problems may occur creating XDoclet subtasks. The workarounds and full discussion can be found in bug report. (bug 37070)

Ant Editor code completion based on Ant 1.6.1

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 mostly based on Ant 1.6.1 with some updates to Ant 1.6.5 (bug 30886)

Eclipse can hang due to implementation of the Ant <property> task (Windows 9X only)

On Windows 9X, using:<property environment="env"/> will cause Eclipse to hang if the build occurs in the same VM as Eclipse. Running the build in a separate VM will hang the build but not Eclipse. (bug 44196)

Setting build loggers not supported when debugging Ant builds

When debugging Ant builds within Eclipse, setting -logger as a program argument will be ignored.

Renaming an External Tool builder set to run during auto-build will cause errors

If you rename an existing external tool builder that is configured to run during auto-builds, you will get the following error: Errors during build. Errors running builder "Integrated External Tool Builder" on project <PROJECT_NAME>. The builder launch configuration could not be found. The workaround is to first disable the builder for auto-builds and then rename the builder. (bug 118294)

Slow typing/saving of the Ant editor with imports that define numerous macrodefs

The Ant editor is slow on saving with buildfiles that have <import> declarations of buildfiles that have numerous <macrodef>s. See bugs 92640 and 125117 for possible workarounds

Failure to run Ant builds on non-Windows platforms if Eclipse installed in location with spaces in the path

Due to a bug in Ant 1.7.0, Ant builds will fail with an IllegalArgumentException if the Eclipse installation is in a location with spaces in the path. Embedded usage of Ant builds, such as plug-in export will also fail. See bug 187993 for possible workarounds

3.2.3 Platform - User Assistance

Welcome page not displayed properly (Linux/Unix)

The default Welcome implementation is HTML-based and requires a supported browser in order to work. If no supported browser can be found, Welcome falls back to its Forms-based implementation, which has a different (simpler) appearance. Consult the SWT FAQ for supported browsers and setting up your browser to work with eclipse.

Help browser tool bar buttons do not work for some documents

The Help browser's Print, Synchronize, and Bookmark buttons do not work for pages that are not actually installed with the product. However, you can always use the print command in the browser's context menu to print the page you're reading. (bug 44216)

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)

Help browser displays a blank page

If you see a help launched with a blank page, and no errors displayed, it can be caused by a conflict between libraries in org.eclipse.tomcat plug-in and jars optionally installed in JRE jre/lib/ext directory. To fix the problem, ensure that the JRE used for running Eclipse does not contain any J2EE or Apache jars in the jre/lib/ext directory. (bug 63970)

3.2.4 Platform - UI

High contrast settings

Eclipse was tested for High Contrast using 1152 x 864 resolution in Windows XP High Contrast mode. You can select this mode by selecting Accessibility Options > Display > Use High Contrast from the Windows XP Control Panel menu.

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

Note: the bug report associated with this problem has been fixed. If you run Eclipse with JDK 1.5 or greater you should not have to use the workaround stated below any longer. However, the problem still exists when running Eclipse with JDK 1.4.x or lower, so in this case the workaround is still required .

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)

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.

2.1 Presentation based workspaces incorrectly get new Min/Max behavior

Workspaces that are currently using the Eclipse 2.1 Presentation will incorrectly 'inherit' the new min/max behavior when opened with 3.3.

Workaround:

1. Go to the 'Preferences -> Appearance' page, change the current presentation to 'Default' and select apply
2. Change it back to the 2.1 Presentation, select 'OK' and 'Yes' to the restart prompt

Toolbars only containing contributed controls exhibit display errors on Mac/Linux

Currently there is no way on the Max or Linux platforms to define the height for controls contributed to toolbars, nor will those platforms respect the size returned by the control's computeSize method. If you encounter this issue there is currently no truly viable workaround. (bug 183003)

3.2.5 Platform - Text

3.2.6 Platform - SWT

Eclipse plug-in based on the SWT Browser throws exception

The SWT Browser widget uses a platform-specific web browser to render HTML. The org.eclipse.swt.SWTError exception ("No more handles") is thrown on platforms that don't meet the requirements for running the Browser widget. Supported platforms and prerequisites are listed on the SWT FAQ item "Which platforms support the SWT Browser?".

Opening File Dialog crashes eclipse (Vista only)

On Vista, launching eclipse using -vmargs -Xmx[any size] can crash eclipse when the FileDialog is opened. The workaround is to use the default heap size, i.e. do not use the -Xmx VM args. (bug 188317)

Crash while editing text (Windows XP with SP2 only)

Some users who have installed Service Pack 2 on Windows XP have experienced crashes while using editors in Eclipse. The workaround is to place a working version of Windows\System32\USP10.DLL in the Eclipse startup directory or uninstall Service Pack 2. (bug 56390)

Input Method broken (Motif only)

Some versions of RedHat Linux such as Fedora Core 3 and Enterprise Linux WS release 4 use a new technology called IIIM (Intranet/Internet Input Method Framework) to replace the old XIM (X input method). When running on these new systems, Eclipse will crash if you attempt to enter any DBCS character. The workaround is to use a XIM based input method such as chinput. This problem may be fixed in newer releases of RedHat. (bug 89722)

Eclipse does not start on Linux-Motif with Xinerama and a UTF-8 locale

The Linux-motif build of Eclipse does not launch properly when run on a computer with Xinerama (provides support for dual head monitors) and a UTF-8 locale. The workaround for this problem is to change the locale to a non-UTF-8 value, or to disable Xinerama. (bug 38843)

Eclipse hangs when pasting from an unresponsive application (GTK only)

If the application that is supplying the clipboard material is unresponsive, the paste operation hangs Eclipse for several minutes. This situation can be encountered when copying from an Eclipse target workbench, suspending the target workbench at a breakpoint and pasting into the hosting Eclipse workbench. (bug 44915)

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)

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 Eclipse bug report number 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.

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)

IME conversion problem (Solaris GTK only)

When typing Japanese text, the conversion to Kanji must be done one ideogram at a time. (bug 226636)

gtk_init_check and X11 socket failure when using the IBM 1.4.2 JRE (GTK only)

Under RHEL 3.1 with the IBM 1.4.2 JRE and a large number of plugins, Eclipse may fail to launch with an exception from gtk_init_check along with this error:

_X11TransSocketOpen: socket() failed for local
_X11TransSocketOpenCOTSClient: Unable to open socket for local

A workaround is to set the environment variable JAVA_HIGH_ZIPFDS to a value of 500 before starting Eclipse. (bug 106396)

Key bindings can stop working on Debian (GTK+ only)

On some versions of Debian, Eclipse key bindings may stop working. In this context the only way to make the key bindings work again is to restart Eclipse.

The problem is that a focus issue exists in GTK+ 2.6.7 and earlier, for which SWT has a workaround. This workaround is incompatible with the GTK+ 2.6.7 fix, so a GTK+ version check is done at runtime to determine whether the workaround should be used or not. However, Debian backported the GTK+ focus fix into their libgtk+2.0 (2.6.4-2) package, so the SWT workaround and GTK+ fix are both incorrectly applied in this context.

To work around this problem, either get the Debian unstable version of GTK+, compile your own GTK+, or hack SWT's Shell.gtk_realize(int) and change the version that it checks. See SWT bug 107013 and GTK+ bug 109246 for more information.

Typing in an editor crashes with IBM 1.5 VM (Linux GTK PPC only)

When running on the IBM Java 5.0 VM, Eclipse crashes while the user is typing in an editor. If using this VM you must disable the JIT with the -Xnojit vm argument to avoid the crashes (see bug 116730). The command line for launching Eclipse with this vm should be:
eclipse -vmargs -Dosgi.locking=none -Xnojit

Eclipse won't start (Linux GTK PPC only)

Eclipse fails to create a lock file with reason "No locks available". To launch eclipse you must disable file locking using the osgi.locking property. For example, you could launch eclipse as follows:
eclipse -vmargs -Dosgi.locking=none

SWT for carbon cannot be used with OS X JRE version 1.6 (Mac OSX only)

OS X JRE version 1.6 assumes that pointers have a size of 64 bits, but SWT's Carbon port only uses 32-bit pointers, so SWT and Eclipse cannot be used with OS X JRE version 1.6. The workaround is to use the cocoa version of SWT or an earlier supported version of the OS X JRE.

Strings may be truncated or incorrectly wrapped on RHEL5 (Linux GTK only)

Strings on wrapping Controls may not appear correctly in some locales on RHEL5 as a result of a bug in Pango version 1.14.x. This problem can be fixed by upgrading the installed Pango library to a version that is newer than 1.14.x. (bug 231951)

Block Selection functionality provided by StyledText is not BIDI aware

When the orientation of characters under the left and right edges of the block selection rectangle are not the same, the actual selection ranges (in memory) differ from the visual representation of the selection.(bug 277929)

3.2.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.

CVS server compatibility

The CVS plug-in parses messages returned from the CVS server. If the format of these messages is not as expected, some of the plug-in's functionality may be missing. The CVS plug-in is compatible with all stable 1.11.X builds of the CVS server, and should be compatible with future releases in that stream unless text message formats change (the last tested server was 1.11.22). As for the 1.12.X feature releases of CVS, the Eclipse CVS client has been tested with builds up to 1.12.13. However, future releases could easily break the Eclipse CVS client. Basic functionality, such as Checkout, Commit, and Update, should always work, but there may be problems with more advanced commands such as Synchronizing and Browsing the repository.

SSH2 proxy settings lost upgrading to 3.3

CVS now uses the Platform proxy settings. As a result, any CVS proxy settings will be lost and must be re-entered on the General>Network Connections preference page.

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)

"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)

A disabled CVS capability may not be auto-enabled in existing workspaces

New in 3.0 is the ability to disable capabilities and the CVS support in Eclipse can be disabled. However, for backwards compatibility the CVS capability is auto-enabled in existing workspaces that already contain CVS projects. The auto-enabling function may not run if the team support plugin is not loaded at startup. (bug 66977)

Builder output files may appear as changed

When folders containing build output are shared they may get improperly marked as dirty when build output is generated.

Enabling GNOME proxy support

GNOME applications can make use of proxy settings defined in this environment. If set, Eclipse will use it prior to proxy settings declared using env variables. This feature is disabled by default, to enable it launch Eclipse with "-Dorg.eclipse.core.net.enableGnome" switch. That is,

eclipse -Dorg.eclipse.core.net.enableGnome

3.2.8 Platform - Install/Update

Manually installing features and plug-ins on a FAT file system (Windows only)

When features and plug-ins are manually installed on top of an Eclipse-based product install located on a FAT file system that has already been run at least once, the product must be explicitly restarted with -clean. That is,

eclipse.exe -clean

Connecting to untrusted sites using https

You cannot install or update software from a site using https whose certificate is not chained to a trusted root certificate in your local certificate store. This typically means the server is using a self-signed certificate, or a certificate authenticated by an unknown third party.

Extension location is lost if the install path changes

A previously configured extension location may be temporarily removed if the install is moved or mounted under a different path. This only happens when the link file that configures the extension location uses a relative path that points to a directory under the Eclipse install. On a second startup using the same install path, the extension location is added again (bug 95403).

Feature patches can only be installed from Eclipse 3.4-based update sites

Feature patches can only be installed from update sites designed for Eclipse 3.4 or greater. Specifically, the update site must have the necessary metadata for Equinox p2 (a content.xml or content.jar file). This data can be generated by building an update site using Eclipse 3.4 or newer, or running the p2 metadata generator on an update site built using earlier versions of the Eclipse SDK. See the help topic Generating p2 metadata for more details on running the p2 metadata generator (bug 244483).

3.2.9 Platform - Debug

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

3.2.10 Platform - Compare

None.

3.3 Java development tools (JDT)

Multiple regions formatting in a given source snippet

• org.eclipse.jdt.core.formatter.CodeFormatter#K_SINGLE_LINE_COMMENT
• org.eclipse.jdt.core.formatter.CodeFormatter#K_MULTI_LINE_COMMENT
• org.eclipse.jdt.core.formatter.CodeFormatter#K_JAVA_DOC

Searching for constant field references

Search does not find references to constant fields inside binaries because the Java Language Specification mandates that constant field values be inlined in the class file's byte codes, leaving no trace of a field reference. (bug 12044)

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

Applying 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 30442)

Breakpoints unreliable running Sun 1.6.0_14

Side effects of Step into Selection and Run to Line

The actions "Step into Selection" and "Run to Line" optimistically set breakpoints on the line the user has chosen to step into or run to. However, the debugger can not determine if or when execution will ever reach the chosen line. The breakpoints set by the underlying implementation are not visible to the user and can cause execution to suspend unexpectedly at a later time, when the associated line is actually executed. (bug 51507)

Default locale initialization incorrect

The default locale is generally initialized from the settings in the operating system when a target VM is launched. However, when using javaw.exe on JDK1.4.2, Windows XP, the default locale is incorrectly initialized to en_US, no matter what the operating system settings are. (bug 65945)

Some refactoring script operations fail with Sun 6.0 JREs

Creating and applying refactoring scripts sometimes fails with Sun 6.0 JREs due to a bug in the XML parser that is shipped with those VMs. A workaround is to use a J2SE 5.0 VM or an IBM 6.0 VM. Another workaround is to replace the XML parser using the Java Endorsed Standards Override Mechanism:

1. Get original versions of xml-apis.jar, xercesImpl.jar, xalan.jar, and serializer.jar from Apache, e.g. xalan-j_2_7_1-bin.zip from here.
2. Unpack the archive and copy the 4 JARs into <path-to-your-JavaSE6.0-install>\jre\lib\endorsed\.

Suspend on uncaught exception overrides exception breakpoint location filters

Exception breakpoints can be configured with location filters (inclusive and exclusive). When an unchecked exception is configured to not suspend execution in a specific class, execution will still suspend when the user preference to suspend on uncaught exceptions is on. (bug 66770)

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)

Cannot detect installed JRE with GB18030 characters in path name

Automatic JRE detection fails when the JRE is stored in a directory containing GB18030 characters in its name. (bug 33844)

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)

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)

Missing debug attributes

Using Hot Code Replace

Hot code replace is supported on JDK 1.4.x VMs, and IBM J9 VMs. The debugger will attempt to replace all class files that change in the workspace as the user edits and builds source code. However, hot code replace is limited to changes that a particular virtual machine implementation supports. For example, changes within existing methods may be supported, but the addition or removal of members may not be.

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, and later.

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)

Memory View (Linux only)

Java 6 and MacOS

Java Annotation Processing

Some methods in the processing API are unimplemented when compiling within the IDE, and will throw UnsupportedOperationException.

Java 6 annotation processors are supported in the batch compiler and in the IDE. By design, Java 6 processors are only executed during a build, not while editing (bug 188558).

Java 5 annotation processors are supported in the IDE only. Java 5 processors can be executed while editing, as well as during a build. Slow annotation processors can cause a slowdown of the editing experience. If this occurs, you may wish to turn off Enable processing in editor on the Java Compiler > Annotation Processing properties page of your Java project.

3.4 Plug-in Development Environment (PDE)

Feature manifest editor does not preserve all comments

When a non-source page of the feature manifest editor is used, PDE will convert changes back into XML by regenerating the file. Although the overall content and most of the comments are preserved, some comments may be lost. (bug 59502)

PDE will not unzip source zips of some plug-ins

In the plug-in import wizard, when you choose to import plug-ins as "projects with source folders", PDE will not unzip the source for the org.apache.ant, org.eclipse.core.runtime.compatibility.registry, org.eclipse.osgi.util and org.eclipse.osgi.services. This is because the source ZIPs contains code that will not compile when unzipped as it requires additional JARs that are not part of the SDK. To avoid the creation of plug-in projects that won't compile, PDE will import these plug-ins as binary and attach source, so you would still be able to read the source, you just won't be able to modify it. Also, PDE will not unzip the source for the org.eclipse.swt plug-ins. In this case, it is because, when shipped, the swt code is spread across a plug-in and a fragment, and when unzipped, it will require circular dependencies between the plug-in and fragment projects. These circular dependencies are at minimum marked as warnings by the JDT compiler and may result in unpredictable build behavior. Therefore, PDE always imports org.eclipse.swt as binary with source attached. (bug 66314)

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)

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)

Export of plug-in may silently drop classes

When exporting a plug-in using the plug-in, feature or product wizards, some classes might be dropped from the resulting archive if their fully qualified name is too long. This typical path limitation can be worked around by creating the jar of the problematic plug-in by using the Jar export wizard. (bug 97150)

Compilation errors when exporting projects not stored outside of the workspace

When exporting multiple plug-ins and one is stored outside of the workspace, compile errors occurs on export. To work around the problem, you can either export the plug-ins one by one, or change their location. (bug 98579)

Headless build needs to be run from a fully qualified path

When running a headless build using the scripts provided by pde build, the properties builder and buildDirectory must refer to a fully qualified path. (bug 139554)

Target Platform only sees installed plug-ins

With the new p2 provisioning system in 3.4, PDE introduced a preference to control how target platforms are built. By default, this preference is on if your target equals your host, otherwise it's off. When this preference is enabled, PDE attempts to read a target platform's configuration and build the target platform based in the target's list of installed plug-ins. If a configuration can't be found (a bundles.info or platform.xml file), PDE will simply manually scan the target directory and populate the target platform's list of plug-ins. (bug 226037 and bug 225148)

Delta pack is not seen by PDE when installed

If you're using the delta pack, the target platform preference for building a target based on the target's installed plug-ins must be checked off. This is because a target's runtime configuration only contains plug-ins specific to the platform it's running on. (bug 230146)

The org.osgi.util.tracker package is exported at wrong version

The Equinox OSGI Framework (org.eclipse.osgi) exports the org.osgi.util.tracker package at the incorrect version of 1.4.2. The correct org.osgi.util.tracker package version for the OSGi Release 4 Version 4.2 specification is version 1.4.0. Bundles that wish to run on other vendor frameworks should import the org.osgi.util.tracker package at version 1.4.0. By default PDE will suggest the version 1.4.2 to be used when a bundle imports the org.osgi.util.tracker package (using Import-Package manifest header). Developers can manually change the import to use 1.4.0 version of the package to be able to run on both Equinox and other vendor frameworks. (bug 279622)

Importing plug-ins as source misses resources

When importing plug-ins as source (from associated binary plug-ins and source bundles), resources such as property files and images will not be imported into the workspace. The workaround is to retrieve projects from their associated CVS repository or import binary plug-ins with attached source (if the ability to edit the imported plug-ins is not required). (bug 280259)

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 1.4.2 JRE, not included with the Eclipse SDK). On Windows, the executable file is called eclipse.exe, and is located in the eclipse sub-directory of the install. If installed at c:\eclipse-SDK-3.5-win32, the executable is c:\eclipse-SDK-3.5-win32\eclipse\eclipse.exe. Note: Set-up on most other operating environments is analogous. Special instructions for Mac OS X are listed below.

Allocating enough memory and solving OutOfMemoryErrors

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

eclipse -vmargs -Xmx<memory size>

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

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

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

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

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

Selecting a workspace

When the Workbench is launched, the first thing you see is a dialog that allows you to select where the workspace will be located. The workspace is the directory where your work will be stored. If you do not specify otherwise, Eclipse creates the workspace in your user directory. This workspace directory is used as the default content area for your projects as well as for holding any required metadata. For shared or multi-workspace installs you must explicitly specify the location for your workspace using the dialog (or via the "-data" command line argument).

Specifying the Java virtual machine

Here is a typical Eclipse command line: 

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

Tip: It's generally a good idea to explicitly specify which Java VM to use when running 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:

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

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

Mac OS X

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

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

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

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

Shared Install

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

5. Upgrading Workspace from a Previous Release

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 sub-directory 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 sub-directory 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. If you had installed additional features and plug-ins into your old Eclipse, you should re-install them in the new Eclipse.
5. Start this new version of Eclipse and select this location using the workspace chooser dialog at startup (or use "-data" command line argument to pre-select the workspace location).

Users who do use "-data"

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

1. Optionally copy your workspace directory to a new, empty location outside of any Eclipse install directory as a backup.
2. Install the new version of Eclipse in a new location, separate from any old versions of Eclipse.
3. If you had installed additional features and plug-ins into your old Eclipse, you should re-install them in the new Eclipse.
4. Start this new version of Eclipse and select this location using the workspace chooser dialog at startup (or use "-data" command line argument to pre-select the workspace location).

Note: Copying your workspace is recommended because, 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 will need that backup.

6. Interoperability with Previous Releases

6.1 Interoperability of Release 3.5 with previous releases

Sharing projects between heterogeneous Eclipse 3.5 and 3.4

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 3.5 while others are working in Eclipse 3.4, there are no such guarantees. This section provides advice for what to do and not to do. It addresses the specific issues with the Eclipse SDK.

The typical failure mode is noticed by the 3.5 user. 3.5 metadata is lost when a 3.4 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 3.5 creates or modifies a project in a way that results in changes to a shared metadata file that rely on 3.5-specific information. The user then commits the updated project files, including the shared metadata file, to the shared repository.
• Another user working in Eclipse 3.4 shares this project from the same repository. The 3.5-specific information in the shared metadata file is not understood by Eclipse 3.4, 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 3.5-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 3.5 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 some things to watch out for when sharing projects between Eclipse 3.5 and earlier 3.x releases:

• Linked resources in the .project file - Eclipse 3.5 supports creating linked resources at arbitrary depth within a project, and supports creating linked resources referring to other file systems. Neither of these scenarios are supported in Eclipse 3.1 or earlier. If such linked resources are created in 3.5, and the project is subsequently loaded into an Eclipse 3.1 or earlier workspace, these links will not be recognized. Recommendation: avoid creating links at arbitrary depth or to other file systems where project compatibility with Eclipse 3.1 or earlier is required.

Using Eclipse 3.5 to develop plug-ins that work in Eclipse 3.4

It is also possible (and reasonable) to use Eclipse 3.5 to develop a plug-in intended to work in Eclipse 3.4 or earlier. Use the Plug-in Development > Target Platform preference page to locate non-workspace plug-ins in an Eclipse 3.4 install. This ensures that the code for your plug-in is being compiled and tested against Eclipse 3.4 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 3.5.1 since 3.5.0

Release 3.5.1 is a maintenance release to fix serious defects present in release 3.5.0 These changes only affect some plug-ins and features.

Maintenance release 3.5.1 contains fixes for the following defects and others:

Note: Bug fixes since the 3.4.2 release can be obtained by the following the Bugzilla query:

Bugs fixed in the 3.5.1 release

ID	Summary
77217	[browser] Support the Browser widget on Solaris SPARC
195183	[launching] JavaClassPath.performApply() uses original instead of working copy causes NPE
196308	[formatter] Don't escape entity when formatting in <pre> tags within javadoc comments
209333	[Trim] [Trim] NPE in IWorkbenchPage.setPartState(IWorkbenchPartReference, IWorkbenchPage.STATE_RESTORED);
214807	[browser] xulrunner 1.9 has changed invalid certificate behaviour
216901	[Import/Export] Eclipse not responsive when export to archive a lot of projects
226595	[Help] Help index cannot handle multiple files with same ID
234872	[relengtool] The "Fix copyrights" tool should not add rem statements that echo to the console
235526 [SEC]	[security] No prompt for installing unsigned content
235572	[relengtool] "Fix copyrights" doesnt detect existing Copyright in Windows .bat files
254738	NPE in HierarchyResolver.setFocusType
256942	Using file_prompt for Ant script produces confusing results
259946	[ui][engine] p2 not cleaning up large .profile file
260968	Deadlock in UserLibraryManager
262791	Compilation slow when APT is enabled
263702	Branch creation problem in CVS
264182	[Linked Resources] If .project file edit fails, linked resource shows up anyway under certain conditions.
267046	SourceMapper infinite loop on primitive type in generic
268789	[OLE] Cannot create in-place editor for Microsoft Word documents in Windows Vista
269172	[Contributions] WorkbenchMenuService calling Display.syncExec() on disposed Display
270229	[p2agent] Provisioning not working with proxy (workaround)
271703	Cannot print from 64 bit eclipse
272850	[Webapp] TOC expand too slow for when there are 3000+ sub topics
273112	[Markers] Use 'bottom up' heap sort to optimize the Markers view
273385	[model] NPE while closing project
273495	[ActionSets] Actionsets leak when opening/closing perspectives
273619	[formatter] Formatting repeats *} in javadoc
274898	[recovery] IllegalArgumentException in ASTNode#setSourceRange()
275330	NPE from org.eclipse.jdt.internal.core.ClasspathChange.requestIndexing
275589	can't see text cursor after setting dark background color
276110	Label: SWT.CENTER is being ignored when used with SWT.WRAP
276111	[JUnit] classpath container doesn't pick up JUnit jars in shared installations
276162	[KeyBindings] Exporting key preferences to CSV does not warn of overwriting file
276202	[Forms] NPE if dispose() called on FormToolkit more than once
276313	[ICU] consume updated Collator version
276319	Huge regression on BuilderPerformanceTest#testManualBuildWithAutobuildOn() test
276373	Incorrect resource comparison with IJavaProject.isOnClasspath(IResource)
276938	Remove unreachable removes reachable logic in case statement.
276969	[Help] HelpView does not create itself correctly in a multi window session that has been restarted, dynamic context help is disabled
277064	[launcher] RCP app crashes on SplashHandler takedown
277120	[CommonNavigator] Project explorer does not reveal elements when linked to editor
277204	IAE in SharedASTProvider for generic local class.
277303	[clean up] Add ISV doc for the clean up extension point
277315	Combo does not accept drag and drop
277356	[cocoa] npe in Tree widget
277450	[1.5][compiler] Problems with += and Autoboxing/Unboxing
277489	VM arg are wrong for the agent download
277547	[eclipse] StringIndexOutOfBoundException when setLauncherName is passed an empty string
277567	Path.close() method on results in different behavior on Cocoa
277783	Http service should not use 8859_1 alias on S60
277926	[Commands] Command is not invoked when focus changes.
277965	[compiler] NPE in canBeSeenBy due to illegal protected toplevel class
278305	[1.5][compiler] JDT accepts supertype parameterized with wildcard
278311	[DataBinding] INativePropertyListener methods should document that source may be null
278370	[Mozilla] DOM is unavailable in completed event listener after setText()
278376	NPE in Shell.WM_ENTERIDLE
278550	[Databinding] ObservablesManager, ObservableTracker and MapSimpleValueObservableMap lead to exception
278562	[1.5][compiler] Generated code results in VerifyError
278734	[ActivityMgmt] WorkbenchActivityHelper restrictArray is returning NULL for objects failing the test "restrictUseOf(Object)"
278745	Methods overloaded with unavailable types worked in 3.4 but give "indirectly referenced.." error in 3.5
278781	Launching eclipse application fails when a vm arg in eclipse.ini contains a space
278801	Export wizards have missing mnemonics
278814	[composite] Relative child repository locations not working
278933	[Workbench] FileNotFoundException in test log makes it particularly unreadable
278943	[Cocoa] Incorrect colors while copying an image
278944	Cocoa: Image transfer not working for images (randomly)
279013	SWT: crash when calling setParent() on Linux
279103	[Cocoa] SelectionChanged events behaviour broken
279169	[category def] Category help link brings up wrong help contents
279183	[1.6][compiler] Inconsistent stackmap frames generated by JDT cause VerifyError
279278	Add mac carbon x86 to build.properties in rcp.config builder
279295	[ip] imports servlet 2.2
279313	TreeItem.removeAll incorrectly implemented on Mac platform
279314	Typo in p2_metadata_generator.html
279326	[Help] Infinite loop possible in Toc
279425	[organize imports] MultiElementListSelectionDialog has wrong button layout
279509	BrowserInformationControl leaks TextLayout
279514	[Metadata] UI bundles should depend on SWT 3.5, not 3.4
279524	API compare for jar in PDE classpath container
279552	NPE running API use scan
279611	[nls tooling] Add 'Find Broken NLS Strings' to Tips & Tricks
279622	The framework exports tracker package at 1.4.2 but should be 1.4.0
279671	Preferences - PathEditor and DirectoryFieldEditor do not show all disk content on Mac OS X
279697	ArrayIndexOutOfBoundsException running use scan
279715	[inline] Inline Constant and Inline Local Variable are missing parentheses for extended '-' chains
279836	[1.5][compiler] Eclipse compiler shows error on javac-valid construct: raw types on overridden methods
279947	SimpleArtifactRepository.delete does not delete Symbolic links
279957	[doc] property osgi.noshutdown and option -noRestart
280026	Create the link in the root of the SDK / platform with a p2 action
280061	[formatter] AIOOBE while formatting javadoc comment
280063	org.eclipse.jdt.internal.compiler.parser.Parser.parseClassBodyDeclarations(char[], int, int, CompilationUnitDeclaration) should return consistent results
280068	[rename] Rename/Refactor package breaks plugin.xml when pressing Back on Preview
280079	NPE while parsing K_CLASS_BODY_DECLARATIONS
280156	Delta pack doesn't contain all platform pieces
280255	[formatter] Format edited lines adds two new lines on each save
280259	[regression] All resources missing when importing plugin as source project
280276	executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.pde.ui.TargetPlatformPreferencePage)') do not open Target Platform page
280285	[native touchpoint] LinkAction undo does not calculate paths correctly
280303	ServiceEvent.MODIFIED_ENDMATCH is not sent in all cases
280427	"Configuring accessibility options for textual editors" is not in TOC
280458	[DataBinding] New API is not showing up in Galileo javadocs
280497	Incorrect null result for IJavaProject.getClasspathEntryFor(IPath)
280615	CCE when changing sort order in file search result page
280616	[formatter] Valid 1.5 code is not formatted inside <pre> tag
280678	[schema] SchemaTransformer doesn't generate help for "API Information" sections
280708	Second call to setFont produces incorrect text
280755	[working sets] Check out into new working set results into strange working set
280888	change a java file in one plug-in will compile all related plugin projects
280917	[target] Target platform created with 3.4 doesn't work with 3.5
280921	Tree.select() sets selection instead of adding to selection
280929	Deadlock possible between refreshPackages and BundleLoader initialization
281053	Non thread safe use of static member gives NPE in ResolverImpl
281075	Bundle-NativeCode can't work on Windows Server 2008/Windows 7
281088	BrandingIron compares String to File
281125	[doc] typo whats new section: OSGi service registry enhancements
281150	product qualifier substitution broken for p2.generate.metadata
281290	Timer Leak when executing external tool actions
281317	[search] An internal error occurred during: "Java Search".
281348	[Net] Eclipse Galileo crashes under Japanese version of Windows XP
281372	RCP Product Export wizard copies over wrong Mac icon to launcher
281409	Create repository zip for org.eclipse.platform
281426	Race condition: IModelProxy.installed() is called after IModelProxy.disposed()
281446	[typing] "Cut" did not complete normally
281533	[formatter] ArithmeticException: / by zero at Scribe.printLineComment(Scribe.java:2161)
281546	NPE in PublisherUtil
281598	[assist] Problems during content assist - if project has empty zip file in classpath
281609	[javadoc] "Javadoc: Invalid reference" warning for @link to Java package
281623	[FastView] NPE in FastViewPane$2.setState (was: File Search doesn't work in 3.5.0)
281628	[Net] Should be impossible to edit native proxy setting by double-clicking the entry
281691	RCP application does not launch when having an own config.ini with generic bundle URLs
281723	[Databinding] SWTException: Invalid thread access when binding in non-UI thread
281727	[DataBinding] observing delegating value property of observable list/set/map returns null if master element's hash code has changed
281750	Dead link in description
281871	[content assist] The extension took too long to return from the 'computeCompletionProposals()' operation
281917	[Doc] Bad link in Ant Editor help page
281933	[Dialogs] Show Views Dialog and Windows Preference Dialog fail to open if SHOW_FILTERED_TEXTS is set to false
282001	SWT 64 Libraries on AIX built with wrong compiler options
282046	[MPE] MultiPageEditorSite does not remove properly its KeyBindingService
282321	No indication that help dialog tray opens (for accessibility)
282427	P2 Installer 3.5 fails with "An error occurred while collecting items to be installed"
282563	[ds] RCP using declarative services (occasionally) hangs for 30 secs on start-up
282680	name of win32 x86_64 drop is incorrect in sdk.tests\testScripts\test.xml
282690	[DataBinding] problems with disposed observables
282704	[launcher] EclipsePolicy assumes non-null CodeSource
282739	performance hit on workspace start to build problem detectors
282747	The library.extensions configuration property does not require leading '.' dots
282850	runtests should allow aix.motif.ppc
282851	Default version of Ant Runtime set to Ant 1.6.5 instead of more recent 1.7.0
282874	[ViewMgmt] [ActivityMgmt] NullpointerException during saving state of view registry with disabled xp based activities
282891	[compiler] "Comparing identical expressions" warning sometimes invalid
283078	customAssembly not set for assemble.p2 script
283136	[Intro] AlwaysWelcomeCheckbox - incorrect URL when creating HTML content
283162	[DataBinding] 3.4 org.eclipse.jface.tests.databinding bundle has a higher version than 3.5
283163	[Content Type] ContentTypeCatalog causes deadlock (regression from 269158)
283185	product mirroring from context should be non-greedy
283186	Context repositories not passed to the product publisher
283204	[DataBinding] CheckableCheckedElementsObservableSet#clear can cause ConcurrentModificationException
283207	Plugin org.eclipse.swt.tests has a higher version in the Eclipse 3.4.2 release than the one in Eclipse 35
283297	Installation path containing square brackets prevents eclipse startup
283313	[Cocoa] Deleting TableViewer elements and calling refresh() causes major crash
283346	"Hide Eclipse" doesn't work properly
283351	[DataBinding] Document ObservableListTreeContentProvider ObservableCollectionTreeContentProvider constructor realm restriction
283428	[DataBinding] ViewerSupport.bind() cannot be called multiple times
283467	[formatter] wrong indentation with 'Never join lines' selected
283475	[launcher] Eclipse cannot be launched on Solaris 9 because of libc.so library version dependency
283529	Eclipse application freeze
283682	NPE when product does not want to show filter
283688	No drag/drop feedback selection on Table if using OwnerDrawLabelProvider on Windows
283797	Classloading fails when org.eclipse.osgi.framework.eventmgr.EventManager is closed
283958	SWT.MULTI does not work for SWT Text control using Mac OS X Cocoa.
284031	Error while parsing manifest
284303	Update loses launcher.ini arguments
284366	[DataBinding] ObservableValueEditingSupport sets model value 1st time even if not changed
284431	Different inherited thrown exception clauses are not properly handled
284482	[compiler] Collision cases not detected
284520	Class org.osgi.framework.Bundle.loadClass(String name) throws ClassNotFoundException for Array Types
284650	[CommonNavigator] Misleading JavaDoc of the INavigatorContentService
284728	[misc] Javadoc view stays empty if browser widget is not available
284785	[1.5][compiler] Eclipse compiler shows error on javac-valid construct: varargs plus overload
284872	TVT35:TCT313: CHS: Duplicate Mnemonic Keys
284948	[1.6][compiler] Java annotations are broken in editor when used on interface methods
284993	GC#setAlpha() not respected by GC#drawImage()
285045	[IDE] TVT35:TCT330: CHS: Duplicate Mnemonic Keys on workspace pref page
285094	[DS] Tracing throws Null Pointer Exception (NPE)
285215	Cannot change breakpoint type using RulerBreakpointTypesActionDelegate
285277	ACTIVE_EDITOR_INPUT_NAME does not contribute to source priority
285292	Trace fails to determine class/method/line number when using a tracing class
285322	[ui] TVT35:TCT328: CHS: Duplicate Mnemonic Keys
285437	[extract superclass] action not enabled any more when class is selected
285443	[transport] UpdateSite doesn't handle 403 errors properly
285464	[DS] dependency injection does not work when starting more than one instance of a service
285466	[3.5 regression] fails to build IcedTea, works with 3.4.x
285585	Broken links to PRODUCT_PLUGIN/book.css in platform.doc.user
285701	[1.5][compiler] Internal Compiler Error - ArrayIndexOutOfBoundsException
285727	[junit] default auto start setting doesn't work
285750	[Widgets] Combo - No selection event when selection changed with keyboard
285774	p2 director.app is generating compressed profile files by default.
285799	HashtableOfObject rehashes and grows buffer on removeKey()
285804	[Import/Export] File -> Import filesystem w/cyclical symbolic folder links causes OOME
285838	[apt] IdeFilerImpl breaks javax.annotation.processing.Filer contract
285909	Increment product version numbers for 3.5.1
285938	Update org.osgi classes to latest v4.2
285996	[EditorMgmt] [Patch] Reloading of bundles does not discard all editor descriptors
286028	Organize Manifest: Do not remove lazy Bundle-ActivationPolicy header for DS bundles
286030	[import] [regression] Import as source
286047	GZipped profile format not understood by 3.5.0
286117	[tranport] Transfer Exception on subsequent download resume
286243	p2.user.ui feature version should be incremented in 3.5.1 stream
286307	FilePermission with "<<ALL FILES>>" in permissions.perm
286391	[compiler] jsr14 target behavior changed between ECJ 3.4.2 and ECJ 3.5
286407	[Model] IMemberValuePair don't return the right value for java.lang.annotation.RetentionPolicy annotations
286505	version of org.eclipse.equinox.p2.repository should be incremented in 3.5.x maintenance stream
286518	DVT35:TCT558: CHS - Help Contents - Incorrect number
286533	[DataBinding] Test failure in build N20090812-2000
286581	FeatureGeneralPropertyPage message collation
286600	[Markers] DVT35:TCT580: CHT: Descriptions the same as for Problem view
286645	Fix for bug 155465 doesn't take security into account.
286682	SwitchStatement traverses this.expression with incorrect scope
286720	DVT35:TCT601: FRA - Access Rules title should be in bold
286721	DVT35:TCT599: FRA - PDE - Link not working
286755	[Help] The dialog font is not applied to the Help Content preference pages.
286779	[Browser] Xulrunner >= 1.9 Embedding: need to call "XRE_NotifyProfile"
286840	ClasspathJar getPath() should return a unique path
286956	NPE when asking to externalize constant
286968	Backport to 3.5.1 fix for Bug 103301
287138	[CommonNavigator] Add tests simulating CDT/JDT to CNF
287208	TVT35:TCT669: DEU: Defunct. buttons in Preferences API Errors/Warnings
287323	[compiler][apt] Error type detection is too conservative
287424	[JUnit] Update license for 4.5
287449	Behavior change between 3.4.2 and 3.5 around TCCL management when a Bundle is started
287590	core.resources bundle version needs to be incremented in 3.5.x stream
287601	[DataBinding][Regression] NullpointerException if observables are disposed while masterdetail running
287621	[CommonNavigator] Add more tracing
287746	Adopt ECF support on NTLM2
287850	EventManager must protect thread creation with proper doPriv
288374	[CommonNavigator] Compile error in tests

236 bugs found.

Sun, Solaris, 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, Vista, 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 2009

Appendix 1: Execution Environment by Bundle

In the table below, the "3.5 minimum execution environment" column indicates the minimum Java class library requirements of each bundle for the 3.5 release, where the value is one of: