Release 0.9
Last revised July 29, 2009
This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.
Preamble
1. Target Operating Environments
2. Compatibility with Previous Releases
3. Known Issues
4. Running Eclipse
The e4 0.9 release is a technology preview from the Eclipse Project's e4 incubator. The project is making a release available at this early stage to solicit feedback and wider participation in the project. This release is quite unlike the stable, mature releases people have come to expect from the Eclipse project. The software has bugs, and has not been heavily tested for quality, internationalization, usability, performance, or accessibility. Having said that, this release is a preview of some exciting new technology that will make Eclipse-based applications more flexible, easier to program, and interoperable with a wider range of programming languages and runtime environments. We encourage developers to look past the rough edges of this early release to the explore the new underlying technology, try the e4 demos, provide feedback, and participate in its further development.
In order to remain current, each e4 Project release targets reasonably current operating environments.
Most of the e4 Project is "pure" Java code and has no direct dependence on the underlying operating system. The chief dependence is therefore on the Java Platform itself. Portions are targeted to specific classes of operating environments, requiring their source code to only reference facilities available in particular class libraries (e.g. J2ME Foundation 1.0, J2SE 1.3 and 1.4, etc.). In general, the 0.9 release of the Eclipse Project is developed on Java SE 5.
e4 has dependencies on components from other Eclipse projects, notably the Platform project, and the EMF project. While specific version dependencies may specify a wider range, e4 is generally built and tested against the versions contained in the Galileo release train.
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.
e4 also has dependencies on browser technologies such as JavaScript and Flash. The reference platforms listed below show the versions of these technologies that we are developing and testing against.
e4 0.9 is tested and validated on the following reference platforms:
| Reference Platforms |
Microsoft Windows Vista, x86-32, Win32 running (any of):
|
Microsoft Windows XP, x86-32, Win32 running (any of):
|
Red Hat Enterprise Linux 5.0, x86-32, GTK running (any of):
|
Apple Mac OS X 10.5, Universal, Cocoa running:
|
As stated above, we expect that e4 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.
Portions of e4 will be compatible with Eclipse 3.5 (and all earlier 3.x versions). However, compatibility is not a primary focus for this initial release of e4, and there is no firm promise of compatibility between e4 and earlier Eclipse releases of any kind. Compatibility with Eclipse 3.x is anticipated to be a major focus of the subsequent e4 release.
Workspace Compatibility: e4 0.9 will be upwards workspace-compatible with earlier 3.x versions of the Eclipse SDK unless noted. This means that workspaces and projects created with Eclipse SDK 3.5 .. 3.0 can be successfully opened by e4 0.9 and upgraded to an e4 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 e4 0.9 should provide similar upwards compatibility for their hidden and visible workspace metadata created by earlier versions; 0.9 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 e4 0.9 will be unusable with a product based an earlier version of Eclipse. Visible metadata files created (or overwritten) by e4 0.9 will generally be unusable with earlier versions of Eclipse.
Non-compliant usage of API's: All non-API methods and classes, and certainly everything in a package with "internal" in its name, are considered implementation details which may vary between operating environment and are subject to change without notice. Client plug-ins that directly depend on anything other than what is specified in the Eclipse SDK API are inherently unsupportable and receive no guarantees about compatibility within a single release much less with earlier releases. Refer to How to Use the Eclipse API for information about how to write compliant plug-ins.
3.1 General problems
3.1.1 Startup
3.1.2 GCJ
3.1.3 64-bit Java HotSpot(TM) VM
3.2 e4 Compatibility Platform
3.3 e4 Components
3.3.1 XWT
3.3.2 SWT
3.3.3 Declarative Styling
3.4 e4 Demos
Note: Bug numbers refer to the Eclipse project bug database at http://bugs.eclipse.org/bugs/
Here are some common problems that can cause Eclipse not to start:
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)
The Sun VM may hang indefinitely during class loading if it runs out of permanent generation memory. This will cause CPU usage to stay at 100% until the process is ended. See the section Running Eclipse for details on addressing this VM problem.
GCJ is an effort by the GCC team to provide an open source Java compiler and runtime environment to interpret Java bytecode. Unfortunately, the GCJ runtime environment is not an environment that is often tested on by Eclipse developers.
The most common problems surrounding GCJ are:
The workspace's log file is a good place to check to identify whether GCJ is being used or not. Every Eclipse log session is prepended with information about the runtime environment that was used to run Eclipse. The log may include something like the following:
java.fullversion=GNU libgcj 4.2.1 (Debian 4.2.1-5)
If Eclipse does start, one can check which runtime environment is being used to run Eclipse by going to Help > About Eclipse SDK > Installation Details > Configuration. The About dialog itself can also provide other information, the build identifier can be of particular interest as it is tagged by some distributions. This allows the user to identify whether Eclipse was downloaded through the distribution's package management system or directly from the eclipse.org website.
Eg:Build id: M20070212-1330 (Ubuntu version: 3.2.2-0ubuntu3)
The two most common workarounds are:
To download e4, visit the e4 download page:
It is imperative that 64-bit builds are downloaded and used if a 64-bit Java runtime environment has been installed. Below are two sample tarball names of version 3.5.0 of the Eclipse SDK packaged for 32-bit and 64-bit processors.eclipse-SDK-3.5-linux-gtk.tar.gz (32-bit) eclipse-SDK-3.5-linux-gtk-x86_64.tar.gz (64-bit)
To run Eclipse with an alternate Java runtime environment, the path to the Java virtual machine's binary must be identified. With an Eclipse installation from the distribution, altering the $PATH variable to include the path to the alternate Java runtime environment is often not enough as the Eclipse that Linux distributions package often performs a scan internally to pick up GCJ by itself whilst ignoring what's on the $PATH. An example of the terminal's output is shown below:
searching for compatible vm...
testing /usr/lib/jvm/java-7-icedtea...not found
testing /usr/lib/jvm/java-gcj...found
Once the path to the virtual machine's binary has been identified, try running Eclipse with the following command:
./eclipse -vm /path/to/jre/bin/java
For an actual example, it might look something like the following:
./eclipse -vm /usr/lib/jvm/sun-java-6/bin/java
./eclipse -vm /opt/sun-jdk-1.6.0.02/bin/java
If this seems to solve the problem, it is likely that the problem really was related to the use of GCJ as the Java runtime for running Eclipse. The eclipse.ini file located within Eclipse's folder can be altered to automatically pass this argument to Eclipse at startup. An example of its content is presented below:
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
-vm
/opt/sun-jdk-1.6.0.02/bin/java
-vmargs
-Xms40m
-Xmx512m
Note that every argument must be on its own line. More information about the eclipse.ini file can be found at http://wiki.eclipse.org/Eclipse.ini.
If problems persists after downloading an installation of Eclipse from eclipse.org and using a supported Java runtime environment (a list of which may be found above), you can seek further assistance through the newsgroups, the IRC channel, and/or bugzilla.
There is a known issue with the Java HotSpot(TM) 1.6.0 VM compiler which causes eclipse to crash (see Sun bug http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6614100, and Eclipse bug 214092). The crash usually occurs within a VM CompilerThread when attempting to compile the method org.eclipse.core.internal.dtree.DataTreeNode.forwardDeltaWith.
This problem has been addressed in Sun Java 6 update 11, so the simplest resolution is to obtain the latest JRE release for your platform. To work around the issue you can exclude the method org.eclipse.core.internal.dtree.DataTreeNode.forwardDeltaWith from being compiled with the following VM argument:
-XX:CompileCommand=exclude,org/eclipse/core/internal/dtree/DataTreeNode,forwardDeltaWith
This VM argument can be placed in the eclipse.ini file after the -vmargs line like the following:
-startup
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.0.200.v20090306-1900
--launcher.library
plugins/org.eclipse.equinox.launcher_1.0.200.v20090429-1630.jar
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
-vmargs
-XX:CompileCommand=exclude,org/eclipse/core/internal/dtree/DataTreeNode,forwardDeltaWith
-Xms40m
-Xmx256m
There have been reports of other classes that cause the compiler to crash. If all else fails you can disable the compiler with the VM arg "-Xint".
When you shutdown and restart the workbench, any changes you made to the workbench layout are not persisted. The e4 compatibility platform always opens in the default perspective with the default layout. (bug 284473). As a side effect, you will sometimes see errors when closing the workbench, but they won't cause problems.
On Mac OS X, the embedded web UI does not currently work due to a Jetty configuration problem. As a workaround, add "-Dorg.eclipse.equinox.http.jetty.http.port=8080" to the end of the eclipse.ini file. (bug 284433).
When hitting a debug breakpoint, if the source editor has already been open in a non-debug perspective, the duplicate source editor might not appear in the debug perspective or might not get scrolled to the breakpoint location.
This problem should be eliminated once the support for shared model parts is implemented. For details please see bug 284610.
The Outline view is missing its toolbar buttons, and the Synchronize view only opens with two buttons. Closing and then re-opening the Synchronize view after a sync operation will restore its buttons. (bug 284387).
The main menu is available, but support for the main toolbar is not currently hooked up. (bug 269269).
Multi-instance views such as the Console or Properties view cannot be opened or the second view functions incorrectly. Please see bug 279807 for details.
When there is only one perspective open, it cannot be closed. The workaround is to open another perspective before closing the one you no longer want to use (bug 285081).
You can open the Interal Web Browser view, but if you double-click on a file in the Package Explorer or use Open the file will be opened in an external web browser. (bug 284050).
Sometimes if you switch editors by clicking on the tab, focus goes to the tab and you can't type in the editor. The workaround is to <TAB> (which will move focus into the editor) or simply click in the editor. (bug 285001).
3.x themes will not work with the CSS support enabled. They should not be used. Once in this state, the only option is to open in another workspace. (bug 285166).
On Mac OS X, the XWT editor does not currently support Cocoa. The XWT editor can only be used when running on Carbon (bug 282358).
Although there has been some work on porting SWT/BE to both JavaScript/Dojo and Silverlight, the 0.9 release only includes support for the ActionScript/Flex port. Other ports may become available in the future depending on level of interest.
Although the top and bottom border colors of the ETabFolder can be set differently, e.g.
ETabFolder {
border-top-color: rgb(246, 246, 251);
border-bottom-color: rgb(201, 200, 204);
}
The lines don't match up quite right. Thus in practice, you should just use border-color:. However, if you wish to experiment with this, there is a patch in bug 283882 to fix this.
The e4 photo demo doesn't show photo thumbnails immediately after adding adding photos to an album. Selecting another album in the Albums view and then switching back will cause the Thumbnails view to update. For details see bug 285014.
4.1 Running the e4 SDK
4.2 Running the e4 demo applications
4.2.1 Photo demo application
4.2.2 Contacts demo application
4.2.3 SWT Flex examples
4.2.4 Customizing the workbench style
4.2.5 Manipulating the workbench model
4.2.6 e4 RAP integration
4.2.7 e4 XWT integration
After installing the e4 SDK in a directory, you can start the Workbench
by running the Eclipse executable included with the release (you also need a Java SE 5
JRE, not included with the Eclipse SDK). On Windows, the executable file is called eclipse.exe,
and is located in the eclipse sub-directory of the install. If
installed at c:\e4-0.9-win32, the executable is c:\e4-0.9-win32\eclipse\eclipse.exe.
Note: Set-up on most other operating environments is analogous. Special
instructions for Mac OS X are listed below.
By default, Eclipse will allocate up to 256 megabytes of Java heap memory. This should
be ample for all typical development tasks. However, depending on the JRE
that you are running, the number of additional plug-ins you are using, and
the number of files you will be working with, you could conceivably have to increase this amount.
Eclipse allows you to pass arguments directly to the Java VM using the
-vmargs command line argument, which must follow all other Eclipse specific arguments.
Thus, to increase the available heap memory, you would typically use:
eclipse -vmargs -Xmx<memory size>
with the <memory size> value set to greater than
"256M" (256 megabytes -- the default).
When using a Sun VM, you may also need to increase the size of the permanent generation memory. The default maximum is 64 megabytes, but more may be needed depending on your plug-in configuration and use. When the VM runs out of permanent generation memory, it may crash or hang during class loading. This failure is less common when using Sun JRE version 1.5.0_07 or greater. The maximum permanent generation size is increased using the -XX:MaxPermSize=<memory size> argument:
eclipse -vmargs -XX:MaxPermSize=<memory size>
This argument may not be available for all VM versions and platforms; consult your VM documentation for more details.
Note that setting memory sizes to be larger than the amount of available physical memory on your machine will cause Java to "thrash" as it copies objects back and forth to virtual memory, which will severely degrade your performance.
When the Workbench is launched, the first thing you see is a
dialog that allows you to select where the workspace will be located. The
workspace is the directory where your work will be stored.
If you do not specify otherwise, Eclipse creates the workspace in your
user directory.
This workspace directory is used as the default content area for your projects
as well as for holding any required metadata. For shared or multi-workspace
installs you must explicitly specify the location for your workspace using the
dialog (or via the "-data" command line argument).
Here is a typical Eclipse command line:
eclipse -vm c:\jdk1.5.0_07\jre\bin\javaw
Tip: It's generally a good idea to explicitly specify which Java VM to
use when running Eclipse. This is achieved with the "-vm"
command line argument as illustrated above. If you don't use "-vm",
Eclipse will look on the O/S path. When you install other Java-based products,
they may change your path and could result in a different Java VM being used
when you next launch Eclipse.
To create a Windows shortcut to an installed Eclipse:
eclipse.exe in Windows Explorer and use Create
Shortcut on the content menu.Opening this shortcut launches Eclipse. (You can drag the shortcut to the Windows Desktop if you want to keep it in easy reach.)
On Mac OS X, you start Eclipse by double clicking the Eclipse application. If you need to
pass arguments to Eclipse, you'll have to edit the eclipse.ini file
inside the Eclipse application bundle: select the Eclipse application bundle icon while holding down the Control Key.
This will present you with a popup menu. Select "Show Package Contents" in the popup menu.
Locate eclipse.ini file in the Contents/MacOS sub-folder and open it with your favorite text editor to edit the command line options.
On MacOS X you can only launch a UI program more than once if you have separate copies of the program on disk. The reason for this behavior is that every UI application on Mac can open multiple documents, so typically there is no need to open a program twice. Since Eclipse cannot open more than one workspace, this means you have to make a copy of the Eclipse install if you want to open more then one workspace at the same time (bug 139319).
If you need to launch Eclipse from the command line, you can use the symbolic link "eclipse" in the top-level eclipse folder. It refers to the eclipse executable inside the application bundle and takes the same arguments as "eclipse.exe" on other platforms.
On Mac OS X 10.4 and later, you may notice a slow down when working with significant numbers of resources if you allow Spotlight to index your workspace. To prevent this, start System Preferences, select the Spotlight icon, then the Privacy tab, then click the Add button ("+") and find your workspace directory in the dialog that appears.
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.
The e4 compatibility platform includes a special menu item for quickly getting setup to run the e4 example applications. To use it, do the following:
These steps will load the source code of the e4 sample applications into your workspace. To launch and work with the demos, see the following readme sections.
The e4 photo demo is a simple application that illustrates various concepts of the e4 architecture:
Perform the following to install and run the e4 photo demo. Note that steps 1-6 can be skipped if the steps for Loading the example projects above are followed.
The e4 photo demo application will come up. Click Create Album or select File > Create Album. The new album location on disk will be printed to your Eclipse console. Just drop a couple (not too many!) of JPEG photos in that directory, then play with the application. Make sure you find a photo with embedded GPS coordinates - when you select it in the Exif view, the Location view will show where the photo was taken using Google Maps. You can find an example photo with GPS coordinates on bug 263898.
Then, have a look at the Application.xmi file to see how the demo application is configured, and/or look at the source files for the individual pieces (views and command handlers).
The e4 contacts demo is a simple application that illustrates various concepts of the e4 architecture:
Perform the following to install and run the e4 contacts demo. Note that steps 1-6 can be skipped if the steps for Loading the example projects above are followed.
The e4 contacts demo application will come up. Select a different theme from the Theme menu for a demonstration of changing application styling on the fly.
Back in the workbench, view and edit the CSS files under the org.eclipse.e4.demo.contacts/css folder to experiment with different application styling. Browse and edit the Application.xmi file to customize the application model.
The SWT port for Flex consists of the Adobe Flex environment (the ActionScript compiler), the SWT ActionScript development tools plugins (which provides the tools needed to build, launch and debug Java code in a Flash player) and the Eclipse target environment (the running plugins, the SWT port itself and example code).
Setup Flex environment
Setup the Flex tools:
Setup the Eclipse target environment:
Get the demos
For more information on working with e4 SWT, visit the e4 SWT Demos wiki page.
You can experiment with the e4 declarative styling support by manipulating the stylesheet for the e4 SDK itself. If you've downloaded the e4 SDK, you can find it on disk in:
eclipse\plugins\org.eclipse.e4.ui.examples.legacy.workbench_0.9.0.vSomeBuildDate\css\webby.css
Changes in the style sheet will be picked up in the running platform but you need to tell it that the style sheet changed. To do so, click e4 > Reload Style Sheet in the top level menu. This will re-read the style sheet in and update the UI. Thus you can modify the style sheet on disk and then click the menu to live update the workbench look. You don't need to restart Eclipse.
If you decide to create a new CSS file, you''ll need to change the following property in org.eclipse.e4.ui.examples.legacy.workbench/plugin.xml:
<property
name="applicationCSS"
value="platform:/plugin/org.eclipse.e4.ui.examples.legacy.workbench/css/webby.css">
</property>
You can experiment with the e4 modeled workbench by browsing and manipulating the model of the compatibility platform itself. When the compatibility platform is running, select e4 > UI Editor from the top level menu. This opens the e4 workbench model editor. You can browse through the structure of the workbench itself in the top pane. Try finding a perspective or view and changing its name, tooltip, or other properties in the Basic and Advanced tabs at the bottom. Notice how model changes are reflected immediately in the workbench window state underneath!
There is experimental integration available between the Eclipse Rich Ajax Platform (RAP) project and e4. For more details on running e4 on RAP, see the e4 RAP Integration" wiki page. Also see the e4 demos running on RAP here.
This release includes an initial integration between XWT and e4. This integration supports CSS Styling out-of-the-box and provides some facilities for communication between e4 and XWT events, and between e4 contexts and XWT data binding.
XWT versions of the e4 contacts and photo demos are also available. To load these demos, perform the following:
For more details on running e4 with XWT, see the XWT wiki page, and the XWT demos wiki page.