Installation Blues, Part 2 - Readying Eclipse for use

Today I'd like to pass on the benefits of a lesson that I underwent in the "school of hard knocks" in the fervent hope that it will help some of you, dear readers, to avoid the trap that I fell into in my first brush with Eclipse (getting it ready for working with Java).

Now what's the first thing you look for when you install (Windows) software these days? Surely it's got to be a setup program, and you look for one named setup.exe or install.exe or something similar. And if you're like me you immediately launch this setup program without bothering to read any documentation (since the true test of a good modern installer is that it makes setup a breeze).

Well, in the case of Eclipse you're in for a surprise. Getting Eclipse ready for use is rather different from what you're used to with all the other IDEs out there. (As a preamble, I'm assuming that you already have the suitable prerequisite JRE and JDK installed, as for any other Java IDE.)

The first thing you have to know is that setting up Eclipse V3 is not an "installation" in the usual sense of the term, so let me instead use the term "readying Eclipse". There's no conventional installer that churns around for while setting up directories and doing other mystical things and then finally telling you that Eclipse has been installed.

This difference can confuse both novices and seasoned developers. Nowhere (at least nowhere obvious, to my knowledge) is there a simple set of instructions for getting Eclipse ready for use. I haven't come across a README file in the Eclipse distributions which tells you about this. Nor did I find much about it in any of the Eclipse textbooks and a tutorials. This can be a stumbling block, and sure enough I stumbled!

In the absence of any simple README file, after considerable digging around I worked out that you only have to unzip the Eclipse build package into a folder and then just launch eclipse.exe from that folder. So I got to the point where the Eclipse workbench opened in all its glory, and things were looking good or so I thought.

But more frustration lay ahead. I couldn't discover any Java support (syntax checker, compiler, etc). What was going on here, says I to myself. Was it due to some Eclipse option that I hadn't activiated? I looked everywhere, but try as I might I couldn't even get my World program compiled and running.

As a last resort, I moved into Read The Manual mode! After a bit of research, I came across an intelligible description of the Eclipse plug-in architecture and installation procedures. It indicated that Java support (the "SDK") was just one of the available plug-in options. So I had to install the Java SDK did i? What a nuisance. So after reluctantly reading up on the Eclipse plug-in installation procedure (and stumbling a few more times), I managed to install the Java plug-in. Much to my relief, I could then compile and debug "Hello World".

Nevertheless, I wasn't a happy trooper. Why on earth did I have to go through all the rigmarole of learning the Eclipse plug-in architecture and separately install the Java plug-in? Why did neither the Eclipse online Help nor the eclipse.org web site explain in a friendly, clear and up-front fashion the simple steps needed to get Eclipse ready for use (just unzip the file into a folder and then run eclipse.exe from that folder)? Maybe they do explain it somewhere, but if so I yet to find it!

This initial experience with Eclipse did NOT make a good first impression on me, especially in comparison with the many other smooth IDE installations I have done over the years. What had I done that was so wrong, and what did I have to do to get a simple Java compile working?

After some further research and experimentation I finally discovered where I had gone astray: I had stumbled merely because I had selected the wrong file. I had downloaded the Eclipse Platform build file (for Eclipse 3.0, the one named "eclipse-platform-3.0-win32.zip").

One of the shortcomings of the Eclipse delivery process is the way that the builds are shipped. If you visti one of the Eclipse mirro sites (such as http://mirror.pacific.net.au/eclipse/eclipse/downloads/drops/ here Down Under, in Melbourne) you are presented with an an overwhelming list of builds. And when you open one of the individual builds (such as http://mirror.pacific.net.au/eclipse/eclipse/downloads/drops/R-3.0-200406251208/) there's a long list of build files to choose from. It's pretty obvious that some are for WIndows, others for Linux or Solaris, and so on. But what's not obvious to the novice is that the appealing-looking "platform" variant is NOT the build file that you should be interested in (for Java).

What I didn't immediately realize was that when you unzip this "platform" file you get only a skeletal Eclipse IDE (a basic, language-neutral “platform”) and this base version does not include any language plug-ins at all. When I did come to realize this, the rest was easy.

What I should have downloaded was the Eclipse SDK build file (for Eclipse 3.0, the one named "eclipse-SDK-3.0-win32.zip"). As soon as I used this version everything went smoothly. This is the build file that has the desired Java support built in (there's no need to install the Java SDK plug-in separately). Lesson over, but what along and painful lesson! The pity is that it should have been plain sailing all the way, and I shouldn't have had to endure any storm-tossed seas!

So, brethren, let me put it pithily:

• Eclipse should come with a simple "READ ME FIRST" document that clearly explains the salient points from above so that you don't go astray like I did.
  
• If it's Java you want to use -- and most Eclipse users probably do, not the JDT or RCP or other specialist aspects of Eclipse -- then be sure to download the SDK file (not the base "platform" file, or the "JDT" file, or the "RCP" file, or any of the others in the drop).

Here endeth the lesson.

Now it's over to you ... Can any of you provide similar tips for Eclipse (and post them here for the benefit of all)?