Eclipse Project Release Notes
- Eclipse Project Release Notes
- Target Operating Environments
- Compatibility with Previous Releases
- Known Issues
- General - Startup
- Platform - Ant
- Custom Ant tasks and Ant types must be separate from plug-in library JARs
- XDoclet support from within Eclipse
- Ant Editor code completion based on Ant 1.6.x
- Setting build loggers not supported when debugging Ant builds
- Renaming an External Tool builder set to run during auto-build will cause errors
- Slow typing/saving of the Ant editor with imports that define numerous macrodefs
- Ant 1.8.x reports missing libraries as build failures
- Platform - User Assistance
- Welcome page not displayed properly (Linux/Unix)
- Help browser tool bar buttons do not work for some documents
- Help documents not displayed in a browser or very slow document loading (Windows only)
- Working disconnected from the network (Windows only)
- Using Internet Explorer in offline mode (Windows only)
- Platform - UI
- Dirty state not tracked properly for OLE documents (Windows only)
- OLE document crashes can cause Eclipse to also crash (Windows only)
- Toolbars only containing contributed controls exhibit display errors on Mac/Linux
- Allocating enough memory and solving OutOfMemoryError
- Capabilities and Activities don't affect the menus and toolbars
- Platform - SWT
- Support for macOS 11 (Big Sur)
- Usage of swt.autoScale and GDK_SCALE flag on GTK platforms
- Non-uniform scaling of text vs. icons when using intermediate scaling factors on high-DPI displays
- Eclipse plug-in based on the SWT Browser throws exception
- Eclipse icon is duplicated in task-bar on Windows
- BIDI Segments in Text controls
- Block Selection functionality provided by StyledText is not BIDI aware
- Platform - Install/Update
- Java development tools (JDT)
- Cut, copy, paste not working for linked resources in views showing Java elements
- Java working sets not working correctly for elements from JRE system library container
- Suspend on uncaught exception overrides exception breakpoint location filters
- Running Java programs with non-Latin-1 characters in package or class names
- Cannot run or debug class in a project with GB18030 characters in project name
- Cannot detect installed JRE with GB18030 characters in path name
- Cannot generate Javadoc for packages with GB18030 characters in the name
- Unable to debug stack overflows
- Evaluation limitation
- Missing debug attributes
- Using Hot Code Replace
- Scrapbook
- Debugging over slow connections
- Updating of inspected values
- Stepping over native methods that perform I/O
- Java indexing encounters problems when a folder is used both as a source and a class folder
- Plug-in Development Environment (PDE)
- Feature manifest editor does not preserve all comments
- PDE will not unzip source zips of some plug-ins
- Emacs key bindings do not work in manifest editor fields
- Export of plug-in may silently drop classes
- Compilation errors when exporting projects not stored outside of the workspace
- Headless build needs to be run from a fully qualified path
- Importing in Eclipse application fails if plug-in exists in host workspace
- Reusing a workspace after changing architectures silently breaks PDE models
- Missing @since tag API Tools problems on interface fields containing @noreference tag
- Running Eclipse
- Upgrading Workspace from a Previous Release
- Interoperability with Previous Releases
Target Operating Environments
In order to remain current, each Eclipse Project release targets reasonably current operating environments.
Most of the Eclipse SDK is "pure" Java code and has no direct dependence on the underlying operating system. The chief dependence is therefore on the Java Platform itself. Portions are targeted to specific classes of operating environments, requiring their source code to only reference facilities available in particular class libraries (e.g. J2ME Foundation 1.1, J2SE 1.4, Java 5, etc).
In general, the 4.31 release of the Eclipse Project is developed on Java SE 17 VMs. As such, the Eclipse SDK as a whole is targeted at all modern, desktop Java VMs.
There are many different implementations of the Java Platform running atop a variety of operating systems. We focus our testing on a handful of popular combinations of operating system and Java Platform; these are our reference platforms. Eclipse undoubtedly runs fine in many operating environments beyond the reference platforms we test. However, since we do not systematically test them we cannot vouch for them. Problems encountered when running Eclipse on a non-reference platform that cannot be recreated on any reference platform will be given lower priority than problems with running Eclipse on a reference platform.
Eclipse 4.31 is tested and validated on a number of reference platforms. For the complete list, see Target Environments in the 4.31 Plan.
As stated above, we expect that Eclipse works fine on other current Java VM and OS versions but we cannot flag these as reference platforms without significant community support for testing them.
The Eclipse SDK is designed as the basis for internationalized products. The user interface elements provided by the Eclipse SDK components, including dialogs and error messages, are externalized. The English strings are provided as the default resource bundles.
Latin-1, DBCS, and BiDi locales are supported by the Eclipse SDK on all reference platforms.
The Eclipse SDK supports GB 18030 (level 1), the Chinese code page standard, on Windows, Linux and the Macintosh.
German and Japanese locales are tested.
Compatibility with Previous Releases
Compatibility of Release 4.31 with 4.30
Eclipse 4.31 is compatible with Eclipse 4.30 (and all earlier 4.x and 3.x versions).
API Contract Compatibility: Eclipse SDK 4.31 is upwards contract-compatible with Eclipse SDK 4.30 except in those areas noted in the Eclipse 4.31 Plug-in Migration Guide. Programs that use affected APIs and extension points will need to be ported to Eclipse SDK 4.31 APIs. Downward contract compatibility is not supported. There is no guarantee that compliance with Eclipse SDK 4.31 APIs would ensure compliance with Eclipse SDK 4.30 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 4.31 is upwards binary-compatible with Eclipse SDK 4.30 except in those areas noted in the Eclipse 4.31 Plug-in Migration Guide . Downward plug-in compatibility is not supported. Plug-ins for Eclipse SDK 4.31 will not be usable in Eclipse SDK 4.30. Refer to Evolving Java-based APIs for a discussion of the kinds of API changes that maintain binary compatibility.
Source Compatibility: Eclipse SDK 4.31 is upwards source-compatible with Eclipse SDK 4.30 except in the areas noted in the Eclipse 4.31 Plug-in Migration Guide . This means that source files written to use Eclipse SDK 4.31 APIs might successfully compile and run against Eclipse SDK 4.30 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 4.31 is upwards workspace-compatible with earlier 3.x and 4.x versions of the Eclipse SDK unless noted. This means that workspaces and projects created with Eclipse SDK 4.30, 4.29, 4.28, 4.27, 4.26, 4.25, 4.24, 4.23, 4.22, 4.21, 4.20, 4.19, 4.18, 4.17, 4.16, 4.15, 4.14, 4.13, 4.12, 4.11, 4.10, 4.9, 4.8, 4.7, 4.6, 4.5 and 4.4 can be successfully opened by Eclipse SDK 4.31 and upgraded to a 4.31 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 4.31 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; 4.31 plug-in developers are responsible for ensuring that their plug-ins recognize metadata from earlier versions and process it appropriately. User interface session state may be discarded when a workspace is upgraded. Downward workspace compatibility is not supported. A workspace created (or opened) by a product based on Eclipse 4.31 will be unusable with a product based on an earlier version of Eclipse. Visible metadata files created (or overwritten) by Eclipse 4.31 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 or x-internal in the bundle manifest entry, are considered implementation details which may vary between operating environment and are subject to change without notice. Client plug-ins that directly depend on anything other than what is specified in the Eclipse SDK API are inherently unsupportable and receive no guarantees about compatibility within a single release much less with earlier releases. Refer to How to Use the Eclipse API for information about how to write compliant plug-ins.
Known Issues
Note: Bug numbers refer to the Eclipse project bug database at http://bugs.eclipse.org/bugs/
General - Startup
Installation/Configuration issues that can cause Eclipse to fail start
Here are some common problems that can cause Eclipse not to start:
- As shown above, Eclipse 4.31 requires at least a Java SE 17. Perhaps an older version of the VM is being found in your path. To
explicitly specify which VM to run with, use the Eclipse
-vm
command-line argument. (See also the Running Eclipse section below.) - Eclipse must be installed to a clean directory and not installed over top of a previous installation. If you have done this then please re-install to a new directory. If your workspace is in a child directory of your old installation directory, then see the instructions below on "Upgrading Workspace from a Previous Release".
- Java sometimes has difficulty detecting whether a file system is writable. In particular, the method java.io.File.canWrite() appears to return true in unexpected cases (e.g., using
Windows drive sharing where the share is a read-only Samba drive). The Eclipse runtime generally needs a writable configuration area and as a result of this problem, may erroneously detect the
current configuration location as writable. The net result is that Eclipse will fail to start and depending on the circumstances, may fail to write a log file with any details. To work around
this, we suggest users experiencing this problem set their configuration area explicitly using the
-configuration
command line argument. (bug 67719)
Invalid characters in install directory prevents Eclipse from starting
Eclipse will fail to launch if installed in a directory whose path contains certain invalid characters, including :%#<>"!. The workaround is to install Eclipse in a directory whose path does not contain invalid characters. (bugs 3109 and 17281)
Platform - Ant
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).
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.x
Code completion provided by the Ant editor does not respect the user-specified version of org.eclipse.ant.core plug-in or ANT_HOME. Code completion proposals are mostly based on Ant 1.6.x with some updates to Ant 1.8.3 (bug bug 193046)
Setting build loggers not supported when debugging Ant builds
When debugging Ant builds within Eclipse, setting -logger
as a program argument will be ignored.
Renaming an External Tool builder set to run during auto-build will cause errors
If you rename an existing external tool builder that is configured to run during auto-builds, you will get the following error: Errors during build. Errors running builder "Integrated External Tool Builder" on project <PROJECT_NAME>. The builder launch configuration could not be found. The workaround is to first disable the builder for auto-builds and then rename the builder. (bug 118294)
Slow typing/saving of the Ant editor with imports that define numerous macrodefs
The Ant editor is slow on saving with buildfiles that have <import> declarations of buildfiles that have numerous <macrodef>s. See bug 125117 for a possible workaround
Ant 1.8.x reports missing libraries as build failures
In Ant 1.8.x, if you try to use a task that requires additional libraries and you do not have the libraries on the Ant classpath, the build will now properly report as failed. In previous versions of Ant, the build would still report that it had succeeded even though it actually failed to run any of the tasks from additional bundles. See bug 344518.
For more information on tasks that require additional bundles please refer to the Ant 1.8.2 release notes and the Optional Tasks section in the Ant manual.
Platform - User Assistance
Welcome page not displayed properly (Linux/Unix)
The default Welcome implementation is HTML-based and requires a supported browser in order to work. If no supported browser can be found, Welcome falls back to its Forms-based implementation, which has a different (simpler) appearance. Consult the SWT FAQ for supported browsers and setting up your browser to work with eclipse.
Help browser tool bar buttons do not work for some documents
The Help browser's Print, Synchronize, and Bookmark buttons do not work for pages that are not actually installed with the product. However, you can always use the print command in the browser's context menu to print the page you're reading. (bug 44216)
Help documents not displayed in a browser or very slow document loading (Windows only)
- 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.
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)
Platform - UI
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.
Toolbars only containing contributed controls exhibit display errors on Mac/Linux
Currently there is no way on the Max or Linux platforms to define the height for controls contributed to toolbars, nor will those platforms respect the size
returned by the control's computeSize
method. If you encounter this issue there is currently no truly viable workaround. (bug
183003)
Allocating enough memory and solving OutOfMemoryError
The native launcher checks the JVM but PDE launches simply use java and don't go through the native launchers. The workaround is to add the appropriate JVM arg to your launch config or to the Preferences > Java > Installed JREs. (bug 339763)
Capabilities and Activities don't affect the menus and toolbars
Capabilities used to hide GUI elements like menu entries work for commands and individual actionSet entries, but Capabilities have not been fully implemented. (bug 359778)
Platform - SWT
Support for macOS 11 (Big Sur)
Usage of swt.autoScale and GDK_SCALE flag on GTK platforms
Non-uniform scaling of text vs. icons when using intermediate scaling factors on high-DPI displays
Eclipse plug-in based on the SWT Browser throws exception
The SWT Browser widget uses a platform-specific web browser to render HTML. The org.eclipse.swt.SWTError exception ("No more handles") is thrown on platforms that don't meet the requirements for running the Browser widget. Supported platforms and prerequisites are listed on the SWT FAQ item "Which platforms support the SWT Browser?".
Eclipse icon is duplicated in task-bar on Windows
Workaround is to pin the launched eclipse application and not the launcher, for more details, refer bug 314805
BIDI Segments in Text controls
BIDI Segments in Text controls only work on Windows and GTK. (bug 388578)
Block Selection functionality provided by StyledText is not BIDI aware
When the orientation of characters under the left and right edges of the block selection rectangle are not the same, the actual selection ranges (in memory) differ from the visual representation of the selection. (bug 277929)
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
Connection cannot be found after initially missing
If a connection initially fails due to a network problem, the connection may continue to fail even when the network problem is fixed. In order to establish the connection you must exit and restart Eclipse. (bug 9295)
Received broken pipe signal" error from server
Eclipse sometimes performs multiple commands within a single connection to the server. This may cause problems with CVS servers that are running server scripts in response to certain commands. (bugs 23575 and 23581)
Terminated with fatal signal 10" error from server
There is a bug in the CVS server related to some compression levels. If you get this error, changing the compression level on the CVS preference page may help. (bug 15724)
error using ext connection method
There are a few situations that can result in an "Unknown response" error messages when using the ext connection method. One situation involves using an external communications client (e.g. rsh or ssh) that adds CRs to the communications channel (bug 21180). Another involves Eclipse not properly reading the stderr output of the external communications tool. (bug 11633)
A disabled CVS capability may not be auto-enabled in existing workspaces
New in 3.0 is the ability to disable capabilities and the CVS support in Eclipse can be disabled. However, for backwards compatibility the CVS capability is auto-enabled in existing workspaces that already contain CVS projects. The auto-enabling function may not run if the team support plugin is not loaded at startup. (bug 66977)
Builder output files may appear as changed
Enabling GNOME proxy support
eclipse -Dorg.eclipse.core.net.enableGnome
Platform - Install/Update
Manually installing features and plug-ins on a FAT file system (Windows only)
eclipse.exe -clean
Connecting to untrusted sites using https
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).
Java development tools (JDT)
Cut, copy, paste not working for linked resources in views showing Java elements
The cut, copy, and paste actions do not work for linked files and folders appearing in views that show Java elements, including the Package Explorer. The workaround is to use these actions from the Navigator view instead. (bug 34568)
Java working sets not working correctly for elements from JRE system library container
Applying a working set consisting entirely of elements from the JRE System library container as a filter to the packages view might result in an empty Package Explorer. (bug 30442)
Suspend on uncaught exception overrides exception breakpoint location filters
Exception breakpoints can be configured with location filters (inclusive and exclusive). When an unchecked exception is configured to not suspend execution in a specific class, execution will still suspend when the user preference to suspend on uncaught exceptions is on. (bug 66770)
Running Java programs with non-Latin-1 characters in package or class names
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)
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
32215)
Unable to debug stack overflows
If a debug session suspends on a java.lang.StackOverflowError
exception (due to an exception breakpoint), the debugger may not be able to retrieve any
debug information from the target JVM. As well, the debugger may not be able to reliably interact with the target JVM past this point. (bug
19217)
Evaluation limitation
The debugger uses threads in the target JVM to perform evaluations (both explicit evaluations that the user requests, and implicit evaluations such as toString()
invocations in the Variables view). The Java Debug Interface (JDI) requires that the thread in which an evaluation is performed be suspended by a user event (that is, a breakpoint or step
request). Evaluations cannot be performed on threads suspended by the suspend action. As well, when a breakpoint is configured to suspend the JVM rather than just the individual thread, the
threads which did not encounter the breakpoint are not in a valid state to perform an evaluation. When an evaluation is attempted in a thread that is not in a valid state to perform an
evaluation, an error message will appear to the effect of "Thread must be suspended by step or breakpoint to perform method invocation". (bug
34440)
Missing debug attributes
Using Hot Code Replace
Scrapbook
Setting a breakpoint inside a scrapbook page is not supported.
Debugging over slow connections
Updating of inspected values
Stepping over native methods that perform I/O
Java indexing encounters problems when a folder is used both as a source and a class folder
Java indexing encounters problems when a folder is used both as a source folder in a project and as a class folder in another project. Hence, when this peculiar setup is used, the Java Search might miss matches located in such a folder. To avoid this kind of problem, it is strongly advised to use different folders for sources and binary classes. (bug 309903)
Plug-in Development Environment (PDE)
Feature manifest editor does not preserve all comments
When a non-source page of the feature manifest editor is used, PDE will convert changes back into XML by regenerating the file. Although the overall content and most of the comments are preserved, some comments may be lost. (bug 59502)
PDE will not unzip source zips of some plug-ins
In the plug-in import wizard, when you choose to import plug-ins as "projects with source folders", PDE will not unzip the source for the org.apache.ant. This is because the source ZIPs contains code that will not compile when unzipped as it requires additional JARs that are not part of the SDK. To avoid the creation of plug-in projects that won't compile, PDE will import these plug-ins as binary and attach source, so you would still be able to read the source, you just won't be able to modify it. Also, PDE will not unzip the source for the org.eclipse.swt plug-ins. In this case, it is because, when shipped, the swt code is spread across a plug-in and a fragment, and when unzipped, it will require circular dependencies between the plug-in and fragment projects. These circular dependencies are at minimum marked as warnings by the JDT compiler and may result in unpredictable build behavior. Therefore, PDE always imports org.eclipse.swt as binary with source attached. (bug 66314)
Emacs key bindings do not work in manifest editor fields
Non-default key bindings currently do not work in fields on non-source pages of the PDE manifest editors. (bug 19482)
Export of plug-in may silently drop classes
When exporting a plug-in using the plug-in, feature or product wizards, some classes might be dropped from the resulting archive if their fully qualified name is too long. This typical path limitation can be worked around by creating the jar of the problematic plug-in by using the Jar export wizard. (bug 97150)
Compilation errors when exporting projects not stored outside of the workspace
When exporting multiple plug-ins and one is stored outside of the workspace, compile errors occurs on export. To work around the problem, you can either export the plug-ins one by one, or change their location. (bug 98579)
Headless build needs to be run from a fully qualified path
When running a headless build using the scripts provided by pde build, the properties builder
and buildDirectory
must refer to a fully
qualified path. (bug
139554)
Importing in Eclipse application fails if plug-in exists in host workspace
When running an Eclipse application (self-hosting) importing plug-ins will not work correctly if the plug-in being imported exists in the host Eclipse's workspace. This is because PDE modifies the target platform of the application to point at the running plug-ins from the host (target weaving). This also affects the PDE test suite. (bug 294005)
Reusing a workspace after changing architectures silently breaks PDE models
If a workspace is reused on a machine with a different architecture, the PDE models used to build plug-ins may silently fail. To work around this problem, delete the metadata in <workspace>/.metadata/.plugins/org.eclipse.pde.core. (bug 350172)
Missing @since tag API Tools problems on interface fields containing @noreference tag
The Eclipse platform 4.6 release will not allow the API Tools @noreference tag on interface fields. This was changed because all interface fields are constant fields that cannot support the @noreference restriction. The tag was allowed in previous releases and this usage will now be considered an API change requiring a @since tag. It is recommended that you create an API Tools filter for the missing @since tag problem. This filter can be removed as soon as the API baseline has been regenerated. (bug 402393)
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 Java SE 17 JRE,
not included with the Eclipse SDK). With Oomph users can install required JRE courtesy of JustJ. On Windows, the executable file is called eclipse.exe , and is located in the eclipse
sub-directory of the install. If installed at
c:\eclipse-SDK-4.31-win64
, the executable is c:\eclipse-SDK-4.31-win64\eclipse\eclipse.exe
. Note: Set-up on most other operating environments is analogous.
Special instructions for Mac OS X are listed
below.
Allocating enough memory and solving OutOfMemoryErrors
with the <memory size>
value set to greater than "1024M" (1024 megabytes -- the default).
Selecting a workspace
Specifying the Java virtual machine
Here is a typical Eclipse command line:
To create a Windows shortcut to an installed Eclipse:
- Navigate to
eclipse.exe
in Windows Explorer and use Create Shortcut on the content menu. - Select the shortcut and edit its Properties. In the Target: field append the command line arguments.
Mac OS X
On MacOS X you can only launch a UI program more than once if you have separate copies of the program on disk. The reason for this behavior is that every UI application on Mac can open multiple documents, so typically there is no need to open a program twice. Since Eclipse cannot open more than one workspace, this means you have to make a copy of the Eclipse install if you want to open more then one workspace at the same time (bug 139319).
If you need to launch Eclipse from the command line, you can create a symbolic link such as "eclipse". It should point to the eclipse executable inside the application bundle and takes the same arguments as "eclipse.exe" on other platforms.
On Mac OS X 10.4 and later, you may notice a slow down when working with significant numbers of resources if you allow Spotlight to index your workspace. To prevent this, start System Preferences, select the Spotlight icon, then the Privacy tab, then click the Add button ("+") and find your workspace directory in the dialog that appears.
Shared Install
The startup speed of a shared install can be improved if proper cache information is stored in the shared install area. To achieve this, after unzipping Eclipse distribution, run Eclipse once with the "-initialize" option from an account that has a write access to the install directory. See shared installs in Eclipse Help for more information.
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:
- Find the workspace directory used by your old version of Eclipse. Typically this is located inside the directory in which Eclipse was installed in a sub-directory
called "
workspace
". If you are using a shortcut or script to launch Eclipse, then it will be under the current working directory of that shortcut or script in a sub-directory called "workspace". For Windows users, this is specified by the "Start in:" argument in your shortcut properties. - Copy this workspace directory to a new, empty location outside of any Eclipse install directory.
- Install the new version of Eclipse in a new location, separate from any old version of Eclipse.
- If you had installed additional features and plug-ins into your old Eclipse, you should re-install them in the new Eclipse.
- 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"
- Optionally copy your workspace directory to a new, empty location outside of any Eclipse install directory as a backup.
- Install the new version of Eclipse in a new location, separate from any old versions of Eclipse.
- If you had installed additional features and plug-ins into your old Eclipse, you should re-install them in the new Eclipse.
- 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 use User Libraries or classpath containers that contain JARs referencing other libraries via Class-Path in the MANIFEST.MF
- Add the system property (
-DresolveReferencedLibrariesForContainers=true
) to the-vmargs
list on start-up, or - Manually add the referenced JARs to the User Library or to the project.
Dropped in bundles may not resolve after upgrade
Interoperability with Previous Releases
Interoperability of Release 4.31 with previous releases
Sharing projects between heterogeneous Eclipse 4.31 and 4.30
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 4.31 while others are working in Eclipse 3.x, there are no such guarantees. This section provides advice for what to do and not to do. It addresses the specific issues with the Eclipse SDK.
The typical failure mode is noticed by the 4.31 user. 4.30 metadata is lost when a 4.31 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 4.31 creates or modifies a project in a way that results in changes to a shared metadata file that rely on 4.31-specific information. The user then commits the updated project files, including the shared metadata file, to the shared repository.
- Another user working in Eclipse 4.30 or earlier shares this project from the same repository. The 4.31-specific information in the shared metadata file is not understood by Eclipse 4.30, 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 4.31-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 4.31 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.
- Virtual folders - Eclipse 4.31 supports a notion of virtual folders that did not exist in Eclipse 3.5 or earlier. If such virtual folders are created in 4.31, and the project is subsequently loaded into an Eclipse 3.5 or earlier workspace, these folders will not be recognized. Recommendation: avoid creating virtual folders where project compatibility with Eclipse 3.5 or earlier is required.
- Resource filters - Eclipse 4.31 supports a notion of resource filters that did not exist in Eclipse 3.5 or earlier. If such filters are added to resources in 4.31, and the project is subsequently loaded into an Eclipse 3.5 or earlier workspace, these filters will not be recognized. Recommendation: avoid creating resource filters where project compatibility with Eclipse 3.5 or earlier is required.
- Predefined path variables - Eclipse 4.31 supports a set of built in path variables that can be used as the basis for linked resource locations. Such variables will not be defined automatically in Eclipse 3.5 or earlier. If compatibility with 3.5 or earlier workspace is required, users on 3.5 or earlier workspaces will need to define such path variables manually.
Using Eclipse 4.31 to develop plug-ins that work in Eclipse 4.30
Sun, Solaris, Java and all Java-based trademarks are trademarks of Oracle Corporation. in the United States, other countries, or both.
IBM is a trademark of International Business Machines Corporation in the United States, other countries, or both.
Microsoft, Windows, Windows NT, Vista, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
Apple and Mac OS are trademarks of Apple Computer, Inc., registered in the U.S. and other countries.
Other company, product, and service names may be trademarks or service marks of others.
(c) Copyright Eclipse Contributors 2009, 2024