blob: e0862b4e3112bf78fc0545c882754b54c5fe05d5 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Eclipse e4 Project Release Notes 0.9</title>
</head>
<body>
<h1>Eclipse e4 Project Release Notes</h1>
<p>Release 0.9<br>
Last revised July 29, 2009</p>
<p align="left"><strong>This software is OSI Certified Open Source Software.<br>
OSI Certified is a certification mark of the Open Source Initiative.&nbsp;</strong></p>
<blockquote>
<p align="left"><a href="#Preamble">Preamble</a><br>
<a href="#TargetOperatingEnvironments">1. Target Operating
Environments</a><br>
<a href="#Compatibility">2. Compatibility with Previous Releases</a><br>
<a href="#Known Issues">3. Known Issues</a><br>
<a href="#Running Eclipse">4. Running Eclipse</a><br>
</p>
</blockquote>
<h2><a name="Preamble"/>Preamble</h2>
<p>
The e4 0.9 release is a technology preview from the
<a href="http://eclipse.org/eclipse">Eclipse Project</a>'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 <a href="#R-Demos">e4 demos</a>,
provide feedback, and participate in its further development.
</p>
<h2>1. <a name="TargetOperatingEnvironments"></a>Target Operating Environments</h2>
<p>In order to remain current, each e4 Project release targets reasonably current
operating environments.</p>
<p>Most of the e4 Project is &quot;pure&quot; 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.</p>
<p>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.</p>
<p>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 <em>reference
platforms</em>. 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.</p>
<p>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.</p>
<p>e4 0.9 is tested and validated on the following reference platforms:</p>
<center>
<table border="1" cellpadding="2" cellspacing="2" width="80%" summary="Reference Platforms">
<tbody>
<tr align="center">
<td><b>Reference Platforms</b></td>
</tr>
<tr>
<td><b>Microsoft Windows Vista, x86-32, Win32</b> running (any of):
<ul>
<li>Sun Java Standard Edition 5 Update 14 for Microsoft Windows</li>
<li>IBM 32-bit SDK for Windows, Java 2 Technology Edition 5.0, SR6b</li>
</ul></td>
</tr>
<tr>
<td><b>Microsoft Windows XP, x86-32, Win32</b> running (any of):
<ul>
<li>Sun Java Standard Edition 5 Update 14 for Microsoft Windows</li>
<li>IBM 32-bit SDK for Windows, Java 2 Technology Edition 5.0, SR6b</li>
</ul></td>
</tr>
<tr>
<td><b>Red Hat Enterprise Linux 5.0, x86-32, GTK</b> running (any of):
<ul>
<li>Sun Java Standard Edition 5 Update 14 for Linux x86</li>
<li>IBM 32-bit SDK for Linux on Intel architecture, Java 2 Technology Edition 5.0, SR6b</li>
</ul></td>
</tr>
<tr>
<td><b>Apple Mac OS X 10.5, Universal, Cocoa</b> running:
<ul>
<li>Apple Java for Mac OS X 10.5, Update 1</li>
</ul></td>
</tr>
</tbody>
</table>
</center>
<p>As stated above, <i>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.</i></p>
<h2>2. <a name="Compatibility"></a>Compatibility with Previous Releases</h2>
<h3>Compatibility of e4 0.9 with previous Eclipse project releases</h3>
<p>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.
</p>
<p><strong>Workspace Compatibility:</strong> 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. </p>
<p><strong>Non-compliant usage of API's</strong>: All non-API methods and classes,
and certainly everything in a package with &quot;internal&quot; 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
<a href="http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html">
<em>How to Use the Eclipse API</em>
</a> for information about how to write compliant plug-ins. </p>
<h2>3. <a name="Known Issues"></a> Known Issues</h2>
<blockquote>
<a href="#I-General">
3.1 General problems</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#I-General-Startup">3.1.1 Startup</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#I-General-GCJ">3.1.2 GCJ</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#I-General-64bitJava">3.1.3 64-bit Java HotSpot(TM) VM</a><br>
<a href="#I-Platform">3.2 e4 Compatibility Platform</a><br>
<a href="#I-Components">3.3 e4 Components</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#I-Components-XWT">3.3.1 XWT</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#I-Components-SWT">3.3.2 SWT</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#I-Components-Styling">3.3.3 Declarative Styling</a><br>
<a href="#I-Demos">3.4 e4 Demos</a><br>
</blockquote>
<p>Note: Bug numbers refer to the Eclipse project bug database at <a href="http://dev.eclipse.org/bugs/">http://bugs.eclipse.org/bugs/</a></p>
<h3>3.1 <a name="I-General">General problems</a></h3>
<h3>3.1.1 <a name="I-General-Startup">General - Startup</a></h3>
<h4>Installation/Configuration issues that can cause Eclipse to fail start</h4>
<p>Here are some common problems that can cause Eclipse not to start:</p>
<ul>
<li>As shown <a href="#TargetOperatingEnvironments">above</a>, Eclipse e4 0.9 requires
at least a Java SE 5 VM. Perhaps an older version of the VM is being found in
your path. To explicitly specify which VM to run with, use the Eclipse <tt>-vm</tt>
command-line argument. (See also the <a href="#Running Eclipse">Running Eclipse</a>
section below.)</li>
<li>
Running Eclipse on Gentoo Linux may result in the following error message:
<div style="margin-left: 40px;">
<tt>* run-java-tool is not available for sun-jdk-1.6 on i686<br>* IMPORTANT: some Java tools are not available on some VMs on some architectures</tt>
</div>
If this occurs, start Eclipse by specifying a -vm argument, either
specify the path to a java vm or use: <tt>eclipse -vm `java-config</tt>
--java` (bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=176021">176021</a>)</li>
<li>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 "<a href="#upgrading">Upgrading Workspace from a
Previous Release"</a>.</li>
<li>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 <tt>-configuration</tt> command
line argument. (bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=67719">67719</a>)</li>
</ul>
<h4><b>Invalid characters in install directory prevents Eclipse from starting</b></h4>
<p>Eclipse will fail to launch if installed in a directory whose path
contains certain invalid characters, including :%#&lt;&gt;&quot;!. The
workaround is to install Eclipse in a directory whose path does not contain
invalid characters. (bugs <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=3109">3109</a>
and <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=17281">17281</a>)</p>
<h4>Hanging during class loading when out of permanent generation memory</h4>
<p>
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 <a href="#Running Eclipse">Running Eclipse</a> for details
on addressing this VM problem.
</p>
<h3>3.1.2 <a name="I-General-GCJ">General - GCJ</a></h3>
<p>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.</p>
<p>The most common problems surrounding GCJ are:</p>
<ul>
<li>Eclipse does not start at all</li>
<li>Eclipse throws a 'java.lang.ClassNotFoundException: org.eclipse.core.runtime.Plugin' that can be found in the logs (located in
workspace/.metadata/.log)</li>
</ul>
<p>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:</p>
<code>java.fullversion=GNU libgcj 4.2.1 (Debian 4.2.1-5)</code>
<p>If Eclipse does start, one can check which runtime environment is being used to
run Eclipse by going to <b>Help &gt; About Eclipse SDK &gt; Installation Details &gt; Configuration</b>. The
<b>About</b> 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.</p>
Eg: <code>Build id: M20070212-1330 (Ubuntu version: 3.2.2-0ubuntu3)</code>
<p>The two most common workarounds are:</p><ul>
<li>download the Eclipse binary from eclipse.org directly</li>
<li>run Eclipse using an alternate Java runtime environment</li></ul>
<p>To download e4, visit the e4 download page:</p><ul>
<li><a href="http://download.eclipse.org/e4/downloads/">http://download.eclipse.org/e4/downloads/</a></li>
</ul>
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.
<pre>eclipse-SDK-3.5-linux-gtk.tar.gz (32-bit)
eclipse-SDK-3.5-linux-gtk-x86_64.tar.gz (64-bit)</pre>
<p>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:</p>
<code>searching for compatible vm...<br>
testing /usr/lib/jvm/java-7-icedtea...not found<br>
testing /usr/lib/jvm/java-gcj...found</code>
<p>Once the path to the virtual machine's binary has been identified, try running
Eclipse with the following command:</p>
<code>./eclipse -vm /path/to/jre/bin/java</code>
<p>For an actual example, it might look something like the following:</p>
<code>./eclipse -vm /usr/lib/jvm/sun-java-6/bin/java<br>
./eclipse -vm /opt/sun-jdk-1.6.0.02/bin/java</code>
<p>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:</p>
<code>-showsplash<br>
org.eclipse.platform<br>
--launcher.XXMaxPermSize<br>
256m<br>
-vm<br>
/opt/sun-jdk-1.6.0.02/bin/java<br>
-vmargs<br>
-Xms40m<br>
-Xmx512m</code>
<p>Note that every argument must be on its own line. More information about the
eclipse.ini file can be found at <a href="http://wiki.eclipse.org/Eclipse.ini">http://wiki.eclipse.org/Eclipse.ini</a>.</p>
<p>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 <a href="#TargetOperatingEnvironments">above</a>),
you can seek further assistance through the <a href="http://www.eclipse.org/newsgroups/">newsgroups</a>,
the IRC <a href="irc://irc.freenode.net/#eclipse">channel</a>,
and/or <a href="https://bugs.eclipse.org/bugs/">bugzilla</a>.
</p>
<h3>3.1.3 <a name="I-General-64bitJava">General - 64-bit Java HotSpot(TM) VM</a></h3>
<p>
There is a known issue with the Java HotSpot(TM) 1.6.0 VM compiler which causes eclipse to
crash (see Sun bug <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6614100">http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6614100</a>,
and Eclipse bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=214092">214092</a>).
The crash usually occurs within a VM CompilerThread when attempting to compile the method org.eclipse.core.internal.dtree.DataTreeNode.forwardDeltaWith.
</p>
<p>
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:
</p>
<code>
-XX:CompileCommand=exclude,org/eclipse/core/internal/dtree/DataTreeNode,forwardDeltaWith
</code>
<p>
This VM argument can be placed in the eclipse.ini file after the -vmargs line like the following:
</p>
<code>
-startup<br>
plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.0.200.v20090306-1900<br>
--launcher.library<br>
plugins/org.eclipse.equinox.launcher_1.0.200.v20090429-1630.jar<br>
-showsplash<br>
org.eclipse.platform<br>
--launcher.XXMaxPermSize<br>
256m<br>
-vmargs<br>
-XX:CompileCommand=exclude,org/eclipse/core/internal/dtree/DataTreeNode,forwardDeltaWith<br>
-Xms40m<br>
-Xmx256m<br>
</code>
<p>
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 &quot;-Xint&quot;.
</p>
<h3>3.2 <a name="I-Platform">e4 Compatibility Platform</a></h3>
<h4>Workbench layout is not restored</h4>
<p>
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 <a href="https://bugs.eclipse.org/284473">284473</a>). As a side effect, you
will sometimes see errors when closing the workbench, but they won't cause problems.
</p>
<h4>Web UI does not work on Mac OS X</h4>
<p>
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 <a href="https://bugs.eclipse.org/284433">284433</a>).
</p>
<h4>Debugging with multiple copies of a source editor open</h4>
<p>
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.
</p>
<p>
This problem should be eliminated once the support for shared model parts is
implemented. For details please see bug <a href="https://bugs.eclipse.org/284610">284610</a>.
</p>
<h4>Views have missing toolbar buttons</h4>
<p>
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 <a href="https://bugs.eclipse.org/284387">284387</a>).
</p>
<h4>No main toolbar</h4>
<p>
The main menu is available, but support for the main toolbar is not currently hooked up.
(bug <a href="https://bugs.eclipse.org/269269">269269</a>).
</p>
<h4>Cannot open second Console or Properties views</h4>
<p>
Multi-instance views such as the Console or Properties view cannot be opened
or the second view functions incorrectly. Please see bug
<a href="https://bugs.eclipse.org/279807">279807</a> for details.
</p>
<h4>Cannot close the last perspective</h4>
<p>
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 <a href="https://bugs.eclipse.org/285081">285081</a>).
</p>
<h4>Cannot open a file in the internal web browser editor</h4>
<p>
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 <a href="https://bugs.eclipse.org/284050">284050</a>).
</p>
<h4>Cannot type in a editor sometimes after clicking on a tab</h4>
<p>
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 &lt;TAB&gt; (which will move
focus into the editor) or simply click in the editor.
(bug <a href="https://bugs.eclipse.org/285001">285001</a>).
</p>
<h4>Changing theme in the Appearance Preferences prevents workspace startup</h4>
<p>
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 <a href="https://bugs.eclipse.org/285166">285166</a>).
</p>
<h3>3.3 <a name="I-Components">e4 Components</a></h3>
<h3>3.3.1 <a name="I-Components-XWT">XWT</a></h3>
<h4>XWT Editor does not support Cocoa</h4>
<p>
On Mac OS X, the XWT editor does not currently support Cocoa. The XWT editor can
only be used when running on Carbon (bug <a href="https://bugs.eclipse.org/282358">282358</a>).
</p>
<h3>3.3.2 <a name="I-Components-SWT">SWT</a></h3>
<h4>SWT/BE only available on Flex</h4>
<p>
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.
</p>
<h3>3.3.3 <a name="I-Components-Styling">Declarative Styling</a></h3>
<h4>ETabFolder body / tab keylines don't line up</h4>
<p>
Although the top and bottom border colors of the ETabFolder can be set
differently, e.g.
</p>
<code>
&nbsp;&nbsp;ETabFolder {<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;border-top-color: rgb(246, 246, 251);<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;border-bottom-color: rgb(201, 200, 204);<br>
&nbsp;&nbsp;}<br>
</code>
<p>
The lines don't match up quite right. Thus in practice, you should just use
<tt>border-color:</tt>. However, if you wish to experiment with this, there is a patch
in bug <a href="https://bugs.eclipse.org/283882">283882</a> to fix this.
</p>
<h3>3.4 <a name="I-Demos">e4 Demos</a></h3>
<h4>Photo demo thumbnails view doesn't update when photos are added</h4>
<p>
The e4 photo demo doesn't show photo thumbnails immediately after adding adding
photos to an album. Selecting another album in the <b>Albums</b> view and then
switching back will cause the <b>Thumbnails</b> view to update. For details see
bug <a href="https://bugs.eclipse.org/285014">285014</a>.
</p>
<h2>4. <a name="Running Eclipse">Running Eclipse</a></h2>
<blockquote>
<a href="#R-General">4.1 Running the e4 SDK</a><br>
<a href="#R-Demos">4.2 Running the e4 demo applications</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-Photo">4.2.1 Photo demo application</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-Contacts">4.2.2 Contacts demo application</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-Flex">4.2.3 SWT Flex examples</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-CSS">4.2.4 Customizing the workbench style</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-Model">4.2.5 Manipulating the workbench model</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-RAP">4.2.6 e4 RAP integration</a><br>
&nbsp;&nbsp;&nbsp;&nbsp; <a href="#R-Demos-XWT">4.2.7 e4 XWT integration</a><br>
</blockquote>
<h3>4.1 <a name="R-General">Running the e4 SDK</a></h3>
<p>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 <samp>eclipse.exe</samp>,
and is located in the <code>eclipse</code> sub-directory of the install. If
installed at <code>c:\e4-0.9-win32</code>, the executable is <code>c:\e4-0.9-win32\eclipse\eclipse.exe</code>.
<b>Note:</b> Set-up on most other operating environments is analogous. Special
instructions for Mac OS X are listed <a href="#macosx">below</a>.</p>
<h3>Allocating enough memory and solving OutOfMemoryErrors</h3>
<p>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
<code>-vmargs</code> command line argument, which must follow all other Eclipse specific arguments.
Thus, to increase the available heap memory, you would typically use:</p>
<blockquote>
<p><code>eclipse -vmargs -Xmx&lt;memory size&gt;</code></p>
</blockquote>
<p>with the <code>&lt;memory size&gt;</code> value set to greater than
&quot;256M&quot; (256 megabytes -- the default).
</p>
<p>
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=&lt;memory size&gt; argument:</p>
<blockquote>
<p><code>eclipse -vmargs -XX:MaxPermSize=&lt;memory size&gt;</code></p>
</blockquote>
<p>This argument may not be available for all VM versions and platforms; consult your VM documentation
for more details.
</p>
<p>
Note that setting memory sizes to be larger than the amount of available physical
memory on your machine will cause Java to &quot;thrash&quot; as it copies objects
back and forth to virtual memory, which will severely degrade your performance.
</p>
<h3>Selecting a workspace</h3>
<p>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 &quot;<code>-data</code>&quot; command line argument).</p>
<h3>Specifying the Java virtual machine</h3>
<p>Here is a typical Eclipse command line:&nbsp;</p>
<blockquote>
<p><code>eclipse -vm c:\jdk1.5.0_07\jre\bin\javaw</code></p>
</blockquote>
<p><i>Tip:</i> It's generally a good idea to explicitly specify which Java VM to
use when running Eclipse. This is achieved with the &quot;<code>-vm</code>&quot;
command line argument as illustrated above. If you don't use &quot;<code>-vm</code>&quot;,
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.</p>
<p>To create a Windows shortcut to an installed Eclipse:</p>
<ol>
<li>Navigate to <code>eclipse.exe</code> in Windows Explorer and use Create
Shortcut on the content menu.</li>
<li>Select the shortcut and edit its Properties. In the Target: field append
the command line arguments.</li>
</ol>
<p>Opening this shortcut launches Eclipse. (You can drag the shortcut to the
Windows Desktop if you want to keep it in easy reach.)</p>
<h3><a name="macosx">Mac OS X</a></h3>
<p>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 <code>eclipse.ini</code> 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 &quot;Show Package Contents&quot; in the popup menu.
Locate <code>eclipse.ini</code> file in the <code>Contents/MacOS</code> sub-folder and open it with your favorite text editor to edit the command line options.
</p>
<p>
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 <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=139319">139319</a>).
</p>
<p>If you need to launch Eclipse from the command line, you can use the symbolic link &quot;eclipse&quot; in the
top-level eclipse folder. It refers to the eclipse executable inside the application bundle and takes
the same arguments as &quot;eclipse.exe&quot; on other platforms.
</p>
<p>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
(&quot;+&quot;) and find your workspace directory in the dialog that appears.</p>
<h3><a name="SharedInstall">Shared Install</a></h3>
<p>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 &quot;-initialize&quot;
option from an account that has a write access to the install directory.</p>
<h3>4.2 <a name="R-Demos">Running the e4 demo applications</a></h3>
<h4 id="R-Demos-Loading">Loading the example projects</h4>
<p>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:
</p>
<ol>
<li>Start the e4 compatibility platform.</li>
<li>Select <b>e4 &gt; Generate e4 Example Project</b> from the top level menu.</li>
<li>A project called <tt>org.eclipse.e4.examples.psf</tt> will be created. Select the
file <tt>e4-examples.psf</tt> in this project, and click <b>Import Project Set...</b>
in the context menu.</li>
<li>If prompted for a username/password, enter a username of &quot;anonymous&quot;
and leave the password field blank.</li>
</ol>
<p>
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.
</p>
<h3>4.2.1 <a name="R-Demos-Photo">Photo demo application</a></h3>
<p>
The e4 photo demo is a simple application that illustrates various concepts of the e4
architecture:
</p>
<ul>
<li>Injection of services in views, making view implementations much simpler</li>
<li>Alternate workbench layout using a customized e4 workbench model.</li>
<li>Custom view presentation using CSS</li>
</ul>
<p>
Perform the following to install and run the e4 photo demo. Note that steps 1-6 can
be skipped if the steps for <a href="#R-Demos-Loading">Loading the example projects</a>
above are followed.
</p>
<ol>
<li>Start the e4 compatibility platform with an empty workspace directory.</li>
<li>Select <b>File &gt; Import...</b> and select <b>CVS &gt; Projects from CVS</b>, click <b>Next</b>.</li>
<li>Enter the e4 repository information. Host: dev.eclipse.org, Repository path: /cvsroot/eclipse, User: anonymous, Connection type: pserver.</li>
<li>Click <b>Next</b> and select the second option, <b>Use an existing module</b>.</li>
<li>Drill down as follows: <b>e4 &gt; org.eclipse.e4.ui &gt; examples</b> and select <b>org.eclipse.e4.demo.e4photo</b>. Click <b>Next</b>.</li>
<li>Important: Do not click Finish just yet. Advance to the last wizard page using <b>Next</b>, then click <b>Refresh Tags</b>. Select <b>R0_9</b> and click <b>Finish</b>.</li>
<li>This will check out one project into your workspace. Expand the project in the <b>Package Explorer</b> and open the e4photo.product file.</li>
<li>Click on the link <b>Launch an Eclipse Application</b> at the bottom left of the e4photo.product file editor.</li>
</ol>
<p>
The e4 photo demo application will come up. Click <b>Create Album</b> or select <b>File &gt; Create Album</b>.
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 <b>Exif</b> view, the <b>Location</b> view will show where the photo was
taken using Google Maps. You can find an example photo with GPS coordinates on bug <a href="https://bugs.eclipse.org/263898">263898</a>.
</p>
<p>
Then, have a look at the <tt>Application.xmi</tt> file to see how the demo application is configured,
and/or look at the source files for the individual pieces (views and command handlers).
</p>
<h3>4.2.2 <a name="R-Demos-Contacts">Contacts demo application</a></h3>
<p>
The e4 contacts demo is a simple application that illustrates various concepts of the e4
architecture:
</p>
<ul>
<li>Customizing the look and feel using CSS</li>
<li>Product branding</li>
<li>Data binding</li>
</ul>
<p>
Perform the following to install and run the e4 contacts demo. Note that steps 1-6 can
be skipped if the steps for <a href="#R-Demos-Loading">Loading the example projects</a>
above are followed.
</p>
<ol>
<li>Start the e4 compatibility platform with an empty workspace directory.</li>
<li>Select <b>File &gt; Import...</b> and select <b>CVS &gt; Projects from CVS</b>, click <b>Next</b>.</li>
<li>Enter the e4 repository information. Host: dev.eclipse.org, Repository path: /cvsroot/eclipse, User: anonymous, Connection type: pserver.</li>
<li>Click <b>Next</b> and select the second option, <b>Use an existing module</b>.</li>
<li>Drill down as follows: <b>e4 &gt; org.eclipse.e4.ui &gt; examples</b> and select <b>org.eclipse.e4.demo.contacts</b>. Click <b>Next</b>.</li>
<li>Important: Do not click Finish just yet. Advance to the last wizard page using <b>Next</b>, then click <b>Refresh Tags</b>. Select <b>R0_9</b> and click <b>Finish</b>.</li>
<li>This will check out one project into your workspace. Expand the project in the <b>Package Explorer</b> and open the contacts.product file.</li>
<li>Click on the link <b>Launch an Eclipse Application</b> at the bottom left of the contacts.product file editor.</li>
</ol>
<p>
The e4 contacts demo application will come up. Select a different theme from the <b>Theme</b> menu
for a demonstration of changing application styling on the fly.</p>
<p>
Back in the workbench, view and edit the CSS
files under the <tt>org.eclipse.e4.demo.contacts/css</tt> folder to experiment with different application styling. Browse
and edit the <tt>Application.xmi</tt> file to customize the application model.
</p>
<h3>4.2.3 <a name="R-Demos-Flex">SWT Flex examples</a></h3>
<p>
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).
</p>
<p>
<b>Setup Flex environment</b>
</p>
<ol>
<li>Download and install the Adobe Open Source Flex SDK (available from
<a href="http://opensource.adobe.com">http://opensource.adobe.com</a>).
NOTE: The path where you install the Flex SDK must contain no spaces. This is due to a bug in FCSH.</li>
<li>Verify that your Flex install works by opening a command prompt, changing to the Flex SDK bin
directory, typing &quot;mxmlc&quot; and hitting Enter. If you get an error message, you will need to add a
JAVA_HOME environment variable that points to the home dir or edit the bin/jvm.config file in the Flex SDK.</li>
</ol>
<p>
<b>Setup the Flex tools:</b>
</p>
<ol>
<li>Update your eclipse.ini file and add another line at the end, -Dflex.sdk=<your path to the installed sdk>
Note: Make sure you don't edit the command line (for example in a launch shortcut) as it
overrides the .ini file and loses the Flex settings.</li>
<li>Make sure that you are using at least a Java SE 5 JRE to run Eclipse as the ActionScript tools plugin requires it.</li>
<li>Launch the e4 compatibility platform with a new Eclipse workspace. Note: The path
where you create the workspace must contain no spaces.</li>
<li>Select <b>Help &gt; Install New Software...</b></li>
<li>Go to the <a href="http://download.eclipse.org/e4/downloads/">e4 download page</a> for the 0.9 release, and find the link
at the bottom right corner called <b>online p2 repo link</b>. Drag that link into the <b>Work with</b> field.</li>
<li>Expand <b>E4 SWT</b> and select <b>Eclipse e4 ActionScript Developer Tools</b>.</li>
<li>Click <b>Next</b> twice. Review and accept the license, and click <b>Finish</b>.</li>
<li>Restart the workbench when prompted</li>
</ol>
<p>
<b>Setup the Eclipse target environment:</b>
</p>
<ol>
<li>Turn off auto build (<b>Project &gt; Build Automatically</b>)</li>
<li>Download the SWT source zip from the e4 release download page (The zip is named
org.eclipse.swt.e4.flex-incubation-I[timestamp].zip).</li>
<li>Import this zip into your project (<b>File &gt; Import &gt; General &gt; Existing Projects into Workspace &gt; Select archive file</b>).</li>
<li>Add a new ActionScript VM. (<b>Window &gt; Preferences &gt; Java &gt; Installed JREs</b>).
<ol>
<li>Click <b>Add...</b></li>
<li>Select <b>ActionScript VM</b>, click <b>Next</b>.</li>
<li>Click <b>Directory...</b> and browse to either your Firefox or IE install directory.</li>
<li>Click <b>OK</b>, click <b>Finish</b>.</li>
</ol></li>
</ol>
<p>
<b>Get the demos</b>
</p>
<ol>
<li>Select <b>File &gt; Import...</b> and select <b>CVS &gt; Projects from CVS</b>, click <b>Next</b>.</li>
<li>Enter the e4 repository information. Host: dev.eclipse.org, Repository path: /cvsroot/eclipse, User: anonymous, Connection type: pserver.</li>
<li>Click <b>Next</b> and select the second option Use an existing module.</li>
<li>Drill down as follows: <b>e4 &gt; releng</b> and select <b>org.eclipse.e4.swt.releng</b>. Click <b>Next</b>.</li>
<li>Important: Do not click Finish just yet. Advance to the last wizard page using <b>Next</b>,
then click <b>Refresh Tags</b>. Select <b>R0_9</b> and click <b>Finish</b>.</li>
<li>In the project you just checked out, select the file <tt>e4.swt.as.demo.psf</tt>, and
select <b>Import Project Set...</b> from the context menu (If prompted for username:password, you should use anonymous:anonymous).</li>
<li>Delete the file <tt>.classpath</tt>, and rename the file <tt>.classpath_flex</tt>
to <tt>.classpath</tt> in the <tt>org.eclipse.swt.examples</tt> project.
(Note that in order to see the classpath files, you have to turn off the resources filter
in the <b>Project Explorer</b>by clicking on the drop down arrow menu in the top
right hand corner of the view, selecting <b>Filters</b> and unchecking <b>*.resources</b>).</li>
<li>Turn on <b>Build Automatically</b> in the <b>Project</b> menu (You can
watch the build progress in the <b>ActionScript Build Console</b>, available from the <b>Console</b> view)</li>
<li>You can run any of the demos from <tt>org.eclipse.swt.e4.examples</tt> by
clicking on them and Selecting <b>Run As &gt; ActionScript Application</b>.</li>
</ol>
<p>
For more information on working with e4 SWT, visit the
<a href="http://wiki.eclipse.org/E4/SWT/Running_the_demos">e4 SWT Demos</a> wiki page.
<h3>4.2.4 <a name="R-Demos-CSS">Customizing the workbench style</a></h3>
<p>
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:
</p>
<p>
<code>
&nbsp;&nbsp;&nbsp;eclipse\plugins\org.eclipse.e4.ui.examples.legacy.workbench_0.9.0.vSomeBuildDate\css\webby.css
</code>
</p>
<p>
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 <b>e4 &gt; Reload Style Sheet</b>
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.
</p>
<p>
If you decide to create a new CSS file, you''ll need to change the following property in
<tt>org.eclipse.e4.ui.examples.legacy.workbench/plugin.xml</tt>:
</p>
<p>
<code>
&nbsp;&nbsp;&nbsp;&lt;property<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;name="applicationCSS" <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;value="platform:/plugin/org.eclipse.e4.ui.examples.legacy.workbench/css/webby.css"&gt;<br>
&nbsp;&nbsp;&nbsp;&lt;/property&gt;<br>
</code>
</p>
to point to your new file. This of course will require a restart in order to be picked up.
For more details on what CSS properties are supported for various widgets, see
the <a href="http://wiki.eclipse.org/E4/CSS/SWT_Mapping">CSS SWT Mapping</a> wiki page.</p>
<h3>4.2.5 <a name="R-Demos-Model">Manipulating the workbench model</a></h3>
<p>
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 <b>e4 &gt; UI Editor</b> 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 <b>Basic</b> and <b>Advanced</b> tabs at the bottom. Notice how model
changes are reflected immediately in the workbench window state underneath!
</p>
<h3>4.2.6 <a name="R-Demos-RAP">e4 RAP integration</a></h3>
<p>
There is experimental integration available between the Eclipse <a href="http://www.eclipse.org/rap">
Rich Ajax Platform</a> (RAP) project and e4. For more details on running e4 on RAP,
see the <a href="http://wiki.eclipse.org/E4/RAP_Integration/Experimental">e4 RAP Integration"</a> wiki page.
Also see the e4 demos running on RAP <a href="http://www.eclipse.org/rap/demos.php">here</a>.
</p>
<h3>4.2.7 <a name="R-Demos-XWT">e4 XWT integration</a></h3>
<p>
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.
</p>
<p>
XWT versions of the e4 contacts and photo demos are also available. To load these
demos, perform the following:
</p>
<ol>
<li>Start the e4 compatibility platform with an empty workspace directory.</li>
<li>Select <b>File &gt; Import...</b> and select <b>CVS &gt; Projects from CVS</b>, click <b>Next</b>.</li>
<li>Enter the e4 repository information. Host: dev.eclipse.org, Repository path: /cvsroot/eclipse, User: anonymous, Connection type: pserver.</li>
<li>Click <b>Next</b> and select the second option, <b>Use an existing module</b>.</li>
<li>Drill down as follows: <b>e4 &gt; org.eclipse.e4.xwt &gt; examples</b> and select <b>org.eclipse.e4.demo.contacts</b> or <b>org.eclipse.e4.demo.photos</b>. Click <b>Next</b>.</li>
<li>Important: Do not click Finish just yet. Advance to the last wizard page using <b>Next</b>, then click <b>Refresh Tags</b>. Select <b>R0_9</b> and click <b>Finish</b>.</li>
<li>This will check out one project into your workspace. Expand the project in the <b>Package Explorer</b> and open the e4photo.product file.</li>
<li>Click on the link <b>Launch an Eclipse Application</b> at the bottom left of the e4photo.product file editor.</li>
</ol>
<p>
For more details on running e4 with XWT, see the XWT <a href="http://wiki.eclipse.org/E4/XWT">wiki page</a>,
and the XWT <a href="http://wiki.eclipse.org/E4/XWT/Running_the_demos">demos wiki page</a>.
</p>
</body>
</html>