Last revised June 23, 2005
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
Most of the Eclipse SDK is "pure" JavaTM code and has no direct dependence on the underlying operating system. The chief dependence is therefore on the Java 2 Platform itself. The 3.1 release of the Eclipse Project is written and compiled against version 1.4 of the Java 2 Platform APIs, and targeted to run on version 1.4 of the Java 2 Runtime Environment, Standard Edition.
There are many different implementations of the Java 2 Platform running atop a variety of operating systems. We focus Eclipse testing on a handful of popular combinations of operating system and Java 2 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 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 SDK 3.1 is tested and validated on the following reference platforms:
Eclipse Reference Platforms
|Operating system||Processor architecture||Window system||Java 2 Platform|
|Microsoft Windows XP||Intel x86||Win32||Sun Java 2 Standard Edition, version 1.4.2_08 for Microsoft Windows|
|Microsoft Windows XP||Intel x86||Win32||
IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.2 SR1a
|Microsoft Windows XP||Intel x86||Win32||Sun Java 2 Standard Edition 5.0 Update 2 for Microsoft Windows|
|Red Hat Enterprise Linux WS 3||Intel x86||GTK||Sun Java 2 Standard Edition, 1.4.2_08 for Linux x86|
|Red Hat Enterprise Linux WS 3||Intel x86||GTK||IBM 32-bit SDK for Linux on Intel architecture, Java 2 Technology Edition, Version 1.4.2 SR1a|
|SLES 9||Intel x86||GTK||Sun Java 2 Standard Edition, version 1.4.2_08 for Linux x86|
|SLES 9||Intel x86||GTK||IBM 32-bit SDK for Linux on Intel architecture, Java 2 Technology Edition, Version 1.4.2 SR1a|
|Sun Solaris 8||SPARC||Motif||Sun Java 2 SDK, Standard Edition, 1.4.2_08 for Solaris SPARC|
|HP HP-UX 11i||hp9000
HP-UX SDK for the Java 2 platform, version 1.4.2.07 for hp9000 PA-RISC
|IBM AIX 5L Version 5.2||PowerPC||Motif||
IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4.2 SR1a
|Apple Mac OS X 10.3||PowerPC||Carbon||Java 2 Standard Edition 1.4.2 for Mac OS X|
Although untested, Eclipse should work fine on other OSes that support the same window system. For Win32: Windows 98, ME, NT, 2000, and Server 2003; SWT HTML viewer requires Internet Explorer 5 (or higher). For GTK on other Linux systems: version 2.2.1 (or higher) of the GTK+ widget toolkit and associated librares (GLib, Pango); SWT HTML viewer requires a GTK2 build of Mozilla 1.4 (or higher). For Motif on other Linux systems: Open Motif 2.1 (included); SWT HTML viewer requires a GTK2 build of Mozilla 1.4 (or higher).
An early access version of Eclipse is also available for 64-bit Linux GTK. Testing has been limited to early access 64-bit J2SEs running on x86-64 processors.
SWT is also supported on the QNX Neutrino operating system, x86 processor, Photon window system, and IBM J9 VM version 2.0. Eclipse 3.1 on Windows or Linux can be used cross develop QNX applications. (Eclipse 3.1 is unavailable on QNX because there is currently no 1.4 J2SE for QNX.)
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 (level 1), the Chinese code page standard, on Windows XP and 2000, and Linux.
German and Japanese locales are tested.
SWT fully supports BIDI on Windows only. On Linux GTK, SWT supports entering and displaying BIDI text.
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. On the Windows platform only, the Eclipse SDK itself can be localized for BIDI locales and the widget orientation will change appropriately.
Eclipse 3.1 is compatible with Eclipse 3.0.
API Contract Compatibility: Eclipse SDK 3.1 is upwards contract-compatible with Eclipse SDK 3.0 except in those areas noted in the Eclipse 3.1 Plug-in Migration Guide. Programs that use affected APIs and extension points will need to be ported to Eclipse SDK 3.1 APIs. Downward contract compatibility is not supported. There is no guarantee that compliance with Eclipse SDK 3.1 APIs would ensure compliance with Eclipse SDK 3.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 3.1 is upwards binary-compatible with Eclipse SDK 3.0 except in those areas noted in the Eclipse 3.1 Plug-in Migration Guide. Downward plug-in compatibility is not supported. Plug-ins for Eclipse SDK 3.1 will not be usable in Eclipse SDK 3.0. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain binary compatibility.
Source Compatibility: Eclipse SDK 3.1 is upwards source-compatible with Eclipse SDK 3.0 except in the areas noted in the Eclipse 3.1 Plug-in Migration Guide. This means that source files written to use Eclipse SDK 3.0 APIs might successfully compile and run against Eclipse SDK 3.1 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.1 is upwards workspace-compatible with Eclipse SDK 3.0 unless noted. This means that workspaces and projects created with Eclipse SDK 3.0 can be successfully opened by Eclipse SDK 3.1 and upgraded to a 3.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 3.1 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; 3.1 plug-in developers are responsible for ensuring that their plug-ins recognize 3.1, 3.0, 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 a product based on Eclipse 3.1 will be unusable with a product based an earlier version of Eclipse. Visible metadata files created (or overwritten) by Eclipse 3.1 will generally be unusable with earlier versions of Eclipse.
Non-compliant usage of APIs: 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 an earlier releases. Refer to How to Use the Eclipse API for information about how to write compliant plug-ins.
Since Eclipse 3.0 is compatible with Eclipse 2.1 and 2.0 in most regards, and Eclipse 3.1 is compatible with 3.0, it follows that 3.1 is also compatible with 2.1 and 2.0 in most aspects. If you are upgrading directly from 2.1 or 2.0, refer also to the Eclipse 3.0 Plug-in Migration Guide for problems areas.
3.1.7 Team and CVS
3.2 Java Development Tools (JDT)
3.3 Plug-in Development Environment (PDE)
Note: Bug numbers refer to the Eclipse project bug database at http://dev.eclipse.org/bugs/
Here are some common problems that can cause Eclipse not to start:
If you have installed new plug-ins and they aren't showing up when you run, then perhaps you unzipped them into your "plugins" directory and your configuration might need to be refreshed. This can be accomplished by starting Eclipse with the -clean command line argument.
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)
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.
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)
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
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)
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
code. (bug 5875)
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)
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)
When launching an Eclipse Application from within the Eclipse IDE it is possible to select the set of plug-ins that are included in the Eclipse Application. Removing the org.eclipse.update.configurator plug-in from the set of plug-ins to an existing configuration can cause the configuration to become invalid. This can result in extra plug-ins installed in the target application that are not resolved. To work around this, after the org.eclipse.update.configurator plug-in has been removed, the target configuration area should be cleared before launching. (bug 85835)
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)
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
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).
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).
Certain Ant tasks are known to leak memory. Please see the bug report for details, patches, and possible workarounds. (bug 24448)
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)
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)
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)
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.6.1 (bug 30886)
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)
When debugging Ant builds within Eclipse, setting -logger as a program argument will be ignored.
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)
- In the Control Panel, open Internet Options, select the Connections tab and choose LAN Settings.
- If your host was configured to use DHCP for IP assignment, make sure that the "Automatically detect settings" check box is cleared.
- If you use a proxy server, ensure that the "Bypass proxy server for local addresses" is selected.
- In "Advanced" settings for proxies, add "127.0.0.1;localhost" to the "Exceptions" if these addresses are not listed.
- 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,
should work. Also, especially when running a firewall, you may want to specify
port 80 or some other firewall-friendly value. (bugs 7036,
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)
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)
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.
The Intro support has the concept of dynamic and static pages. Dynamic pages are described using the intro config XML content and static pages are HTML files either local or remote. An intro config has the notation of being static or dynamic, this is determined by the type of home page specified in the intro presentation. The current implementation only allow dynamic pages to be used within a dynamic intro and static pages within a static intro, i.e. they are mutually exclusive.
To workaround this problem when using a dynamic intro, a dynamic page can use the <html> element with the "type" attribute set to inline. This will include a static HTML file in the dynamic page (bug 68490)
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:
For Windows 2000:
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)
If an OLE document crashes, Eclipse can crash, or the workbench menus can become inconsistent.
File > Open External File can fail when the editor opened for the external file (as determined by Workbench > File Associations preferences) cannot not deal with external files. (bug 58179)
A text editor opened on a file external to the workspace does not show a vertical ruler. So if you set breakpoints in the file, you won't see the breakpoints in the editor (the breakpoints only show up in the Breakpoints view). (bug 54900)
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 are supported by the SWT Browser?".
With some versions of Synergy from Telelogic, Eclipse will crash when you try to open a file
dialog. This is due to a problem with the CMExplorer.dll. The workaround is to
upgrade to Synergy 6.4 (or higher) or to run
"regsvr32 /u CMExplorer.dll" and
reboot (note that this will disable Active CM).
With Acrobat Reader 6 or 7, some users have experienced an unresponsive user interface for up to two minutes when closing a browser which is displaying a PDF document. The workaround is to disable displaying PDF in the browser. In Adobe Reader select Edit > Preferences... > Internet and uncheck 'Display PDF in browser'. (bug 56184)
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)
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)
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)
Users of the Bluecurve theme shipped with RedHat Linux 9 may experience problems running Eclipse. These problems may include crashes or reduced performance. We recommend changing to a different theme. (bugs 38305, 67906, 37683, 58738)
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)
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)
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)
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.
On Windows NT only, you should avoid creating items in a
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.
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)
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)
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.
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
chmod 555 *.sl
(bug 20305 describes a related problem)
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.
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.20). As for the 1.12.X feature releases of CVS, the Eclipse CVS client has been tested with builds up to 1.12.12. 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. (bug 67627)
The Platform's internal authorization database file location has changed for 3.0. 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 re-authenticate.
In 2.x, CVS used markers to identify outgoing additions and outgoing deletions. In 3.x, these markers no longer exist because the Synchronize view can be used to show the same information. If CVS markers exist in a workspace that is upgraded to 3.x, they can be removed by performing a Project>Clean. (bug 40593)
In 1.0, CVS used a .vcm_meta file to store project configuration information. In 2.0, this file was replaced by the .project file but CVS still read the .vcm_meta file for backwards compatibility. In 3.x, the .vcm_meta file is no longer read by CVS. Users who wish to upgrade from 1.0 to 3.x must first upgrade to 2.x and then upgrade to 3.x if they wish to keep their project configuration information (e.g. java project). (bug 43296)
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)
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)
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)
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)
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)
When folders containing build output are shared they may get improperly marked as dirty when build output is generated. (bug 50965)
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,
Then, open the Help > Software Updates > Manage Configuration dialog and toggle on the "Show disabled features" button in its toolbar. Select the newly "installed" feature and press on the "Enable feature" action on the right pane (or select the action from the feature's context menu). (bugs 52525, 66120, 67461)
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. Since 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)
When a feature containing the OSGi and Eclipse runtime plug-ins is updated to a newer version, performing the Revert operation to undo the action will seemingly work, but the OSGi and runtime plug-ins in use will still be those used prior to the Revert. In effect, updating to a newer version of Eclipse platform is not reversible. All other features can be reverted without problems. (bug 74585)
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).
None. (Known problems with the Java debugger appear below in the JDT section.)
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 bytecodes, leaving no trace of a field reference. (bug 12044)
When referencing a secondary type defined in another compilation unit (i.e., a top level type whose name does not match its file name), the editor may incorrectly report it to be missing. The Java compiler handles this case fine. (bug 32505)
The Java indexer analyzes modified Java files in the background. If the indexer happens to crash (which it can under rare circumstances), it will automatically recover and rebuild the affected indexes. If this happens, it adds an informative entry to the .log file to. The rebuilt indexes are fine, and the crash does not impact subsequent search operations. (bug 66836)
Although external class folders (i.e., folder containing .class files and located outside workspace) were never properly supported by the JDT, a problem was never reported when constructing such a build path. JDT now properly diagnoses a problem in this situation. In order to still benefit from external .class files, a class folder must be mounted as a linked folder in Eclipse workspace (in project properties, select Java Build Path > Libraries > Add Class Folder > Create New Folder... > Advanced. Then a folder name can be associated with an arbitrary file system location by checking "Link to folder on the file system). Once mounted, the linked class folder can normally be referenced on a build path, and from there on programs can be compiled against it. (bug 67631)
When a type inherits some member from a restricted super type, no access violation is diagnosed when using the offending member indirectly through this type. (bug 76266)
The Java views (e.g. Package explorer, Type Hiararchy, Open Type dialig, etc.) support filtering their elements based on a working set. Although the dialog offers to select a Plug-in working set, applying such a working set results in an empty view (bug 67814).
Packages explicitly included on the build path using inclusion filters will not be visible in either the Package Explorer or Packages views when the views are set to hierarchical layout mode. Use the flat layout mode when using inclusion filters. (bug 65240)
Adding a new word to the spell checking dictionary does not correct the corresponding spelling errors. The spelling errors do go away the next time you change the file's content. (bug 68282)
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)
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 35395)
Most class libraries do not properly support the creation of a system
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)
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)
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)
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)
When more than one variable references the same object in the Variables view, only one variable will update while stepping through source code. (bug 58768 and 98147)
java.lang.NoClassDefFoundErrorwhen running Java programs with non-Latin characters in the package or class names. The workaround is to package the class files as a JAR file and run the program out of the JAR and not from the file system directly. (bug 4181)
Most class libraries do not properly support the creation of a system
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)
Automatic JRE detection fails when the JRE is stored in a directory containing GB18030 characters in its name. (bug 33844)
If a debug session suspends on a
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)
The debugger uses threads in the target JVM to perform evaluations (both
explicit evaluations that the user requests, and implicit evaluations such as
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)
rt.jar") are compiled without complete debug attributes, and thus local variables and method arguments for those classes are not visible in the debugger.
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.
When a snippet is run in the scrapbook which directly or indirectly calls
the evaluation cannot be completed, and will result in a stack trace for a
being displayed in the scrapbook editor.
Terminating a scrapbook page while it is performing an evaluation results
com.sun.jdi.VMDisconnectedException being displayed in the
System.err, the output may not appear immediately unless the native performs a flush on the output buffer.
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)
When you copy an item in one of the table viewers on the Dependencies, Extensions or Extension Points pages of the plug-in manifest editor, you will not be able to paste it. For copy and paste operations, use the source page of the editor. (bug 67582)
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.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)
It is possible for an extension point search result to include a false hit in the following specific scenario. If you open the plug-in manifest editor on a plug-in that contains both a plugin.xml and manifest.mf, go to the Extension Points page, select one of the extension points and click on 'Find references', the result may include a false hit. The false hit would result only if another plug-in in the product had declared an extension point by the same id. Workaround in this case would be to perform the search through the Plug-in search page. (bug 62177)
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)
Non-default key bindings currently do not work in fields on non-source pages of the PDE manifest editors. (bug 19482)
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)
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)
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)
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
JRE, not 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
c:\eclipse-SDK-3.1-win32, the executable is
Note: Set-up on most other operating environments is analogous. Special
instructions for Mac OS X are listed below.
By default, Eclipse will allocate up to 256 megabytes of Java 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 memory, you would typically use:
eclipse -vmargs -Xmx<memory size>
<memory size> value set to greater than
"256M" (256 megabytes -- the default).
Note that setting this value 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.
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
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).
Here is a typical Eclipse command line:
eclipse -vm c:\jdk1.4.2\jre\bin\javaw -vmargs -Xmx256M
Tip: It's generally a good idea to explicitly specify which Java VM to
use when running Eclipse. This is achieved with the "
command line argument as illustrated above. If you don't use "
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:
eclipse.exein Windows Explorer and use Create Shortcut on the content menu.
Opening this shortcut launches Eclipse. (You can drag the shortcut to the Windows Desktop if you want to keep it in easy reach.)
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
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.
Info.plist file in the
Contents subfolder and open it with your favorite text editor.
Add to, remove from or edit the command line options listed at the end of the file for the "Eclipse" key.
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. Due to a platform limitation you cannot
pass an arbitrary Java VM to the "
-vm" option, but must use the program "
java_swt" found inside
the application bundle; for example:
cd <eclipse directory> ./eclipse -vm Eclipse.app/Contents/MacOS/java_swt
On Mac OS X 10.4 and later, you may notice a slowdown 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.
If you weren't previously using "-data" to specify your workspace, follow these steps to upgrade:
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.
-data" command line argument to pre-select the workspace location).
If you were previously using the "
-data" argument to
start Eclipse, your upgrade path is much easier:
-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.
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.1 while others are working in Eclipse 3.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 3.1 user. 3.1 metadata is lost when a 3.0 user saves changes and then commits the updated metadata files to the repository. Here's how things typically go awry:
Here are a list of things to watch out for when the project is to be shared between users of Eclipses 3.1 and 3.0:
.projectfile. The format of the information changed between 2.1 and 3.0. Builders created or changed in 3.0 use the new format, which is not understood by a 2.1 workspace. Builders created in 2.1 use the old format and continue to work in 2.1. Builders from a 2.1 workspace can be viewed in a 3.0 workspace in read-only mode. Recommendation: Always create or edit external tools builders from a 2.1 workspace. The builder information also changed between 3.0 and 3.1. Changes will be seen in the
.projectfile and associated
.launchfile. The new 3.1 format is backwards compatible with 3.0.
.classpathfile. Recommendation: do not commit a change to the
.classpathfile performed by a 3.0 client, as it may erase extra information which got added by a 3.1 client. Note, though access rules and native library locations usage can be avoided by a 3.1 client; javadoc locations are now automatically shared in the
It is also possible (and reasonable) to use Eclipse 3.1 to develop a plug-in intended to work in Eclipse 3.0 or earlier. Use the Plug-in Development > Target Platform preference page to locate non-workspace plug-ins in an Eclipse 3.0 install. This ensures that the code for your plug-in is being compiled and tested against Eclipse 3.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.)
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 2005