# Eclipse Project Release Notes

Release 3.0.1
Last revised September 16, 2004

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

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

## 1. Target Operating Environments

Most of the Eclipse SDK is "pure" 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.0 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.0 has been 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 SDK, Standard Edition, version 1.4.2_03 for Microsoft Windows
Microsoft Windows XP | Intel x86 | Win32 | IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 1.4.1
Red Hat Enterprise Linux WS 3 | Intel x86 | GTK | Sun Java 2 SDK, Standard Edition, 1.4.2_03 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.1
SuSE Linux 8.2 | Intel x86 | GTK | Sun Java 2 SDK, Standard Edition, 1.4.2_03 for Linux x86
SuSE Linux 8.2 | Intel x86 | GTK | IBM 32-bit SDK for Linux on Intel architecture, Java 2 Technology Edition, Version 1.4.1
Sun Solaris 8 | SPARC | Motif | Sun Java 2 SDK, Standard Edition, 1.4.2_03 for Solaris SPARC
HP HP-UX 11i | hp9000 PA-RISC | Motif | HP-UX SDK for the Java 2 platform, version 1.4.2.00 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.1
Apple Mac OS X 10.3 | PowerPC | Carbon | Java 2 Standard Edition 1.4.1 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 of the GTK+ widget toolkit and associated librares (GLib, Pango); SWT HTML viewer requires Mozilla 1.4GTK2. For Motif on other Linux systems: Open Motif 2.1 (included); SWT HTML viewer requires Mozilla 1.4GTK2.

An early access version of Eclipse is available for 64-bit Linux GTK. Testing has been limited to early access 64-bit J2SEs running on AMD64 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.0 on Windows or Linux can be used cross develop QNX applications.

#### Internationalization

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

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

The Eclipse SDK supports GB 18030, the new Chinese code page standard, on Windows XP and 2000, and Linux.

German and Japanese locales have been tested.

#### BIDI support

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. but the Eclipse SDK itself is not designed to be localized for BIDI locales and its widget orientation can not be changed.

## 2. Compatibility with Previous Releases

### Compatibility of Release 3.0.1 with 3.0

As a general rule, maintenance releases of Eclipse have exactly the same APIs as the major release on which they are based. This means that plug-ins developed against any point release (e.g., 2.1.2) on the maintenance stream can be deployed on any of the other releases in the stream, including both earlier (2.1.0) and later (2.1.3) ones. In a few instances, we have made exceptions and added new API in order to address serious problems.

These are the APIs that have changed in 3.0.1:

- CopyProjectOperation class in package org.eclipse.ui.actions (plug-in org.eclipse.ui.ide) (bug 72978)
  - Added new methods
    - public boolean isCanceled()
    - public String getNewName()
- Extension point org.eclipse.team.core.repository (bug 66407)
  - Added new "canImportId" attribute on <repository> element
- Extension point org.eclipse.debug.ui.launchShortcuts (bug 55804)
  - Added new "path" attribute on <shortcut> element
- Plug-in org.eclipse.ui.intro (bug 69855)
  - Added new interface IIntroContentProvider in package org.eclipse.ui.intro.config
  - Added new interface IIntroContentProviderSite in package org.eclipse.ui.intro.config
  - Added new element <contentProvider> (intro content file)
- Plug-in org.eclipse.ui.intro (bug 69886)
  - Changed default encoding for <html> and <head> snippets to UTF-8 rather than local encoding (intro content file)
  - Added new "encoding" attribute on <head> element (intro content file)
  - Added new "encoding" attribute on <html> element (intro content file)
- Plug-in org.apache.ant was updated from Ant 1.6.1 in Eclipse 3.0 to Ant 1.6.2 in Eclipse 3.0.1. Since the Ant API was augmented between 1.6.1 and 1.6.2, Ant tasks developed against Eclipse 3.0.1 may not work in Eclipse 3.0.0 out of the box. Users can work around this problem by downloading and installing an Ant 1.6.2 release and configuring Eclipse to use the Ant 1.6.2 libraries instead of the 1.6.1 ones (see the section "Using a different version of Ant" in the Workbench User Guide).

When developing plug-ins intended to be deployed successfully atop any Eclipse 3.0.* release, avoid using any of the elements in the above list.

### Compatibility of Release 3.0 with 2.1 (and 2.0)

Eclipse 3.0 is compatible with Eclipse 2.0 and 2.1 to the greatest extent possible.

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

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

Workspace Compatibility: Eclipse SDK 3.0 is upwards workspace-compatible with Eclipse SDK 2.0 or 2.1 except as noted in the next section. This means that workspaces and projects created with Eclipse SDK 2.0 or 2.1 can be successfully opened by Eclipse SDK 3.0 and upgraded to a 3.0 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.0 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; 3.0 plug-in developers are responsible for ensuring that their plug-ins recognize 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.0 will be unusable with a product based an earlier version of Eclipse. Visible metadata files created (or overwritten) by Eclipse 3.0 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 an earlier releases. Refer to How to Use the Eclipse API for information about how to write compliant plug-ins.

