How to use Eclipse for 162 projects

John Jordan
cs162-ta@imail.eecs.berkeley.edu
Last updated: 4 Oct 2006

Table of contents

  1. Introduction
  2. Getting, Installing, and Starting Eclipse
  3. Getting Nachos from CVS
  4. Importing Nachos from the Filesystem
  5. Running Nachos
  6. Using CVS in Eclipse
  7. Tips for developing with Eclipse
  8. Issues on the Mac
  9. FAQ
  10. Acknowledgments
  11. Revision History

Introduction

IBM has made quite an investment in time and money on the Eclipse project. It is posed as an open source development environment and used to stimulate creativity from academia and the industry. The effort has succeeded in gaining wide popularity from all directions, and has matured into a pretty kick-ass tool. It features on-the-fly error detection (while you type), language-intelligent autocomplete, code templates, a relatively easy-to-use debugger, lite refactoring, and a slew of other cool features. For all these reasons, we recommend that you use it to do your Nachos projects, and it should save you a good amount of frustration.

Unfortunately, learning to use a tool as complex as Eclipse can also generate frustration. That's what the Eclipse website/tutorials/documentation, your TA's, and this document are for. (The TA's as a last resort, please). You should decide if you really want to learn to use it while also learning Nachos and operating systems concepts. Experience with it will certainly pay off, but if you can't really get the hang of it, you may consider falling back on what you're used to.

All that aside, this document is intended to get you set up and hopefully a little bit comfortable using Eclipse.


Getting, Installing, and Starting Eclipse

First you need to download Eclipse from the official web site: www.eclipse.org or straight from the downloads page: www.eclipse.org/downloads/. You should get the latest production release. The SDK is more than you technically need (Eclipse experts: you only need the platform and jdt packages), but download that one to be safe.

Unzip the package into your Program Files directory. If you have an older version of Eclipse, then move it out of the way first (rename it to eclipse-x.xx). In the new eclipse/ subdirectory, there will be a binary called Eclipse. Drag it to your start menu/dock/what-have-you so you can easily run it later.

If you don't have a JVM, then Eclipse will tell you when it starts up. In that case, go to java.sun.com to download and install one.

Go ahead and start Eclipse. When it starts it may ask you for a workspace. Use the default or create a directory in a documents folder and point it to that. Next you'll see a purple welcome screen. Take the tutorial linked from there. Make sure you learn the following terms from it: workspace, project, perspective, view, editor, annotation, run profile. Now you're ready to go to the workspace and get started!


Getting Nachos from CVS

First, see the CVS Quick Start guide. This will guide you through setting up the initial repository. It must only be done once per group, so ask your groupmates if it's taken care of. Once that's done, you can check out Nachos in Eclipse.

To access your group repository, you need to download your private SSH key from your user account:

On Windows, use a tool like WinSCP to copy your ~/.ssh/cs162-## key to your local machine.

You will add the downloaded SSH key to Eclipse's list of private keys which is in Preferences under Team > CVS > SSH2 Connection Method. Click Add Private Key... and navigate to your private key to add your SSH key. Click Apply.

First you need to set up Eclipse to connect with your CVS repository. Start by switching to the CVS Repository Exploring perspective. Do this by going to WindowOpen Perspective. Then right click in the CVS Repositories view (on the left) and select New > Repository Location. You will get this window:

Now you will create a project by selecting File > New > Project.... First, create a Java project.

Give the project whatever name you want. Nachos is kinda boring. It could very well be Evil 162 Project, or Nachos, eater of sleep. You don't need to use Java 5.0 (also known as Java 1.5), but templates and foreach loops can come in handy sometimes. Java 1.4 will work just as well. Be sure that everyone in your group agrees on what version of Java to use.

From there you can go ahead and click the Finish button. Eclipse will probably ask if you want to switch to the Java perspective. You should click yes. If it did not prompt you and the screen doesn't change, then manually switch into it. You should use this perspective to do your coding.

Next, you need to check out Nachos from CVS. You can cheat and do this from the new project screen. Select the Checkout Projects from CVS wizard as shown:

The next steps are:

Or, pictorially:

Now, you should have a new and hopefully healthy Nachos project to work on.


Importing Nachos from the Filesystem

If you are using CVS then you need not follow the instructions here. If you have a copy of Nachos on your filesystem that you would like to run, then follow these instructions.

If you don't have it then download Nachos from the Projects page of the CS 162 website. When you decompress it, you'll find a directory called nachos/. Put this directory into some new directory (call it something like project/ or Nachos/).

Select File > New > Project.... Select the Java Project wizard, and continue to the next screen:

Once all this happens, Eclipse will start to compile Nachos. It may come up with a lot of warnings, but if there are errors, you should make sure that the Java compliance is correct. To do this, right click the top-level project from the package explorer (on the left), and go to Properties. Then go to the Java Compiler option and ensure that the proper version is being used. If errors persist, then ask the newsgroup (or see the FAQ).

Your Nachos project should now be set up.


Running Nachos

To run anything in Eclipse, you need to create a run profile. Do this by selecting Run > Run.

Next you should check that Eclipse will use the correct version of the JVM.

Lastly, go to the Common tab and have the profile displayed in both favorites menus.

Once you have a run profile for one phase, you can copy and paste it three times to get all the run profiles you'll ever need (right-click on Phase 1 and select Duplicate). All you need to do is rename and point each to the proper startup directory from the Arguments tab.

Now that you have run profiles, you can run Nachos! Go up to the run button (it's green and has a play symbol on it) and click the arrow to its right. You should see your run profiles there. Select Phase 1 and watch it go! The output is displayed in the Console view at the bottom.

You can use the debugger if you start Nachos in debugging mode. The only thing to do differently is to use the bug instead of the play button. Then, Eclipse will pause execution on breakpoints and some exceptions. More on this later.


Using CVS in Eclipse

Everything you need for CVS from now on is available from the Java perspective, if you followed the instructions in the Getting Nachos from CVS section above. Simply right-click on any item in the package explorer, and use the Team menu as shown:

Commit and Update are really the only two features you will need. They behave the same as the cvs commit and cvs update commands as described in the CVS Quick Start guide. Whichever items are selected in the package explorer (in this case, the top-level project) are the items that CVS will operate on, and possibly recurse over.

You will notice that files and packages that have been modified in your local copy will be denoted by a > in front of its name in the Package Explorer view. These are the files that you will probably want to commit to the repository when you are finished working. Additionally, you should always update from the top-level node (the project) immediately before you commit anything, so you can deal with conflicts as soon as possible.

You should always update from the top level, but you should commit on individual files (and not packages) in an effort to keep your repository free of .class files and other nasty Eclipse meta-information. Committing these things will tend to tick off your groupmates.


Tips for developing with Eclipse

Here's a list of topics that should get you well on your way to using some of the features in Eclipse. There are far too many to list in one place, but I consider these to be among the most important and the ones I use most frequently. Explore the menus when you right-click in different places and see what happens when you press some random key combination. Also observe other people using it. This is how you get good at using your editor (I mean, who reads documentation?). Also note that Eclipse has an emacs keybindings option, but I would strongly advise against using them.

Dealing with Eclipse's attempts to assist you

As you begin to use Eclipse, you will discover that it tries to do lots of little things for you. You may find that it works against your habits or that characters start to appear on the screen that you did not type. Instead of fighting against Eclipse, just continue to type as you normally would. If you are forced to correct something that Eclipse does, then try starting the line over and figure out what Eclipse did that caused you to err. You might find that if you learn how it's trying to help, you will work a little faster.

For instance, when you type a character that will later match with another character (e.g., ( [ { or "), it will insert the matching character for you. Don't delete them, just keep typing. When you get to the closing character, you can just type it, and it will advance the cursor past the one it inserted earlier if there is a green bar to its right. If the green bar is accompanied with a grey box, then you can hit Enter to skip past all the following closing characters, such as here:

Useful hotkeys:

Ctl-Space: Auto-complete, the mother of all hotkeys. Start typing an identifier, and Eclipse can figure out the rest with this hotkey. You can also expand templates with this key (for instance, type sysout and hit control-space).

Ctl-S: Saves the current file.

Ctl-D: Deletes the current line.

Ctl-Left and Ctl-Right: Moves the cursor left or right by one word. It is beneficial to get into the habit of using these hotkeys.

Ctl-Backspace and Ctl-Delete: Deletes the previous or next word.

Alt-Up and Alt-Down: Moves the the current line or current selected lines up or down by one line (displacing the line that was there).

Ctl-I: Corrects the indentation of the current line or selected lines.

Ctl-Shift-M: Finds and imports the identifier that the cursor is on. For instance, you want a Hashtable but haven't imported java.util, just type Hashtable and press this hotkey.

Ctl-1: Auto-fix. Try pressing this while the cursor is on an eclipse error marker. In some cases, Eclipse can fix the error automatically (for instance by surrounding statements with try/catch).

Debugger features

Breakpoints: Absolutely essential for debugging purposes. They can be added or removed by double-clicking in the gutter of the editor. When the line of code associated with the breakpoint is executed in debug mode, Eclipse will pause the program and go into the Debug perspective. From there you can do all sorts of useful things to fix code. The breakpoint is the blue dot shown here:

Breakpoints on exceptions: You can additionally have Eclipse pause execution when certain Exceptions are thrown. You can add them in the Breakpoints view in the Debug perspective:

Variables and the stack: When Eclipse is paused on a breakpoint, you can examine the current values of local variables in the Variables view. To look at values in other stack frames, select a stack frame from the Debug view (on the top left), and the variables on the right will update.

Value inspection: Another trick when Eclipse is paused is that you can evaluate the result of any expression that is in scope. Just highlight an expression, right-click, and Inspect it (or type Ctl-Shift-I):

Stepping: To step through the code while it is paused, you should use F5, F6, and F7, which are Step Into, Step Over, and Step Out Of, respectively. Stepping into will step into whatever method needs to be called next or to the next line of code if there is no more to do on this line. Stepping over will go to the next line of code. Stepping out of will return from the current method. The green bar always selects the line that is about to be executed.

Refactoring

Renaming: Eclipse can automatically rename variables and fields for you. Unlike Find/Replace, it will only change the instances that refer to the same entity. Right click on an identifier name and select Refactor > Rename.

Extracting methods: If you find that you are repeating code a number of times, you can easily make it into a private method. Highlight one instance of the duplicated code, right-click, and select Refactor > Extract Method. Eclipse will determine the necessary arguments, create the new method, and replace what was highlighted with a call to the new method.

Navigating code

Jump to declaration: When you want to go to the declaration of a certain identifier, simply put the text cursor on it and press F3.

Type hierarchy: To see a treeview representation of a class's inheritance hierarchy, put the cursor on the class name and press F4.

Searching for references: To see all of the places where an identifier is used, right click on it and go to References > Workspace.

The Outline view: This view is shown on the right in the Java perspective and is very handy for getting around your classes. Use it to go from one method to another when you can. It's a good idea to keep it sorted (the a-z button does this).


Issues on the Mac

To use Java 1.5 on OS X for Eclipse and Java command line tools, take a look at http://www.macosxhints.com/article.php?story=20060121171126988 (mirrored here). The setJDK script from the article can be found here.

If you have difficulty running Java command line tools on Powerbook G4, take a look at http://www.macosxhints.com/article.php?story=20050426014905678 (mirrored here).


FAQ

No one has asked questions yet. Therefore, this section is incomplete. We'll look through the newsgroup and add some stuff here.


Acknowledgments


Revision History