The way you download Eclipse depends on how close you want to be to the “live stream.” Following are the release types that can be downloaded from the Eclipse download site (http://eclipse.org/downloads), in increasing level of closeness to the CVS HEAD stream:

Each release or build has a corresponding set of build notes and test results. Be sure to consult these notes before selecting a given build. Automated test suites are run against the nightly and integration builds. Having a build pass the tests can increase the confidence level people have in them. In all cases, the builds are shipped as a compressed archive, and installation is a simple matter of unzipping them anywhere on your local machine.

Alternatively, you may have already installed Eclipse without knowing it. Many commercial products are based on Eclipse, and so while installing these products, you often install a given version of Eclipse. These products usually are not shy about being based on Eclipse, so you can easily discover the location of the eclipse installation by investigating the installation directory of the product. Usually, the directory will contain a subdirectory called eclipse that contains the embedded Eclipse instance. While running your product, you can activate the menu option Help > About ... and then click on the Eclipse icon to see what version of the platform is being used.

Note

The Eclipse download site (http://eclipse.org/downloads)

When you unzip the Eclipse SDK, it creates a base install directory called eclipse. The directory layout looks something like this:

eclipse/
   features/          the directory containing Eclipse features
   plugins/           the directory containing Eclipse plugins
   eclipse.exe        platform executable
   cpl-v10.html       the CPL license
   install.ini
   jre/               the JRE to run Eclipse with
   notice.html
   readme
   startup.jar        classes needed to start the platform

You can start Eclipse by running eclipse.exe on Windows or eclipse on other platforms. This small launcher runs a JVM with the following arguments:

java -cp eclipse/startup.jar org.eclipse.core.launcher.Main

If available under the eclipse/jre directory, the Eclipse JRE will be used; otherwise the launcher will consult the JAVA_HOME system path variable. A better option is to explicitly specify a JVM of your choice, using the -vm command-line argument:

eclipse -vm c:/jre/bin/javaw.exe

You should always use -vm so you can be sure of what VM you are using. Installers for other applications sometimes modify the JAVA_HOME variable, thus changing the VM used to launch Eclipse without your knowing about it.

The first time the eclipse command is executed, the platform creates a workspace directory, such as eclipse/workspace. The workspace will contain all your projects, along with private metadata computed by various plug-ins.

In Eclipse 3.0, you are prompted to choose a workspace location on start-up. Previously, the platform stored the workspace in the Eclipse install directory by default. In all versions of Eclipse, you can manually specify the workspace location on the command line, using the -data <workspace-path> command-line argument. The easiest way to quickly start Eclipse on different workspaces for versions before Eclipse 3.0 is to create shortcuts or shell scripts for each launch. The use of -data is advised because using the default workspace location will make it much more difficult for you to upgrade to new versions of Eclipse.

Note

FAQ 26 How do I increase the heap size available to Eclipse?

FAQ 260 Who shows the Eclipse splash screen?

Some JVMs put restrictions on the total amount of memory available on the heap. If you are getting OutOfMemoryErrors while running Eclipse, the VM can be told to let the heap grow to a larger amount by passing the -vmargs command to the Eclipse launcher. For example, the following command would run Eclipse with a heap size of 256MB:

eclipse [normal arguments] -vmargs -Xmx256M [more VM args]

The arguments after -vmargs are directly passed to the VM. Run java -X for the list of options your VM accepts. Options starting with -X are implementation-specific and may not be applicable to all VMs.

Note

FAQ 25 How do I run Eclipse?

Whenever it encounters a problem that does not warrant launching a dialog, Eclipse saves a report in the workspace log file. The log file can be looked at in four alternative ways.

Note

FAQ 121 How do I use the platform logging facility?

Eclipse should work fine on any Linux distribution that has GTK+ 2.2.1 and higher—SWT is based on GTK2—and a 1.4 JRE. Motif versions require Open Motif 2.1, which is included in the Eclipse distribution. Although the Motif distribution has performance comparable to Windows, its clunky appearance makes GTK the widely preferred choice on Linux.

However, the Eclipse development teams are able to perform thorough testing only on a limited set of platforms. Consult the release notes included with each Eclipse build for a detailed list of officially supported platforms. As of June 2004, this list included the platforms in Table 2.1.

Portability of Eclipse is defined mainly by the underlying Java runtime—Eclipse 3.0 needs a Java 1.4 runtime—and by what platform SWT runs on; namely, all graphical UI in Eclipse are based on SWT. Table 2.1 lists various standard Java runtimes. However, earlier versions of Eclipse have also been compiled with gcj (http://www.klomp.org/mark/classpath/eclipse-gnome-gij.png) and even made to run on .Net, using IKVM on the CLR or Mono through the amazing work of Jeroen Frijters (http://www.frijters.net).

For any given Eclipse build, the supported platforms are listed in the readme file included with the download (readme_eclipse.html in the readme directory).

Note

The Eclipse download site (http://eclipse.org/downloads) IKVM (http://www.ikvm.net)

Invariably, with several hundred thousand downloads of Eclipse every month, Eclipse does not start at all for a few users. These failures typically stem from software configuration problems on the host machine or an unusual hardware configuration. If you are already a power Eclipse user, you might be tempted to skip this question. However, even the most advanced Eclipse user will occasionally have problems starting an Eclipse build. So, with a nod to David Letterman, here is a “top ten” list of the most common start-up problems, along with suggestions for solutions.

Note

FAQ 26 How do I increase the heap size available to Eclipse?

FAQ 108 Why doesn’t Eclipse play well with Xerces?

Run the Update Manager, using Help > Software Updates > Find and Install... > Search for updates of the currently installed features. The Update Manager will visit the Eclipse Web site and offer updates for the features you have installed and allow for easy update from Eclipse 2.1 to 3.0, for instance. You can use the Update Manager to upgrade only between official Eclipse releases.

If you want to upgrade to stable stream releases or even nightly builds, you have to live on the edge. Download a new build from the Eclipse download Web site (http://eclipse.org/downloads) and unzip it in a new directory. We strongly recommend against unzipping over your existing Eclipse version as unexpected side effects may occur. Complete upgrade instructions are always included in the Eclipse readme_eclipse.html file included with every build in the readme directory.

Note

FAQ 91 What is the Update Manager?

Your best approach is to use the Eclipse Update Manager.

More experienced plug-in developers—and sometimes lazy plug-in publishers—have learned to find the eclipse/plugins directory and install their plug-ins there manually. This obviously is a more dangerous approach, as no certification takes place about the suitability of the plug-in; it may rely on other plug-ins not available in your installation. In the case of compatibility conflicts, you won’t find out until you use the plug-in that it might break.

You may compare installing plug-ins to installing applications on Windows. You can, of course, install your dynamic link libraries (DLLs) in the System32 directory or play with the PATH environment variable. But, how are you going to remove the application later when you no longer need it? On Windows, specialized installation programs have been devised, and uninstallation is easy through the Start menu. The Eclipse Update Manager can be seen as the Eclipse equivalent of InstallShield and the Windows Registry combined.

For day-to-day development and prototyping of small plug-ins, you might still be tempted to use the manual installation process. You could, but we strongly advise against it. Creating a feature and a corresponding update site is child’s play using the PDE wizards and will greatly improve the quality of your work. Eventually, you will want to share your fruits with others, and having an update site ready from the start will make it much easier to boast of your Eclipse knowledge to your friends and colleagues.

Note

FAQ 69 How do I create a plug-in?

FAQ 89 How do I create a feature?

FAQ 91 What is the Update Manager?

FAQ 237 What is the purpose of activities?

Users who like to “live on the edge” will be frequently installing new builds of Eclipse. When a new build is installed, a manual step is generally required to copy over any extra plug-ins from the old build to the new one. We all know how much programmers hate manual steps, so it would be nice if there were an easy way to link a set of external plug-ins into Eclipse builds. A mechanism to do that is called a product extension.

A product extension must be laid out on disk in a certain way so the Eclipse configuration tools can recognize it. Following is the disk layout for a product extension that contains a single plug-in called org.eclipse.faq.examples.

eclipse/
   .eclipseextension
   plugins/
      org.eclipse.faq.examples/
         plugin.xml
         examples.jar
      ... optionally more plug-in directories ...
   features/
      ... features would go here ...

The file .eclipseextension is empty, acting as a special marker that tells install tools that this is an Eclipse extension. Other than that special file, the layout is the same as that for an Eclipse product. Plug-ins go in a directory called plugins, and if the extension contains features, they go in a sibling directory called features.

Once you’ve got this directory structure set up, you have to link the product extension into your plug-in configuration. In Eclipse 3.0, you simply go to Help > Software Updates > Manage Configuration, choose the option called Link an Extension Location, and select the extension directory when prompted. That’s all there is to it! As long as you keep the same workspace when you upgrade to a new build, the product extensions will automatically be available in the new configuration.

Note

FAQ 30 How do I upgrade Eclipse?

FAQ 33 How do I remove a plug-in?

You should not remove plug-ins from Eclipse. Plug-ins should be installed as features using the Update Manager. The same Update Manager can be used to disable plug-ins by disabling the feature they belong to. Run Help > Software Updates > Manage Configuration..., select the feature of interest, and disable it with the task shown in the right window.

When a feature is disabled, all its plug-ins will be disabled also. They are still available on disk, and they can be enabled at any time in the future. To physically remove the feature and its plug-ins, you will have to manually remove the feature from the eclipse/features directory and its plug-ins from the eclipse/plugins directory. We advise extreme caution here. Remove the wrong ones, and you may have quite some trouble restoring your Eclipse to a stable state. Unless you care a lot about hard disk use, we recommend leaving the plug-ins where they are.

One way of finding out is to select Help > About Eclipse Platform >. From this dialog, click Plug-in Details to get a list of all installed plug-ins, along with vendor and version information. If you instead click Configuration Details, you will be rewarded with a full credit report of your current Eclipse installation. The main sections contain information about your system properties, what features and plug-ins have been installed, preferences specified by you, the Update Manager log, and a dump of the error log, which lists problems that have been reported by various plug-ins.

Note

FAQ 111 What is a configuration?

Eclipse offers extensive help through the menu option Help > Help Contents.... This will launch a Tomcat server to run from inside your Eclipse, and a browser is opened to show the contents. The help browser has a useful search engine to search the entire Eclipse documentation. Sometimes, this help text is confusingly referred to as the online help, perhaps because the help is replicated online at the Eclipse Web site (http://eclipse.org/documentation/main.html). However, your local help will also work when you are disconnected from the network.

Alternatively, more focused, context-sensitive help can be invoked at any time by pressing F1. The currently selected widget is offered a chance to honor the help request. Its containment tree is walked upward until a suitable localized help can be furbished. A pop-up will appear near the mouse, and links to the documentation are provided. If the help does not seem helpful, remember how the search path for F1 help works and feel free to enter a bug report to ensure that help is provided at the proper level.

Select Help > Cheat Sheets... for step-by-step instructions on common tasks. The steps have convenient links to topic-related help.

If you don’t find the answer you need in the help system, there are plenty more sources of information on Eclipse. On eclipse.org you will find a plethora of resources, including articles by Eclipse experts, newsgroups, mailing lists, and lists of books and tutorials. Perhaps best of all, the Eclipse source code is the most reliable place to look for information. The source never lies and is always up to date!

Note

FAQ 274 How do I add help content to my plug-in?

FAQ 275 How do I provide F1 help?

Let’s say that you are new to Eclipse, but have some existing projects with file system layouts that cannot be changed. Perhaps you have other tools or build processes that require your projects to be laid out in a certain way. Because Eclipse also has expectations about how projects are laid out on disk, you can run into problems when you try to get started in Eclipse with your existing projects.

In release 2.1, Eclipse introduced the notion of linked resources to help deal with problems like this. Linked resources can refer to files or folders anywhere in your file system, even inside other Eclipse projects. Using linked resources, you can cobble together a project from files and folders that are scattered all over your file system. The link descriptions are stored in the file called .project inside your project content area. If you share this file with a repository, other users will be able to load the project and get all the links reconstructed automatically in their workspace. If you do not want to hard-code particular file system paths, you can define linked resources relative to workspace path variables. Path variables can be added or changed from the Workbench > Linked Resources preference page.

For more information on using linked resources, see the good general introduction in the Workbench User Guide, under Concepts > Workbench > Linked resources. The Java Development User Guide also has an excellent tutorial that helps you get started with various types of project configurations. Look under Getting Started > Project configuration tutorial. Information on how to define linked resources programmatically is found in the Platform Plug-in Developer Guide, under Programmer’s Guide > Resource and workspace API > Linked Resources.

Attempting to enumerate all of new features and APIs in Eclipse 3.0 would be futile. The past year or so of development has focused on more than 50 major features of the Eclipse 3.0 plan, not to mention addressing more than 5,000 bugs and feature requests, according to a quick query of the Eclipse Bugzilla. The best place to get an overview of major new changes in Eclipse 3.0 is to read through all the New and Noteworthy documents included with each milestone build.

To give you a quick summary, the development of Eclipse 3.0 has centered on the following major themes:

Note

FAQ 38 Is Eclipse 3.0 going to break all of my old plug-ins?

The Eclipse 3.0 plan (http://eclipse.org/development/plan)

No. Many rumors and discussions circulated during the development of Eclipse 3.0 about how compatible it would be with plug-ins written from Eclipse 2.1 or earlier. Clearly, in the large community of Eclipse plug-in writers, many would be greatly inconvenienced by any breaking changes to existing API. On the other hand, rigidly maintaining API across all releases can be a great barrier to ongoing innovation in the platform. Eventually, a balance was struck that allowed for some well-justified breaking changes, while also providing a compatibility story to allow old plug-ins to continue running on Eclipse 3.0. What does this mean if you have written plug-ins targeting older versions of the platform?

If you do not want to take advantage of new capabilities in Eclipse 3.0, you don’t need to do anything. The platform guarantees 99 percent binary compatibility with older versions of Eclipse. Thus, most old plug-ins that used only legal API in previous releases will continue working when installed in Eclipse 3.0. If you find cases in which this is not true, you are encouraged to enter bug reports so that the compatibility support can be fixed.

So far it sounds too easy, right? Well, as the saying goes, “nothing ventured, nothing gained.” If you do want to take advantage of new Eclipse 3.0 API, you will need to do some work to port your plug-in to 3.0. In most cases, the amount of work required is minimal, and the Eclipse plug-in development tools provide utilities for automatically migrating your plug-in manifest file for 3.0. All the required migration is carefully described in the Eclipse 3.0 Porting Guide, found in the Platform Plug-in Developer Guide in the Eclipse help system. If you find that your old code is not compiling or running when being developed against Eclipse 3.0, consult the guide to see what changes might have affected you.

Note

FAQ 39 How do I prevent my plug-in from being broken when I update Eclipse?

Eclipse makes a careful distinction between published APIs and internal implementation details. The APIs are designed to reduce coupling between plug-ins to a small, stable interface. This insulates clients of the interface from being affected by implementation changes, and it allows the plug-in that publishes the interface to continue to innovate and grow without breaking existing clients. If your plug-in uses only published API and carefully follows the API contracts defined in the API javadoc, your plug-in should continue to work after migrating to a new Eclipse release.

In the Eclipse Platform, the API of a plug-in includes all public classes and interfaces that do not have the word internal in their package names and all public and protected methods in those classes and interfaces. The API also includes all extension points that are not explicitly described as for internal use only in their documentation; there is only a small handful of such internal extension points.

Note

eclipse.org article “How to Use the Eclipse API”

EclipseCon 2004 technical track presentation, “Eclipse APIs: Lines in the Sand” (http://www.eclipsecon.org).