### 2.1 Incompatibilities between release 3.0 and 2.1

Eclipse 3.0 breaks compatibility with Eclipse 2.1 in areas described in the Eclipse 3.0 Plug-in Migration Guide located in the Platform Plug-in Developer Guide (one of the help books included with this released, also available here on the web).

## 3. Known Issues

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

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

### 3.1 Platform

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

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

#### Eclipse process does not exit (HP-UX only)

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

> `eclipse -vmargs -XdoCloseWithReadPending`

(bug 18321)

#### Problems reading log file

Internal errors are reported to the Eclipse log file (.metadata/.log). The log is a structured text file with messages in English. The log is written using UTF-8 encoding so that it can capture non-Latin characters that might be embedded in stack traces, etc. When viewing the log file, the Eclipse editor (or external program) should be configured to treat the log as UTF-8. (bug 67872)

### 3.1.1 Platform - Core

#### Eclipse fails to start after moving or copying Eclipse install

When a Eclipse install is run for the first time, it caches various information about the configuration. If the Eclipse install is then moved or copied to another location on disk, this cached information becomes invalid. To avoid the problems that this can cause, the first time the moved or copied Eclipse is launched, the -clean command line option must be used to tell Eclipse to discard previously-cached configuration information. (bug 70454)

#### Eclipse fails to start on some file systems

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)

#### 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 JRE). 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.

#### Changing the character encoding for a resource causes inconsistencies

Changing the character encoding for a resource (or the whole workspace) does not trigger resource change events or auto builds. The result is that builders and listeners that maintain state derived from the affected resources will not have a chance to run, causing inconsistencies (such as compiler errors not going away and searching for references not working properly). To avoid the problem, create the project and set its character encoding before creating (or importing) any files in it. However, if you do need to make a project consistent again, try the following steps (in order):

1. Close all projects.
2. Exit Eclipse.
3. Restart Eclipse.
4. Re-open all projects.
5. Project > Clean all projects.

(bug 59899, 67884).

#### Invalid characters in install directory prevents Eclipse from starting

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

#### Problems with classloaders in created threads

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

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

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

#### Deadlock creating executable extension in Plugin.startup

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

### 3.1.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 runs Ant in the same JVM as the rest of Eclipse. Several aspects of Ant and its use of global Java resources (such as System.out and System.err), make it unsafe to run more than one Ant build concurrently. (bug 24129).

#### Running certain Ant tasks cause memory leakage

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

#### Tasks that require input lock up workspace

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

#### No input handler supplied for <input> task when running Ant in a separate VM

By default, no input handler is supplied for the <input> task for a build running in a separate VM. Therefore the input requests will always fail. The user can supply an input handler using the -inputhandler argument. (bug 45484)

#### "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 always based on Ant 1.6.1. (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)

### 3.1.3 Platform - Help

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

If your LAN settings are not properly configured for local host access, your Help browser might open to a blank page or display an HTTP error instead of a help page, or you may experience long delays when loading help documents. Your system administrator can configure your LAN settings so that help documents can be accessed from the local help server.

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

If you are experiencing problems when not connected to the network, you must install the loopback adapter from the Windows installation CD. (bug 831)

#### Using Internet Explorer in offline mode (Windows only)

If you have been using Internet Explorer in Offline mode, when you access the help system you will get a message indicating that the web page you requested is not available offline or a blank page will display. Click Connect or deselect "Work Offline" in the Internet Explorer "File" menu to return the system behavior to normal.

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

#### Modal interference between Help browser and workbench

If the Help browser gets stuck with an error dialog, some parts of the workbench window stop responding to events. Similiarly, Help topics that teach and describe usage of complex wizards and dialogs are unusable in the default (built-in) browser due to modal wizards and dialogs. To work around this problem, use the Help > Always use external browser preference setting to configure Help to open in a standalone browser. (bug 67543)

#### Internationalized Help documents displayed incorrectly (Windows only)

The embedded help browser used on Windows (Internet Explorer) may display corrupted characters for some documents if the Auto-Select Encoding option is turned on. Right click within the frame containing the incorrectly displayed help document, and clear the check mark beside Encoding > Auto-Select. (bug 72131)

### 3.1.4 Platform - UI

#### High contrast settings

Eclipse was tested for High Contrast using 1162 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.

#### File system import loses file permissions (Unix-based platforms)

Importing files into a project using the Import > File System wizard strips the execute permission from executable files. (bug 25387)

#### Closing zoomed editors hides other editor areas

