Getting started with Eclipse

Here I'm keeping notes on how I get going with Eclipse.

§ Caveat

As of July 2008, I have given up on Eclipse. Each release seems more unstable than the last, and I've gotten tired of finding new ways to stop it from crashing.

Here are my notes on Netbeans: [ Using_Netbeans_with_an_existing_project.html ]

Netbeans is much easier to set up, and it is quite intuitive to a former Eclipse user. It is also pure Java, without the native code bugs of SWT.

If you can afford it, IDEA is even better: [ Idea_notes.html ]

§ My original project

My project is under CVS control, with an ant build.xml, and a directory tree like the following. Let's call my project "foo".

. |-- build | |-- cls | | `-- com | | `-- acme | | `-- foo | |-- javadoc | `-- obj |-- data |-- dist | |-- bin | |-- doc | `-- lib |-- doc |-- etc |-- jar |-- src | |-- com | | `-- acme | | `-- foo | |-- cpp | `-- scripts `-- test

The src directory contains all source code for compilation. Everything is under source control. No files created by the build should go in here.

The build, dist, and test directories are created dynamically by the ant build and are not in the CVS repository. Classes, javadocs, and compiled C++ objects are compiled into the build directory. Jars and C++ shared-object archives are created in the dist directory. The dist directory looks exactly like what goes on a release CD. It has everything of interest to a client. The unit tests (JUnit) run inside the test directory and use only files inside the dist directory. Test log files are also formatted into the test directory. An ant clean simply removes these three directories.

The remaining directories are under CVS control and do not change during a build. Some of each may be copied to the dist directory for release. jar contains third-party jar files only, not those created by the build. doc contains human-edited documentation (not javadocs). The build may do some formatting of these for distribution. etc contains runtime configuration files, such as logging properties. The data directory contains small datasets for running tests.

§ Installing Eclipse

First of all, I got the latest milestone build from http://eclipse.org/downloads/index.php with support for Java 1.6. Their last few releases have been great improvements. I've heard of no problems with milestone builds.

I download the linux zip file with the letters "SDK" and "gtk" in the name.

I unzip the distribution in a convenient location like /usr/local/eclipse and create an alias.

alias ecl="eclipse -data $HOME/projects -vmargs -Xmx700m -XX:MaxPermSize=256m"

The -data argument sets the base directory for all projects to a convenient location.

I was warned to increase the VM memory because it is very difficult to clean up after an out-of-memory crash.

The MaxPermSize seems to prevent another common variety of crash: http://www.eclipsezone.com/eclipse/forums/t77021.html This obscure JVM parameter defaults to too small a value. Recent releases of Eclipse are understood to fix this problem.

I also set JAVA_HOME to point to my JDK installation. Eclipse seems to use this to set paths.

§ Basics

I start up the GUI and see some big icons for documentation and tutorials.

Set defaults for new java projects. Go to the menu bar and select Window -> Preferences -> Java -> Build Path. For the directories, I described earlier, I select the "Folders" button and set "Source folder name" to "src" and set "Output folder name" to "build/cls". Hit "Apply." You might also check the defaults for "Ant." Mine were correct.

Set your compiler level. First, go to the menu bar and select Window -> Preferences -> Java -> Editor -> Installed JREs and make sure it is correct. It should be if you defined a JAVA_HOME. Go to the menu bar and select Window -> Preferences -> Java -> Compiler and select "1.6" or whatever as your "Compiler Compliance Level." Hit "OK."

§ Creating a Java project from new CVS checkout

It may be necessary to warn Eclipse that you are going to be interested in java projects. Click on menu bar Window -> Open Perspective -> Other -> Java (Default). New panels will appear that we will find useful later. You can switch between perspectives with buttons at the upper right. (This step ensures that you will be given a choice to create a java project during the next step.)
Identify your CVS repository. Go to the menu bar and select Window -> Open Perspective -> Other -> CVS Repository Exploring. New tab pane for "CVS Repositories" appears. Right click in this pane and select New -> Repository Location. Fill in the CVS information for your server and repository, click "Save Password," and hit "Finish."
A new repository should have appeared in your "CVS Repositories" tabbed pane. Expand it, then expand HEAD until you see your project name "foo". Right click on "foo" and select "Check out as..." to get a wizard with the same name. Select "Check out as a project configured using the New Project Wizard." For "Select Tag" I choose "HEAD" then hit "Finish." At this point you should get a panel labeled "New Project." (If not, then Eclipse was not warned sufficiently that you are interested in java. Don't skip the previous steps. To recover, return to the "Java Perspective," right click in the left panel and select "New" -> "Java Project.") Select "Java Project" and hit "Next."
You'll get another panel labeled "New Java Project". I choose the same project name "foo" as for the repository. I leave the check in the box for "Create project in workspace" and for "Create separate source and output folders." If you click the "Configure Defaults" button, you should see the locations you typed in earlier. Hit "Finish". You should see a dialog "Confirm Perspective Switch" asking if you want to switch back to the Java Perspective. Answer "Yes." You should see a progress dialog checking out all your code. If you did not get the Java Perspective, open it from the menu.
If you prefer, you can create a project from an already existing CVS tree. Go back to the default Java view Window -> Open Perspective -> Other -> Java (Default) and click on the big Package Explorer. Or go to Window -> Show View -> Package Explorer. Right click on the Package tab pane on the far left -> New -> Java Project -> New Java Project pane. Fill in "foo" for the Project name, and click Contents-> Create project from existing source. The wizard configures everything automatically from the existing source.
At this point, Eclipse will attempt to compile your code. Some of my compilations fail because they cannot find the third-party jars. The default build created a build/cls directory with the expected hierarchy of class files. Unfortunately all other non-java files under src were simply copied verbatim.
We must now change these assumptions.

§ Configuring the project build

Make sure you are in the Java perspective by looking at the button at the upper right. Right click on the new "foo" project on the "Package Explorer" tabbed pane and select "Properties." Look at all the items here.
Add external jars to your build path. First I define a variable for each jar. Select "Java Build Path" -> "Libraries" -> "Add Variable" -> "Configure Variables" -> "New". Then I define a name like JUNIT_JAR for the junit.jar in my jar subdirectory. Hit "OK" twice to return to the "Libraries" tabbed pane. Hit the "Add Variable" button, select the named jars, and they should appear on the list of libraries. Hit "OK" again. The build should start again.
Some standard extensions may not be resolved even though command-line compilation would not have a problem. For the javax.jnlp package , add $JAVA_HOME/jre/lib/javaws.jar as an external jar.
Again, right click on the new "foo" project on the "Package Explorer" tabbed pane and select "Properties." Select "Javadoc Location." For the "javadoc location path" I select the "$HOME/projects/foo/build/javadoc".
Go to "Window" -> "Preferences" -> "Java" -> "General" -> "Startup and Shutdown" and check "Refresh workspace on startup"
Go to "Window" -> "Preferences" -> "Java" -> "Installed JREs", highlight your JDK and hit the Edit button. For "Default VM Arguments" I add "-ea -server".

§ Style preferences

Go to "Window" -> "Preferences" -> "Java" -> "Compiler" -> "Errors/Warning" and ignore only the following errors.
Code style:
- Unqualified access to instance field
- Undocumented empty block
- Access to a non-accessible member of an enclosing type
- Parameter assignment
- Usage of non-externalizable Strings
Potential programming problems
- Boxing and unboxing conversions
Unnecessary code:
- Parameter is never read
The rest of the Ignores are changed to Warnings.
I check all boxes along the way.

Go to "Window" -> "Preferences" -> "Java" -> "Compiler" -> "Javadoc" and enable warnings for missing or malformed comments or tags. Here are the options I set, within brackets.

[X] Process Javadoc comments.  
Malformed Javadoc comments: [Warning]
  Only consider members as visible as: [Private]
  [X] Validate tag arguments (@param...)
    [X] Report non visible references.
    [X] Report deprecated references.
  Missing tag descriptions: Validate all standard tags

Missing Javadoc tags: [Warning]
  Only consider members as visible as: [Protected]
  [X] Check overriding and implementing methods
Missing Javadoc comments: [Warning]
  Only consider members as visible as: [Protected]
  [ ] Check overriding and implementing methods

Do NOT check the final box. It would require the bad practice of overriding inherited javadocs

To disable warnings from third-party code that I compile, I go to the problems tab at the bottom of the java perspective, open the menu under the triangle at the top right, and select "Configure contents." Hit the "New" button and give a name "foo" to "Add New Filter." Click "On Working set" hit select to create a new one. I give it a name "foo." I select a range of packages that I want to "Add" and hit finish. Back on the "Configure" panel, I select errors, warnings, info, and "Select All" on the Type. Finally hit "OK."
I go to "Window" -> "Preferences" -> "Java" -> "Code Style" -> "Formatter" -> "Show" button on right -> "Show Profile 'Eclipse [built-in]'" panel.
On the "Indentation" tab, I set "Tab policy" to "Spaces only" and indentation and tab size to 2.
On the "Braces" tab, I leave everything on the default "Same line."
I accept defaults for the "White Space" tab.
On the "Blank Lines" tab, I set 0 "Before field declarations."
On the "New Lines" tab, under "Insert new line", I check "at end of file."
I accept defaults for the "Control Statements" tab.
On the "Line Wrapping", and "Comments" tab, I set "Maximum line width" to 72.
On the "Comments" tab, I check all boxes except for the "New line after @param tags." I add checks for "Format header comment" and "Clear blank lines in comments."
After closing this panel, you will select a name for the profile. Later you can return and edit this selected profile at "Window" -> "Preferences" -> "Java" -> "Code Style" -> "Formatter".
Go to "Window" -> "Preferences" -> "Java" -> "Code Style" -> "Code Templates". Under Comments I remove nested asterisks, unnecessary blank lines, and the @author tag.
Go to "Window" -> "Preferences" -> "General" -> "Editors" -> "Text Editors" and change "Displayed tab width" to 2. Check "Show print margin" for a margin of 72. Check "Show line numbers."
To edit in emacs-mode, go to "Window" -> "Preferences" -> "General" -> "Editors" -> "Keys" -> "Modify" tab -> "Scheme" -> Emacs

§ Shortcuts

The single most useful hotkey is probably F3, to get the declaration of a variable.

Here are some more

http://www.javaworld.com/javaworld/jw-08-2005/jw-0829-eclipse.html

§ Vi plugin

I've been very happy with the Vrapper plugin for vi editing mode.

Go to Help -> Install New Software -> Work with: http://vrapper.sourceforge.net/update-site/stable then check the box next to Vrapper and Next and Finish.

You'll need to restart all of Eclipse, not just the Perspective.

One installed correctly, you should see a new toolbar option Edit -> Toggle Vrapper.

To continue to get updates, Go to the menu bar (Window -> Preferences -> Install/Update -> Available Software Sites -> Add ...) and add the Location http://vrapper.sourceforge.net/update-site/stable, if it is not already present.

§ Miscellaneous

Sometimes Eclipse may get confused about dependencies and neglect to recompile. This usually appears for me as a missing class from a package elsewhere in the project. To trigger a complete rebuild within Eclipse go to the menu bar and run Project -> Clean.
I have decided to use ant only from the command line. But you can also use it from Eclipse. Right click on the new "foo" project on the "Package Explorer" tabbed pane and select "Properties." Specify "Builders" -> "New" -> "Ant Build" to get a "Properties for New_Builder" dialog, which I rename as an "ant_builder". On the "Main" tab I select "build.xml" as the buildfile and "${workspace_loc:/foo}" as the default base directory. On the "Targets" I replace the default for manual and clean builds by my particular words "build, javadoc". This change does not affect the automatic builds. I move my ant builder up above the "Java Builder" and leave both checked. Then I go to the menu "Project" -> "Build all".
To upgrade Eclipse, use the update manager: http://www.eclipse.org/eclipse/platform-releng/updatesfor3.1.1.html

Bill Harlan, 2004-2006

Return to parent directory.