Setting up Eclipse

Russell Bateman
Spring 2010
last update:

Table of Contents

Caveat lector (Reader beware!)
The world of 64-bit
The Java developer's kit (JDK)
Tomcat and other servers
Eclipse: the installation
Which package should I install?
Eclipse distribution details
Android development
BlackBerry development
Mixing development modes
Launching Eclipse
Windows eclipse.ini
Linux eclipse.ini
Trouble launching Eclipse?
Macintosh trouble
Linux launching problem
Miscellaneous Eclipse command-line information
Debugging Eclipse start-up
Enforcing a default workspace
Javadoc author
Where to go from here?
Appendix: Eclipse versioning
Appendix: Setting up 64-bit Eclipse

This is a very short treatise on quickly setting up Eclipse Galileo, Helios or Indigo. It should also work for Juno. We also show you how to set up a JDK and a web server container (Tomcat) because these all go together. These are arranged in a sequence in Setting Up Eclipse—a Summary of which the present page is the part on setting up Eclipse itself.

Caveat lector (Reader beware!)

Understand that, except for specific remarks especially about Android development, everything I say is from the point of view of a JEE/web application developer. If you're doing C/C++ or PHP, don't assume that everything I say here applies to you. I'm an old C programmer, but I've never used Eclipse for C. I've written less PHP code than a seamstress' thimble would hold and none of it using Eclipse. (See Mixing development modes below.)

Also, while I try to be pretty orthodox in my Eclipse habits, this article and others often represent my opinions which aren't those of other developers some of whom are vastly more experienced than I.

The world of 64-bit

First, note that it is possible to get a 64-bit Eclipse these days. The most important thing to know about setting up 64-bit Eclipse is you must install a 64-bit JDK also. You cannot run Eclipse on a mismatched JDK. This is a common start-up problem among questions to the Eclipse newcomers' forum. Please see Appendix: Setting up 64-bit Eclipse to see how I set this up.

The Java developer's kit (JDK)

Prior to installing Eclipse, you'll need a Java developer's kit (JDK). Read my instructions for Setting up the Sun Java Developer's Kit, then come back here to learn how to install Eclipse.

Tomcat and other server containers

If you plan on developing web applications, you'll also want to download and install Apache Tomcat, GlassFish, JBoss or some other web server container for use with Eclipse. I mostly have experience with Tomcat. See Setting up Apache Tomcat on how to download, explode and make Tomcat available to Eclipse.

If you're doing Android development, you do not need to install Apache Tomcat or any other server container.

Eclipse: the installation

To install Eclipse, go to http://eclipse.org/downloads/ and click on Windows 32-bit or Linux 32- or 64-bit, Macintosh, etc. (If you're going to develop Android applications, read on before doing this.)

This software isn�t installed in the modern sense; instead you just unzip it on a path such as C:\eclipse or (Windows 7) C:\Users\russ\dev—whatever: it's up to you. On Linux, maybe /home/russ/dev/eclipse.

Note: On Windows 7, update problems (Help -> Check for Updates or Install New Software) will later ensue if Eclipse is installed under Program Files. It's much better to put it locally as illustrated here.

Which package should I install?

The Eclipse Foundation and organization of contributing developers make a number of pre-established packages available for web application development, general Java development, C/C++ development, PHP, plug-in and many other uses as you can see on the download page. (Below, from left-to-right: IDE for Java EE Developers, IDE for Java Developers, IDE for C/C++ Developers, PHP Developers and RCP/Plug-in Developers; there are still others than those shown here.)

All of these packages can be configured, via the addition of plug-ins, to do everything any of the other packages can do. However, it can get complicated. Common wisdom holds that you should begin with the package that offers the most of what you need, then add in the remainder.

If you develop in Java, I suggest you install the Eclipse IDE for Java EE Developers because it provides for both Dynamic Web Projects for doing JEE (formerly called J2EE), Java Projects for doing plain Java work and still other project types. This package is basically the standard Java development package enhanced with the features of the Eclipse Web Tools Platform work.