If you split the editor area into two areas, zoom an editor and then close it, it is possible for that the second area will be covered by the first. This can be worked around by zooming the visible editor and then unzooming it. (bug 66974)

#### Problems customizing colors and fonts in non-default themes

If you are using a theme other than the default, a bug prevents you from customizing fonts and colors other than those that happen to have been overridden in the theme definition. There is no such limitation with the default theme. (bug 67221)

#### Problem mixing dynamic and static pages within intro configs

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)

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

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

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

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

For Windows XP:

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

For Windows 2000:

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

(bug 20641)

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

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

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

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

### 3.1.5 Platform - Text

#### Problems opening external files

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)

#### Text editors does not show vertical ruler for external files

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)

### 3.1.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 are supported by the SWT Browser?".

#### Eclipse crashes on RedHat Linux 9 (GTK+ only)

Users of the Bluecurve theme shipped with RedHat Linux 9 may experience problems running Eclipse. These problems may include crashes or reduced performance. (bugs 38305, 67906, 37683, 58738)

We recommend changing to a different theme. Under GNOME, open RedHat Menu > Preferences > Theme. Select a theme other than Bluecurve. All applications should update at this point. Under KDE, open RedHatMenu > Run Command... And then type in "gnome-theme-manager" and click "Run". Select a theme other than Bluecurve. The selection may jump to "Custom Theme" afterward; this is normal, and happens because the GNOME window manager is not running. All GTK+ applications should update to the new theme at this point.

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

#### Drag and drop on Mac (Mac OS X Carbon only)

The Mac OS X Carbon implementation of SWT does not support dragging from an SWT application to another application. (bug 68212)

#### Components in SWT_AWT are not displayed (Motif only)

On Motif systems (verified on Linux and Solaris) problems have been reported by some developers in the support for embedding AWT widgets within SWT layouts. These can range from the AWT widgets not being properly displayed to Java VM crashes. The cause(s) of these problems has not yet been determined. (bug 68353)

#### Can't expand/collapse TableTree item with mouse (GTK only)

Under certain conditions and on certain versions of GTK, TableTree items, such as those found in Property Sheets, cannot be expanded or collapsed using the mouse. The workaround is to use the right and left arrow keys. (bug 38855)

#### 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 the Eclipse bug report. (bug 34524)

#### Available colors on 8-bit Linux (Linux only)

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

#### List and ComboBox on Windows NT (Windows NT only)

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

#### Excessive CPU consumption (Linux GTK only)

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

#### IME-related crash (Linux Motif only)

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

#### Using IBM J9 VM (Photon and AIX)

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

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

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

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

(bug 20305 describes a related problem)

### 3.1.7 Platform - Team - CVS

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

#### 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.16). As for the 1.12.X feature releases of CVS, the Eclipse CVS client has been tested with builds up to 1.12.8. 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)

#### Cached authorization information lost when workspace is upgraded

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.

#### Issues upgrading from 2.x to 3.0

In 2.x, CVS used markers to identify outgoing additions and outgoing deletions. In 3.0, 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.0, they can be removed by performing a Project>Clean. (bug 40593)

#### Issues upgrading from 1.0 to 3.0

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 compatibilty. In 3.0, the .vcm_meta file is no longer read by CVS. Users who wish to upgrade from 1.0 to 3.0 must first upgrade to 2.x and then upgrade to 3.0 if they wich to keep there project configuration information (e.g. java project). (bug 43296)

#### Connection cannot be found after initially missing

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

#### CVS meta-folders appear in some cases

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

#### "Received broken pipe signal" error from server

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

#### "Terminated with fatal signal 10" error from server

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

#### "Unknown response" error using ext connection method

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

#### No way to update folder excluding subfolders

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

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

### 3.1.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 the system property osgi.checkConfiguration set to true. This property can be set in the eclipse/configuration/config.ini file, or passed to the eclipse command line via the -vmargs option. For example, restart with the following command: eclipse.exe -vmargs -Dosgi.checkConfiguration=true. Then, open Help > Software Updates > Manage Configuration dialog and toggle on the "Show disabled features" button 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)

#### Non-responsive sites may use all free threads

Prior to Eclipse 2.1, if the connection to an update site did not respond (the site did not exist or was down), the workbench became non-responsive until the connection request timed out. 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)

#### URL validity checking on input

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

### 3.1.9 Platform - Debug

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

### 3.1.10 Platform - Compare

None.

### 3.2 Java Development Tools (JDT)

#### Missing deprecation warnings

The library JARs that come with Java Runtime Environment distributions of J2SE sometimes omit the information about which API elements are deprecated. This information is found in the library JARs that come with SDK distributions of J2SE. When Java code is compiled against JRE libraries lacking deprecation information, the Java compiler cannot report uses of deprecated elements. (bug 40485)

