** 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 *

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

o 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.

o 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 *

--

o 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.)

o 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."

o 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."


o 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.

o 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.

o 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 *

--
o 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.

o 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.

o 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".

o Go to "Window" -> "Preferences" -> "Java" -> "General" ->
"Startup and Shutdown" and check "Refresh workspace on startup"

o 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 *

--
o Go to "Window" -> "Preferences" -> "Java" -> "Compiler"
-> "Errors/Warning" and ignore only the following errors.

Code style:

--
o Unqualified access to instance field
o Undocumented empty block
o Access to a non-accessible member of an enclosing type
o Parameter assignment
o Usage of non-externalizable Strings
_

Potential programming problems

--
o Boxing and unboxing conversions
_

Unnecessary code:

--
o Parameter is never read
_

The rest of the Ignores are changed to Warnings.

I check all boxes along the way.

o 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

o 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."

o 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".

o Go to "Window" -> "Preferences" -> "Java" -> "Code Style" ->
"Code Templates".  Under Comments I remove nested asterisks,
unnecessary blank lines, and the @author tag.

o 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."

o 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 *

__

o 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.

o 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".

o To upgrade Eclipse, use the update manager:
http://www.eclipse.org/eclipse/platform-releng/updatesfor3.1.1.html

_

Bill Harlan, 2004-2006