Important note: There are components that belong formally to Eclipse and that ship with (one or more) Eclipse distributions. And, there are components that do not because they are "extra"—belonging to third parties like Google, BlackBerry, and still other concerns. Two examples of this are noted below (Android and BlackBerry).

Eclipse distribution details

For a detailed matrix of common packages and the Eclipse distros that they come in, please see Compare Packages.

Android development

Android development is an example of something Eclipse doesn't directly support, but which is nigh-seemlessly integrated into it.

If you're going to develop Android applications, you should create a separate Eclipse installation from normal, Java development, especially if you develop JEE including web applications. Use the Eclipse IDE for Java Developers (after installing a JDK, come back here and click the icon to the right). For example, if you're developing for Android, you should

  1. Get a Sun JDK as discussed above before downloading and installation Eclipse.
  2. Not install any other Eclipse than the simple IDE for Java Developers.
  3. Not install Apache Tomcat or any other server container (because they're totally irrelevant).

It is possible to combine every possible development option into one Eclipse installation. Many do. I do not because it doesn't suit me and because I've had trouble when I've done that.

BlackBerry development

Please see BlackBerry Development and Eclipse.

Mixing development modes

Eclipse can be used to develop a lot of different applications and code written in many different languages beyond its original Java orientation including (but not limited to) C/C++, Fortran, JavaScript, PHP, Python, and many others.

Should you install Eclipse and load it up to do all of these at once?

The short answer is, "Yes, you can" and you start with the most complicated and comprehensive one, for example, JEE, then use Help -> Install New Software, change Work with to "--All Available Sites--" and look around for what you want.

I don't this; I hope I'm steering you to the best solution if you decide to do it. There may be good ways and better ways in how you set up a single, megalithic Eclipse, but I haven't ever done it.

Should you do this?

There are two camps, equally entrenched over this issue.

I belong to the camp that says, as long as I'm not trying to write an application that somehow mixes C/C++ code with Java, why would I want to encumber Eclipse with both Java/JEE and C/C++ at once? I'll just use separate Eclipse installations for each, totally separate undertaking.

I originally began doing this because installing the Android SDK once destabilized my Eclipse JEE and made it useless.

This said, the other camp points out that when you launch Eclipse and avoid using, e.g.: Eclipse CDT plug-ins while doing Java/JEE work, those plug-ins aren't loaded anyway and therefore do not weigh upon Eclipse (or destabilize it). I trust them completely in this because I haunt the same newsgroups as they and have complete confidence in their knowledge and abilities.

I just have no objection to sacrificing a few hundred megabytes on my system to two or three separate installations, in my case, JEE and Android (I don't use Eclipse for much else). I have had excellent experiences with Galileo and Helios which were rock-hard. I've never had a bad experience with Indigo. I don't use Juno yet though I've downloaded it and played with it. I tend to develop on mature (old) Eclipse installations until I find a reason to switch.

I keep my Android projects in one or more Android-only workspaces, so it's convenient not to have to switch workspaces every time I launch. Also, I can have both up simultaneously if I want to examine and/or debug my server code and my Android client code together.

You just need to think about what's important to you and, in the end, it's pretty arbitrary.

Launching Eclipse

As you might expect, you can set up a shortcut on Windows XP, pin the application to either the Start Menu or the Taskbar on Windows 7, or create a Launcher on Linux.

(Note: if you installed or copied a JDK locally to Eclipse, on the path eclipse/jre, as desribed here, you do not need to adjust eclipse.ini as shown below. However, you may do it anyway if you like being explicit about it.)

(For a very comprehensive overview of Eclipse start options, see http://stackoverflow.com/questions/142357/what-are-the-best-jvm-settings-for-eclipse/3275659#3275659. However, this is over-kill when starting up as a beginner and only to be consulted for advanced options.)

It's best to tell Eclipse, via eclipse.ini, where your JDK is located. See http://wiki.eclipse.org/Eclipse.ini. In the meantime, here's mine on a Windows 7 host. In green, you see what I added to this file (for Windows):

Windows eclipse.ini
C:\Users\russ\dev\eclipse>type eclipse.ini -startup plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.0.200.v20090519 -product org.eclipse.epp.package.jee.product --launcher.XXMaxPermSize 256M -showsplash org.eclipse.platform --launcher.XXMaxPermSize 256m -vm C:/Program Files (x86)/Java/jdk1.6.0_18/bin/javaw.exe -vmargs -Dosgi.requiredJavaVersion=1.5 -Xms40m -Xmx512m

eclipse.ini options are a little weird to the way most of us think: the option itself goes on one line and its value goes imperatively on the next line.

Here is a working eclipse.ini for Linux. I'm running Ubuntu Karmic:

Linux eclipse.ini
russ@ubuntu-karmic:~/dev/eclipse> cat eclipse.ini -startup plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar --launcher.library plugins/org.eclipse.equinox.launcher.gtk.linux.x86_1.0.200.v20090520 -product org.eclipse.epp.package.jee.product -showsplash org.eclipse.platform --launcher.XXMaxPermSize 256m -vm /home/russ/dev/jdk1.6.0_18/bin/java -vmargs -Dosgi.requiredJavaVersion=1.5 -XX:MaxPermSize=256m -Xms40m -Xmx512m

Trouble launching Eclipse?

When Eclipse fails to launch, there is a very short list of problems to suspect.

  1. If you're running a 64-bit OS, the first and foremost is whether you're trying to run 64-bit Eclipse on a 32-bit JDK or vice-versa.
  2.  
  3. Use Sun's JDK. Other JREs will (usually) work, but unless there's good reason to do otherwise (I can't think of any, but maybe your environment requires it), always use Sun's JDK/JRE and explicitly reference it in eclipse.ini.
  4.  
  5. The most common problem ever is not specifying the path to the JDK with -vm or failing to get the -vm argument in eclipse.ini right. The path to Java goes on the next line after the option; see Launching Eclipse (above), or go to http://wiki.eclipse.org/Eclipse.ini.
  6.  
  7. If you've used the built-in unzip in Windows, there may have been a problem in filename/path length and Eclipse will not start, giving an error like "The Eclipse executable launcher was unable to locate its companion shared library". This is because some paths in the download may exceed a Windows limitation. In years of Eclipse usage, this has only happened to me recently in a Helios download. This is sometimes remedied by extracting from the zip at the root of C:, but it's always solved by extracting using 7-zip or other competent extractors.
  8.  
  9. As a last-ditch solution to try before resorting to the newcomers' forum, especially if you've already run your copy of Eclipse successfully a few times, launch Eclipse and clean:
    russ@ubuntu-karmic:~/dev/eclipse> ./eclipse -clean
  10.  
  11. Still not working? Go to the newcomers' forum, post your eclipse.ini and, if you can find them, the errors you get out of your attempt to launch Eclipse.

Macintosh trouble

I see questions from Macintosh users regarding problems encountered with Eclipse on the newcomers' forum all the time. However, they do not appear to be insurmountable and there are several hard-core Macintosh contributors to this forum who can answer your questions and usually do so very quickly. It's not my impression that the Macintosh presents any more difficulty for Eclipse development, in terms of frequency of questions, than does Linux—both have large communities of loyal developers and many others who straddle multiple OSes as I do.

This said, the largest community is clearly the Windows users.

Linux launching problem

Since Linux kernel version 2.18, there has been a problem created by an intentional change made for GTK+ development. Programs that don't use GTK+ with scrupulous accuracy may make bad assumptions that worked accidentally in the past. Eclipse is one of these.

The solution is simple if annoying. To run Eclipse, GDK_NATIVE_WINDOWS must be defined in the environment as true, as if:

russ@ubuntu-karmic:~> export GDK_NATIVE_WINDOWS=true russ@ubuntu-karmic:~> ./eclipse/eclipse

You may or may not wish to define this permanently in your environment depending on whether it gives you trouble running other GTK+ applications. Eventually, Eclipse will fix this problem; I give the detail here in case it ever afflicts you. See also discussion here.

Miscellaneous Eclipse command-line information

Debugging Eclipse start-up

There's much you can do with the Eclipse command line. For example, if you're having trouble getting it up, you can invoke it from the command line and pass -debug to see what may be up. (Note: there is no actual $ECLIPSE_HOME needed, but its meaning is obvious and useful here.)

# cd $ECLIPSE_HOME # eclipse -debug

Whereupon you'll get output such as...

!SESSION 2010-05-28 21:29:57.439 ----------------------------------------------- eclipse.buildId=I20100608-0911 java.version=1.6.0_20 java.vendor=Sun Microsystems Inc. BootLoader constants: OS=win32, ARCH=x86, WS=win32, NL=en_AU Framework arguments: -product org.eclipse.epp.package.java.product Command-line arguments: -os win32 -ws win32 -arch x86 -product org.eclipse.epp.package.java.product -data c:\temp\ws -debug !ENTRY org.eclipse.osgi 4 0 2010-05-28 21:29:59.756 !MESSAGE Application error !STACK 1 (Java exception trace starts here...)

This information is useful in finding the reason why Eclipse won't run and certainly useful to post in the newcomers' forum when trying to get help.

Enforcing a default workspace

You can specify the workspace for Eclipse to start up. Ordinarily, you can let Eclipse handle this, even defaulting the start-up workspace until you change it. Eclipse always (at least proposes) starts up on the last workspace that it worked in before shut-down. But, if you always want the same workspace at start-up no matter what you may have done the day before, you can specify it on the command line (so, in a script or Linux launcher).

# eclipse -data /home/russ/dev/workspace-x

Javadoc author

If you want Eclipse's automatically created Javadoc comments to fill in @author with a name different from your OS username, you'll need to add

-Duser.name=Name I. Want

...under the -vmargs option in eclipse.ini. For example, my Windows eclipse.ini is:

-vm C:/Program Files (x86)/Java/jdk1.6.0_18/bin/javaw.exe -vmargs -Dosgi.requiredJavaVersion=1.5 -Xms40m -Xmx512m -Duser.name=Russell Bateman

Or, you can do this at launch from the command line (how I modify a launcher in Linux if I don't happen to edit eclipse.ini).

russ@ubuntu-karmic: ~/dev/eclipse> ./eclipse -vmargs -Duser.name="Russell Bateman"

Without doing this, (in my case) I would see near the top of my new Java class:

package com.etretatlogiciels.newclass; /** * This is my new class. * * @author russ */ public class NewClass { . . .

...instead of   @author Russell Bateman.

BIG CAVEAT: If you consume any plug-in from Eclipse that itself uses user.name for what it's really supposed to be (your username on the host computer), then this solution will break.

WORKAROUND: Another option is to edit the code template @author ${user} and change the value to a hard-coded name (@author Russell Bateman).

Where to go from here?

If you got here from one of my tutorials, just click back to return to your reading.

For help with Eclipse, please find various forums, especially the newcomers' forum, at http://www.eclipse.org/forums/. In addition, there are other Eclipse forums for directing specialized technology questions such as the Web Tools Platform and Data Tools Platform forums.

Appendix: Eclipse versioning

Here's a quick reference on Eclipse releases and names.

 
3.0 28 June 2004
3.1 28 June 2005
3.2 Callisto 30 June 2006
3.3 Europa 29 June 2007
3.4 Ganymede 25 June 2008
3.5 Galileo 24 June 2009
3.6 Helios 23 June 2010
3.7 Indigo 28 June 2011
4.2 Juno 27 June 2012

If you see "letters" in conjunction with a version number, this is what they mean:

Appendix: Setting up 64-bit Eclipse

I am running Eclipse on an Intel i5 750 under Ubuntu Lucid Lynx 64-bit. I have set up Eclipse Helios JEE 64-bit. This is what I did:

  1. Download Helios JEE Eclipse 64-bit; unzip it to /home/russ/dev/eclipse.
  2. Download the 64-bit JDK from Sun; unzip it to /home/russ/dev/eclipse/jre.
  3. Edit /home/russ/dev/eclipse/eclipse.ini and add
    -vm
    ./jre/jdk1.6.0_21/bin/java
    		
    on two new lines just above
    -vmargs