#### 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 bytecodes, leaving no trace of a field reference. (bug 12044)

#### Developing programs with J2SE 1.5

The Java tools do not yet fully support J2SE 1.5. You can run or debug programs against a 1.5 JRE, and safely compile 1.4 programs against 1.5 libraries (the Eclipse compiler tolerates them with the exception of covariance scenarios which are forbidden byJava Language Specification (JLS) 2nd edition). However, the Eclipse Java compiler and IDE are unable to handle source files containing uses of any of the new Java language features being added in 1.5 (generics, enhanced for loops, static imports, metadata annotations, varargs), which will be codified in the forthcoming JLS 3rd edition. An early preview of the full Eclipse support for J2SE 1.5 developed in parallel with 3.0, and is available from the Cheetah page. (bug 36938)

#### Missing secondary types in editor

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)

#### Java indexing crash recovery

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)

#### Classpath entry denoting external class folder is now properly rejected

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)

#### Package Explorer not asking for filter removal

Show In > Package Explorer normally asks for removal of filters when the compilation unit to be shown in the Package Explorer is filtered out. However, this currently is not happening if only a single filter is selected. (bug 67814)

#### Hierarchical layout and inclusion filters

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)

#### Problems after moving a compilation unit

Moving a compilation unit can cause an editor open on that file to behave strangely. Closing and re-opening the editor fixes the problem. (bug 67046)

#### Stale spell check errors

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)

#### Javadoc hover in the Java editor

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

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

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

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

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

#### Cannot generate Javadoc for packages with GB18030 characters in the name

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

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

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

#### Multiple references to the same object do not update in Variables view

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)

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

You get a `java.lang.NoClassDefFoundError` when 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)

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

#### 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

The debugger requires that class files be compiled with debug attributes if it is to be able to display line numbers and local variables. Quite often, class libraries (for example, "`rt.jar`") are compiled without complete debug attributes, and thus local variables and method arguments for those classes are not visible in the debugger.

#### 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

Setting a breakpoint inside a scrapbook page is not supported.

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

A global Java debug preference specifies the debugger timeout, which is the maximum amount of time the debugger waits for a response from the target VM after making a request of that VM. Slow connections may require that this value be increased. The timeout value can be edited from the Java > Debug preference page. Changing the timeout value only effects subsequently launched VM, not VMs that are already running.

#### Updating of inspected values

When inspecting the result of an evaluated expression in the debugger, it is important to note that the result displayed is the result of that expression at the time it was evaluated. For example, when inspecting a simple integer counter (primitive data type), the value displayed in the Expressions view is the value when the expression was evaluated. As the counter is changed in the running program, the inspected result will not change (since the view is not displaying the value bound to a variable - it is displaying the value of an expression, and the value of a primitive data type cannot change). However, if an expression results in an object, fields of that object will be updated in the inspector as they change in the running program (since the value bound to fields in an object can change).

#### Stepping over native methods that perform I/O

When the debugger steps over native methods that perform I/O to `System.out` or `System.err`, the output may not appear immediately unless the native performs a flush on the output buffer.

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

Terminating a launch, debug target, or system process associated with a debug target running on the IBM 1.3 JVM on the Linux platform does not work when the associated debug target has a suspended thread. To remove such debug targets from the debug UI, select Terminate and Remove from the debug view's pop-up menu (or use the shortcut "delete" key). Associated system processes in the OS may not be properly cleaned up. If a debug target has no suspended threads, termination works properly. (bug 1631)

### 3.3 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)

#### Paste does not work in table viewers of the plug-in manifest editor

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)

#### 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.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.elipse.swt as binary with source attached. (bug 66314)

#### Search for an extension point reference may include a false hit

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)

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

#### Missing classes from exported plug-ins

On some platforms due to limitations of the length of filenames, the JARs generated by the File > Export.. > Deployable plug-ins and fragments command may be missing class files. This can happen if the workspace path, package names, or class names are too long. (bug 69620)

## 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 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 installed at `c:\eclipse-SDK-3.0-win32`, the executable is `c:\eclipse-SDK-3.0-win32\eclipse\eclipse.exe`. Note: Set-up on most other operating environments is analogous. Special instructions for Mac OS X are listed below.

Depending on the JRE that you are running, the number of plug-ins you are using, and the number of files you will be working with, you may have to increase the amount of memory that is available to the Java VM running Eclipse. 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. To increase the available memory, you would typically use:

> `eclipse -vmargs -Xmx<memory size>`

The `<memory size>` value should typically be at least "128M" (128 megabytes). Usually, "256M" (256 megabytes) is ample. You should not set this value to be larger than the amount of physical memory on your machine.

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 as a sibling of the executable (that is, at `c:\eclipse-SDK-3.0-win32\eclipse\workspace`). This workspace directory is used as the default content area for your projects as well as for holding any required metadata. For shared or multi-workspace installs you must explicitly specify the location for your workspace using the 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 "`-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 `Info.plist` 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 `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

