Getting Started

Here is how you can get a development environment up for the first time when running under Microsoft Windows. 

This has been tested with Microsoft Windows XP (WXP) and Windows 7 (W7).   Most of the images used in this tutorial were taking from a running system with sufficient resolution to read all fine print -- if you have trouble reading anything, just zoom in on it...

Step 1: Install Java.

OpenJDK version 6 is not yet available, so you will need to download the necessary Java software from Sun Oracle..

Be sure to install the full SDK rather than just the JRE run-time environment.  Microsoft Windows doesn't mind spaces in filenames and directories, but this isn't always the case for Java based software.  I prefer to install Java to something like "c:\java\jdk6" rather than the defaults used, and recommend you do the same.  If you are told to reboot you Windows machine after installing Java, do so.  Later on we will be installing additional Java run-time components, such as Ant and Junit, but let's get up up and running with Eclipse first.

Step 2: Install Eclipse

Download an appropriate Eclipse package; you will want to use  the current stable release, Helios.  Fetch it from here...

There are many different ways that Eclipse is bundled and packaged and there any many different ways to get yourself running with Eclipse.  I prefer using the official "plain-vanilla" packages from a vendor-neutral site, but you may be enticed to "Get It Faster" from a vendor-specific sites that has "value-added" packages.  (Its pretty easy to customized Eclipse and add package later on, so I would suggest sticking to a plain-vanilla configuration if you're new to all of this.) 

I recommend using "Eclipse IDE for Java Developers".  You are  presented with different mirror sites from which you can download things.   

Be sure to run Eclipse for the first time before you move on to the next step.  You should get around to reading the release notes at some point, as there are useful command-line switches, such as "--clean" that you'll want to know about.  However, the basic installation is enough to get you going for now

Step 3: Run Eclipse for the first time, check for updates...

Run Eclipse and then force Eclipse to check for updates.  This is easily done from the "Help" menu.  

If you are successful, you should expect to see something similar to this

Since you are running this the first time, its important to make sure this completes successfully before attempting to install any plug-ins for Eclipse.  Do not be alarmed if this takes a few minutes to complete. In most cases, its safe to run this in the background, but you can only run one update or download at a time.  After the update completes, be sure to exit and restart Eclipse.

If you want, you can install GIT for Windows while the Eclipse updates take place.

Step 4: Install GIT for Windows

The GIT command-line interface is a necessary subcomponent for Eclipse.  You don't need to know much about this, other than the requirement to install it.  
If you have used SVN or CVS, be aware that Git is a decentralized version control system.  You don't need to know anything about GIT or why this is such a powerful concept, but you may want to read a bit about this when you have time.

Download and install the current stable version of Git for Windows. (I used Git

You can install Git, in which it will place itself under the "Program Files" directory hierarchy.  Nothing wrong with this approach, but I like to keep my Java environment as portable as possible.  I use PortableGit and install it to a directory that has no spaces in its pathname (eg: c:\bin\git or c:\bin-gui\git).

The Git install asks quite a few questions during the install.  The defaults should be reasonable, but but i
f you have Cygwin installed and use it regularly, you should think through how GIT should interact with PATH, SSH and the CR/LF issue.  Bear in mind that many people prefer putty over Cygwin's ssh, as this has better integration under Windows.

Step 5: Install the Egit plug-in for Eclipse

By now, your Eclipse update should be finished.  You must now add the GIT plug-in for Eclipse.  This is done easily and   quickly from within Eclipse itself.  First, be sure you have exited and restarted Eclipse.

Run Eclipse and select "Install New Software" under the Help Menu.  You may have noticed this when you were checking for Eclipse updates earlier.

Under the "Work with" drop-down, select the Helios repository.
Eclipse already knows about this site, just select the right URL.

There are quite a few goodies that you can install.  Do not be distracted by new shiny things.  You can use the "filter" to narrow your choices -- just filter on "egit" to find the package...

Do not be alarmed if Eclipse appears to freeze up when you add something in the "type filter text" area.  It takes a minute or two for the list of Helios packages to be downloaded from the repository.  Be patient when using the filter capability here.  

Select the Egit package and power through the wizard.  All of the defaults should be fine.

FYI: I'm not entirely sure why Eclipse has Egit and Jgit, since it appears that Jgit is a dependency of Egit.  Its a little confusing, but you can read more about this at  I installed Egit, and suggest you do the same.

Step 6: Configure GIT within Eclipse to get to the right source-code repository

Although Git is a decentralized repository, everyone still needs to agree on where shared sources should be kept.  Webhack uses Github, and the URL for anonymous read-only access to the code is...

From within Eclipse, select File > Import ...

Within the Import wizard, you will want to select an input source for "Projects from Git"

From "Select a Git Repository", click on the "Clone..." button.  This will replicate the Git sources to your local system. You will need to specify the URL of source repository.  The wizard is clever enough to break down the URI and fill in everything else.  Click on "Next"...

From within the repository, select the master branch, as shown below...

... and provide a valid path for a directory in which you will create this cloned repository.  This directly must not currently exist, otherwise you will get an error...

I'd urge you to make sure the fully qualified name of this directory does not include any whitespace and does not rely upon case-sensitive names.  (In other words, to save yourself grief in the future, never assume the environment will always figure out that c:\code\WebHack and c:\code\webhack are different.) 

... just accept the default settings for now and power your way through the wizard .... Hint: if you do not see 'Next' highlighted, its probably because you need to select the repository you just imported... Just pay attention to the wizard and you'll figure everything out...

... and the plug-in will quickly fetch all of the files you need, build the appropriate Eclipse artifacts for you.

You should now see your newly imported Git project as a local project, ready for development...

Holy Jarlsberg, Eclipse has already found your first error!  You are missing the GWT SDK.  

Step 7: Install the Google plug-in and Web Toolkit for Eclipse

Now you will need to add the Google Plugins.  Select "Help" > "Install New Software..."

The process is similar to installing Git, but Eclipse does not have built-in knowledge of the Google repository -- you will need to "Add..." this site before you can "work with" it.  The URL for the Google Plugins is...

Once you add the correct "site", it will be straight-forward  to install the Google plugins for Eclipse.  Select everything: the GWT, the SDK and the plug-in.  (The fries and king prawns come later...)

Eclipse knows how to figure out package dependencies, so it should be sufficient to select the "Google Plugin" or the "Google Web Toolkit".  The version numbers you see will likely be newer than shown below, but anything close to this should be sufficient.

Its a bit odd that the Google packages aren't properly signed, but don't let that bother you.  Click on "OK" when you see this warning.

The rest of the package install is straight-forward: bind your soul to the GPL and  power your way through the remaining dialog boxes.  If you are karmically challenged, you may want to cancel at this point, install the free IDE for "Visual C++ 2010 Express Edition" and brush up on your Visual Basic.  (How about a nice game of Tic-Tac-Toe instead?)

Do not be alarmed if this takes a while.  When you're done, you will be returned back to the primary Eclipse GUI.  

You can spend this time making sure you know where the GIT documentation and bookmarking it in your Firefox or Chrome browser...  

If you do not have Firefox and Chrome downloaded, please fetch them now.  You'll want them later...

Step 8: Resolve any GWT SDK issues

You may run into an odd problem when you first import the project from Git.  If the IDE still reports that the project does not have any GWT SDKs on its build path, you may need to manually ensure that the IDE's classpath includes the GWT SDK by following these steps.

i. right click on the webhack project in the package explorer windows to bring up the properties dialog box
ii. select "Java Build Path" and confirm there is a red "x" icon next to the GWT SDK 
iii. click on the "Libraries" tab and then double-click on the line "GWT SDK [missing]"
iv. this brings up a dialog box for the GWT SDK 
v. select the select the default SDK, click on 'Finish' and then 'OK' out of the original properties box

You will notice that the IDE will initiate a rebuild of the project and the problem will go away by itself.  Wouldn't it be nice if all software problems were that easy to deal with, eh?  

Here are the visual hints to guide you through this odd set of steps...

A proper discussion of what went wrong, how this fixed it and a proper understanding of the "classpath" is beyond the scope of this tutorial, but if it bugs you, let me know and I'll try to address this in a separate posting.

Step 9: Nice to have...

While not required, you may want to download a nice programming font and customize Eclipse to use this.  You can fetch Inconsolata, available on all platforms, from this URL and easily tweak your IDE to use it.

 Inconsolata may be download from...

... once installed, you can tweak your IDE settings under "Windows" > "Preferences" ...

... there are many settings, filter on "font" to find the settings for "Text Font" and "Text Editor ... Font"
I prefer to edit these and set them to Inconsolata 10 point or smaller ...

Step 10: OK, so how do I do something interesting at this point?

First, make sure there are no errors.  Warnings may be ok, but errors are generally fatal and prevent the IDE from building a runnable module.  I'm just going to explain how to get this to run; the theory behind everything is left as another discussion.

"Run" > "Debug As" > "Web Application"

Choices within the IDE are almost always sensitive to context.  If you don't see "Web Application" as a viable choice, be sure you have first clicked on the webhack application in the "Package Explorer" and that the IDE's "focus" is on this project.  You can also right-click on the webhack application and bring up the "Debug As" choice...

Click on the "Console" tab/window to see signs of life, you should observe that the AppEngine has initialized.

Over time, you will see diagnostic information information appease on this "console" window.

Clock on the" Development Mode" tab/window.  You will see the temporary URL at which this application is currently running.  To be more accurate, the application is running as a Java web application inside of a small web server that is running within the Java Virtual Machine environment that Eclipse is also running within.  This is the URL you need to open to interact with this web-based application. 

I suggest you right click and "Open With" Google Chrome.  You will need to "teach" Eclipse where Chrome is the first time you run it, but after that, you should always have the ability to open URLs using Chrome from within Eclipse .

Opps, you did install Chrome as I suggested, right?  If not, go do this now and come back when this is done.

The first time you try to debug an application using Chrome, it will prompt you to download and install the GWT developer plugin for Chrome.  When prompted, do this.  Then reload the URL of your web application, still running in debug mode.

After a small delay, you should see signs that the web application is running.  Success!

Go back to the "Console" window and click on the red square to terminate the running web application.  Eclipse will shutdown the server side of things and Chrome will detect that the web-application has disconnected and let you know.


You have now successfully
- installed the Java SDK to your machine
- installed and configured Eclipse to use git and gwt
- anonymously cloned an existing Git project and imported it into Eclipse
- built your application without errors and successfully ran it as a web application
- run your web application from an external web browser outside of the JVM

May the source we with you.