## 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 subdirectory called "`workspace`". If you are using a shortcut or script to launch Eclipse, then it will be under the current working directory of that shortcut or script in a subdirectory called "workspace". For Windows users, this is specified by the "Start in:" argument in your shortcut properties.
2. Copy this workspace directory to a new, empty location outside of any Eclipse install directory.
3. Install the new version of Eclipse in a new location, separate from any old version of Eclipse.
4. 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.0 and 2.1

#### Sharing projects between heterogeneous Eclipse 3.0 and 2.1

Special care is required when a project in a team repository is being loaded and operated on by developers using Eclipse-based products based on different feature or plug-in versions. The general problem is that the existence, contents, and interpretation of metadata files in the workspaces may be specific to a particular feature or plug-in version, and differ between versions. The workspace compatibility guarantees only cover cases where all developers upgrade their Eclipse workspaces in lock step. In those cases there should be no problem with shared metadata. However, when some developers are working in Eclipse 3.0 while others are working in Eclipse 2.1, 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.0 user. 3.0 metadata is lost when a 2.1 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.0 creates or modifies a project in a way that results in changes to a shared metadata file that rely on 3.0-specific information. The user then commits the updated project files, including the shared metadata file, to the shared repository.
- Another user working in Eclipse 2.1 shares this project from the same repository. The 3.0-specific information in the shared metadata file is not understood by Eclipse 2.1, 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.0-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.0 picks up the changes to a project from the shared repository, including the updated shared metadata file. The user may be unaware that they have just taken a retrograde step until later when things start to malfunction.

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

- External tool (Ant) builders
  Information about external tool builder is recorded in the project's `.project` file. The format of the information changed between 2.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.
- Optional inclusion patterns on Java source entries on the build class path
  This support was added in 3.0. This information is recorded in the project's `.classpath` file. Recommendation: do not specify inclusion patterns. Better still, disable exclusion patterns via the Java > Compiler > Build Path preference page.

#### Using Eclipse 3.0 to develop plug-ins that work in Eclipse 2.1

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

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

Maintenance release 3.0.1 fixes the following defects present in release 3.0.0:

ID | Summary
--- | ---
33640 | Editor colors do not take effect on Apply
38288 | TVT21: English item in the Add Library panel
39863 | TableViewer / cellModifier / ComboBoxCellEditor: new valu...
44613 | [misc] some actions go to disk everytime they are selected
46134 | Migration of CVS repository location problem
47549 | GPF in XtSetValues on M5
52916 | Strange error message when using jre1.5.0 libraries
55804 | allow ordering in "Run As >" context menu
57408 | DBCS: After pressing "Tab", anything can not be inputed
59301 | [GlobalActions] View gets uninitialized ViewSite in its i...
59674 | Minor Typos
59899 | Encoding changes need to notify clients
61368 | Perspective layouts should define a place holder for the ...
62862 | [painting] Reusing Editors does not fully reset editor
63235 | [KeyBindings] Cut/Copy/Paste/SelectAll don't work in Swin...
63324 | [ActionSets] Plugin not deactivated with Exception at sta...
63546 | [OLE] In-place editor fails with: Class ID not found in r...
63947 | Enhance default search for numbers
64956 | [KeyBindings] TVT3.0: Error message on console during sta...
65938 | cannot generate Javadoc with excluded source folder [java...
66405 | Activities Dialog - empty categories should not be visible
66407 | Need multi-provider Project Set import compatibility mech...
66433 | Need keyboard support for Nested Tabfolder Traversal
66512 | Invalid classpath entry not rejected
67046 | Exception when dragging a method to another class using t...
67061 | [Browser] Blank page when opening page with Flash
67070 | SWTException from Forms code.
67221 | [Themes] Cannot customize values of colors/fonts when th...
67293 | [Themes] Setting inital theme to a bad theme id results i...
67547 | [3.0.1] Got user vetoed file modification although I neve...
67590 | [Presentations] The 'Save All' command has no effect
67716 | [ProblemsView] Trying to sort in Problems View removes al...
67789 | Java element delta from refresh contains excluded package
67811 | Need support for adding separators to the help menu
67878 | [3.0.1] Thread timed out while loading class ConsoleDocum...
67884 | [content type] Content type change events not reported
67912 | ConfiguredSite is null after dynamically installing a fea...
67913 | [ActionSets] Actions associated with views not disposed
68017 | Javadoc processing does not detect missing argument to @r...
68023 | Why does pde always append ".jar" on the runtime library ...
68025 | Javadoc processing does not detect some wrong links
68032 | PDE imports plugins only from default location when star...
68058 | NPE in JUnit view [JUnit]
68087 | [Javadoc] '-' character should be accepted in tag names
68117 | Error when changing class name in Configure Accessor Clas...
68146 | Search should not populate Java model cache
68158 | Error Log view does not display stack trace
68180 | [ActivityMgmt] Capabilities Preference page tree expansion
68250 | Throwing Focus to the EditorPart
68273 | tabletree plus/minus not visible in High Contrast Mode
68295 | User Libraries dialog loses settings [build path]
68343 | IDOMType.setSuperInterfaces() with empty array has no imp...
68349 | [osgi] NPE in FileManager.cleanup()
68405 | [3.0.1] CVS Resource History uses bad content description
68413 | NPE from InstructionPointerManager
68421 | boolean property editor is incorrect UI
68487 | "SAXParseException: XML declaration may only begin entiti...
68497 | Standby intro comes up empty
68504 | Refactor -> Change Method Signature removes import [refac...
68505 | [Progress] Progress view shows waiting job which doesn't ...
68562 | [projection] NPE in ProjectionViewer.setRangeIndication
68563 | [3.0.1] typo in 'Checkout from CVS' import wizard
68577 | [formatting] javadoc formatter removes blank lines betwee...
68585 | index is out of date after encoding change
68626 | [content type] LazyInputStream alters mark position on reset
68653 | Cannot install feature in new extension site, until restart
68677 | <not responding> label for restored bkp in source outside...
68683 | Schema transformer places <HTML> tag after <HEAD> stanza,...
68688 | Repeated string on Help welcome page
68698 | Bug in inner class emulation:compiler doesn't reject ille...
68712 | Export of multiple plugins fails
68721 | [3.0.1] ResourceVariantStorage causes StackOverflowError
68726 | [Javadoc] Target attribute in @see link triggers warning
68750 | sync hover too long
68772 | IDOMMember.getComments() sometimes returns wrong results.
68774 | [Perspectives] NPE in PerspectiveSwitcher.setCoolItemSize...
68785 | Wrong default value chosen for attribute with a restriction
68798 | API not indexed
68802 | org.eclipse.ui.themes identifier incorrect
68830 | build-site function corrupts feature.xml
68852 | [SSH2] Bug in Socks5 authentication
68855 | org.eclipse.swt.tools.internal.SwtJniGen is not working p...
68863 | Missing entry in local variable attribute
68868 | Sometime a search results in the error "Memento problem" ...
68886 | Code completion in Ant editor not work with xmlbuddy
68894 | [content type] preferences not being loaded
68921 | o.e.core.resources/schema/refreshProviders.exsd -- missin...
68932 | Exception when project is closed
68939 | [Workbench] Several org.eclipse.ui.*./schema/*.exsd files...
68941 | [Colour/Font] Two org.eclipse.ui./schema/*.exsd files -- ...
68962 | Eclipse don't show errors and warnings inside "new reposi...
68963 | [implementation] A bug of the IME composition string font.
69028 | Anonymous type in argument of super() is not in type hier...
69055 | Topics in the infocenter not indexed by Google
69151 | JUnit Plug-in Tests not working if tests are a fragment.
69152 | [NPE] An internal error occurred during: "Override indica...
69159 | Export feature "Confirm Replace" dialog missing a slash
69190 | NullPointerException @ org.eclipse.debug.core.sourcelooku...
69271 | decimal integer literals should not consist of FULL WIDTH...
69272 | [Javadoc] Invalid malformed reference (missing separator)
69275 | [Javadoc] Invalid warning on @see link
69302 | [Javadoc] Invalid reference warning inconsistent with jav...
69386 | [prefs] PreferenceForwarder does not honour -data @none
69398 | Table.clearAll() does not force redraw
69401 | TVT3.0: What's New->Eclipse Community link causes bogus ...
69410 | TVT3.0: mnemonics doesn't work if focus is in a text widget
69419 | [implementation] ChainedPreferenceStore
69422 | TVT3.0: untranslated string in "Checkout from CVS" proje...
69440 | Inspect32 does not show name for CCombo
69452 | NPE initializing source lookup
69470 | TVT3.0: NL Truncation occurs in Run -> External Tools -> ...
69533 | Activities in org.eclipse.team.examples.filesystem
69535 | TVT3.0: Multiple Mnemonics in CVS Repository Property
69536 | Infinite loop on rendering variables
69541 | [Dialogs] TVT3.0: Task List Description text entry widge...
69554 | Eclipse Java compiler is not completely compliant to Javac
69607 | [Preferences] TVT3.0: nonexternalized string in Preferen...
69608 | [About] TVT3.0: Non-externalized strings in About Eclips...
69612 | [Font/Colour] TVT3.0: Duplicated mnemonics in Preference...
69618 | TVT3.0: Truncation in External Tools -> Ant -> New Config...
69620 | Update site builder is ommitting some innerclasses from g...
69625 | TVT3.0: Non-externalized strings in Software Updates -> M...
69628 | TVT3.0: English dates displayed in manage configuration.
69637 | [CheatSheets] TVT3.0: Problem executing CVS Tasks cheat s...
69665 | Msg for missing .eclipseextension says .eclipseproduct
69669 | TVT3.0: Debug view has mnemonics in Debug, Run, and Exte...
69710 | [find/replace] Replace scope ignored
69723 | TVT3.0: Truncated text in memory view
69724 | [Fonts] TVT3.0: Description for colors & fonts are switched
69736 | IWAV0138E Remote VM terminated too soon error - when acce...
69768 | TVT3.0: Preferences -> Ant has text showing up in english
69782 | Eclipse doesn't automatically discover the inability to w...
69818 | NPE when launching with Debugger
69826 | NPE while debugging
69829 | TVT3.0: Tips and Tricks text in tables is right aligned.
69836 | TVT3.0: In Korean locale "View Installation History" fails
69840 | TVT3.0: Preferences - Platform Dictionary is in english
69843 | TVT3.0: Unexternalized string in Preferences>Java>Task Tags
69851 | TVT3.0: Corrupted text displaying in View Installation Hi...
69855 | Add dynamic/portlet capability to intro
69884 | TVT3.0: Truncation occurs in Add Library Panel
69886 | HTML fragments encoded in UTF-8 display some garbage char...
69900 | [EditorMgmt] Editor cannot be closed after it is activate...
69932 | TVT3.0: Add Constructor from Superclass has incorrect mne...
69961 | [other] NPE retrieving authorization info
69971 | Empty books shown in help working set dialog
69975 | TVT3.0: Preferences CVS has non-externalized strings
69978 | TVT3.0: Two shortcuts for one menuitem
70002 | [implementation] NPE while opening the first java editor
70011 | Installed JREs missing libraries
70030 | [Wizards] Help Context - New Folder or File
70051 | MemoryViewTab does not calculate delta and selected addre...
70077 | [typing] Copy/paste doesn't work occasionally
70080 | [RCP] Reset Perspective does not work if no perspective t...
70111 | TVT3.0: Java Project Properties has truncated text and bu...
70112 | org.eclipse.help.webapp JSPs fail validation
70114 | org.eclipse.help.webapp livehelp.js.jsp references unable...
70149 | [New Plug-in Project] Help Context
70158 | Exception trying to add getter [code manipulation]
70170 | [Schemas] Generated class for view extension does not ext...
70193 | DBCS - GB18030 characters cannot be correctly generated i...
70296 | Changes not being saved when comparing with revision
70299 | Eclipse dead slow on one system, normal on other
70354 | JSP editor does not scroll to/highlight the current execu...
70362 | [EditorMgmt] Topmost editor not properly restored
70364 | Adapt test cases to JDT/Core fix 68017 in 3.0.1 branch
70372 | [prefs] project preference listeners and the workspace
70373 | Make "Drop to Frame" action available in the context menu...
70403 | Hardcoded paths make copy of workspace unusable and event...
70412 | [api] Formatting a large file makes Eclipse freeze (enabl...
70428 | schema files -- missing &lt;pre&gt; and &lt;/pre&gt; tags...
70429 | missing &lt;pre&gt; and &lt;/pre&gt; tags in Examples sec...
70436 | [osgi] Infinite loop in basicStopBundles with IBM JRE 1.4...
70503 | [Commands] ctrl+c, ctrl+v, ctrl+x accelerators dont work ...
70598 | [Encoding] ArrayIndexOutOfBoundsException while testing B...
70623 | TVT3.0: No mnemonic on Run Last launched panel
70644 | User doc missing alt text
70648 | TVT3.0: Wrong string displayed in Ext Connect Method panel
70650 | Project builders do not execute in specified order.
70672 | Bogus url passed to shellexecute
70700 | [Progress] progress issues during build
70708 | no error message on missing product
70734 | TVT3.0: Duplicate mnemonics, ''Build Ant'' and ''Build A...
70744 | Breakpoint location validation error.
70762 | Infocenter documentation set cannot be updated without re...
70765 | TVT3.0: Split words on welcome page
70828 | [ProblemsView] ConcurrentModificationException is thrown ...
70841 | Move to Ant 1.6.2
70882 | EnablementDialog grows too big
70904 | TVT3.0: Help Show All Contents confirmation
70936 | Accessibility: "Hot keys" to jump between important frame...
70939 | Wrong characters used as mnemonics in help HTML UI
70946 | TVT3.0: Truncation in new Plug-in Project screen
70993 | incompatible thread state from drop to frame action
71003 | [osgi] Inconsistant behavior with bundle manifest files b...
71019 | Setting a ToolItem's control to a Button doesn't work in ...
71053 | [ActivityMgmt] IllegalArgException in Capability preferen...
71154 | FormToolkit.createExpandableComposite(..., ExpandableComp...
71185 | TVT3.0: Extra mnemonics for Debug, Run, and External tools
71242 | Manifest editor reports referenced resource not found pro...
71294 | Capabilities Preference Deselection.
71312 | TVT3.0: Non-externalized string 'matches in ...' in Sear...
71318 | TVT3.0: SWT Welcome panel 'Project name' not externalized
71364 | File Search fails if string contains single quote and a {
71390 | The -clean command line option needs to be documented.
71441 | DebugException: Unable to retrieve stack frame - thread n...
71467 | JavaConventions.ValidatePackageName() does not return ERROR
71490 | NPE in SchemaRegistry.getIncludedSchema
71495 | org.eclipse.jdt.ui.examples.projects has old icon
71561 | Inspect popup doesn't handle tabs in inspected expression
71596 | Some files missing from the distribution of the Ant plugin
71683 | Builders, cancellation, and last build state
71742 | [IDE] use long-running operations to set encoding
71767 | Semantic highlighting does not update scanners on propert...
71806 | Convert to Plugin Project does not generate 3.0 compliant...
71823 | empty manifest files included in update site downloads co...
71826 | [registry] Extensions lost dependant on fragment/plug-in ...
71967 | Error using Help: org_eclipse_jdt_ui_javaEditorTextHover....
72024 | UndoManager creates potential memory leak [refactoring]
72040 | ActiveX Accessibility
72062 | CLEAN constant missing from "IncrementalBuild" Ant task
72111 | Existing manifest files can confuse confuse PDE
72114 | [ViewMgmt] Views that implement ISaveablePart are not con...
72136 | Swap Feature Task does not display text from property file
72305 | JDIModelPresentation uses resource name with IJavaStratum...
72340 | [doc] Best practices documentation for Infocenter compati...
72350 | NPE in BreakpointsView.dispose
72366 | NPE from LaunchView
72383 | [Perspectives] Placeholder folder error with multiple ins...
72449 | NPE in VariablesView.saveState
72450 | PDE Junit launch short cut is not specific enough
72468 | "hierarchy of ... type is inconsistent" error message
72483 | NPE attempt to Inspect if never shown Variable view
72512 | Global Properties not set for editor parsing
72514 | [osgi] open up the framework for adding extensions
72542 | HCR when stopped on a Stratum Breakpoint
72545 | [encoding] adopt long-running version of IFile#setCharset
72552 | Help Search broken for nl characters in 3.0
72585 | [ViewMgmt] Empty variables view, inspect disabled
72597 | bad line ending in MANIFEST.MF keeps eclipse from booting.
72653 | [osgi] Application update through update site causes OSGI...
72669 | Deleting a modified file doesn't update icon decoration i...
72680 | Error Generating HTML Message in org.eclipse.ui.intro
72689 | adopt long-running version of IFile#setCharset
72747 | Unclosed jar file and stream in pluginConverter
72753 | "Show Properties" task missing in Configuration Manager
72789 | "Show in Browser" broken for Copyright and License in fea...
72978 | [Actions] Get cancel status and new name from CopyProject...
72979 | PasteAction should notify results
72986 | ExpressionInformationControl leaks
73053 | [misc] Status editor always empty
73107 | PinParticipantAction not removed as an IPropertyChangeLis...
73111 | [osgi] Review the EclipseAdaptor#handleRuntimeException b...
73128 | Error parsing plugin manifest file using 3.0.1 candidate
73130 | [Preferences] 3.0.1 candidate: Workspace gets (fully?) bu...
73166 | Exceptions when compatibility not installed
73195 | Incorrectly setting base folder for plugin import -> stra...
73213 | Unicode - Search problem with "Case sensitive" unchecked
73258 | Subscriber leakage on open/close of Synchronize view
73261 | 'Toggle Line Breakpoint' doesn't remove existing breakpoi...
73302 | Compiler errors after re-importing swt WITH links
73304 | Target Platform in runtime workbench references plugins i...
73330 | NullPointerException in search
73451 | Remove warnings from 20040908 build
73476 | chkpii error in org_eclipse_ui_intro_config.html in M2004...
73693 | [prefs] DefaultPreference initialize problems with no com...
73715 | [Workbench] (regression) Workbench menus disappeared afte...
73847 | MAC OSX Safari1.0(V85.5)run on advanced mode ,so it behav...

268 bugs fixed.

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

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

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

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

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

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

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

(c) Copyright IBM Corp. and others 2004