Introduction

I am both: a newbie to Eclipse, and a dinosaurs doing everything in Emacs, but times are changing, and no Emacs extension can beat Eclipse on its code assist support, and on few other features (which is true also vice-versa: Eclipse still cannot beat Emacs on many features, but that's another story). So I started to play with jMoby in Eclipse.

Because it was painful (I have yet to find a good reference guide for Eclipse) I would like to share my experiences here. Please feel free to add there yours, or correct my observations. Also, there are "more ways to do" in Eclipse (but not as many as in Perl ) so the steps described below may not represent the only way, and I do not claim that are the most efficient - but TGT (The Good Thing) is that they work.

jMoby is just like any other Ant-based Java project. It has its own build.xml and it has many nicely-tuned Ant's targets that we would like to continue to use when we put it into Eclipse. The problem how to incorporate an existing project (an Ant-based project) into Eclipse is documented many times, even in the Eclipse help system itself. The problem is that most of these descriptions are not detailed enough, or they do not reflect exactly goals we would like to achieve. So, what are these goals...

Preconditions and Goals

We would like to keep jMoby in a stand-alone directory, checked-out from its CVS (using an independent CVS client). So we can continue to use also outside Eclipse (once it is in there). In the same time, we would like to make the CVS operations available also from within Eclipse.
We would like to call all Ant targets either from a command-line or from Eclipse. So we must make sure that both command-line Ant and the Eclipse build system will create classes in the same place (and in jMoby there is more than one such place).
And, of course, we want to have access to all nice Eclipse features, like code assist or hierarchy views (so just calling our Ant targets from Eclipse is not enough).

How to do it

For the steps described below, I was using Eclipse 3.1, on Windows and on Linux. The steps do not cover installing Eclipse itself.

Check-out jMoby from its CVS repository

You probably already have done this. The details are in a separate document. Remember that you are using one of the following CVS locations/protocols. For developers with write access, use:

:ext:your_username@pub.open-bio.org:/home/repository/moby

For read-only, use an anonymous access:

cvs -d :pserver:cvs@cvs.open-bio.org:/home/repository/moby

In both cases, you are interested in module moby-live/Java.

By the way, the best CVS client for Windows I know is CVS Tortoise.

Start Eclipse

Open your Eclipse with a workspace that is not the same place as where you checked-out your jMoby local copy. At the beginning, I had my workspace being the same directory (my Desktop actually) where I had also jMoby as its subdirectory. Because of that, I got later error reporting an overlap between the jMoby and workspace. (But I remember that the problem occurred only on Windows, not on Linux.)

You can change the workspace either from File -> Switch Workspace, or by starting Eclipse with a command-line argument -data <directory-name>. If you use more workspaces, it is useful to start Eclipse always with a command-line argument -showlocation - then the path of the current workspace is shown in the window title.

Integrate Maven plugin

As JMoby uses Maven we need to enable Maven in Eclipse. The Maven plugin requires two other plugins which we need to load.
Help -> Software Updates -> Find and Install -> Search for new features and install will open a dialog which shows all existing update sites your Eclipse already know.

For each of the plugins please open New Remote Update Site and add the following sites and install them (make sure that you unselect optional components of the plugins if they produce errors):

Name: Buckminster
URL: http://download.eclipse.org/tools/buckminster/updates
Name: Subversion
URL: http://subclipse.tigris.org/update_1.2.x
Name: Maven
URL: http://m2eclipse.sonatype.org/update/

After install the plugins please restart Eclipse to enable the Maven plugin.

Create a new CVS repository location

Window -> Open Perspective -> Other -> CVS Repository Exploring. Then right-click and New -> Repository Location. As a developer, use connection type ext (not extssh - that would prevent you to do CVS operations outside of Eclipse), as a read-only user, select connection type pserver.

Important: selecting ext means that an ssh protocol will be used to get to the CVS repository. So you need to have an ssh client on your machine to do so. You can use a separate client, or the one which is embedded in Eclipse. By default, Eclipse is looking for an external program called ssh - which it usually finds on Unix systems but not on Windows. That's why on most Windows machine you need to explicitly tell Eclipse to use its own embedded client (the client is called extssh but you could not put it directly in the CVS location definition because it would prevent you to use CVS operations outside of Eclipse). So do the following: Window -> Preferences -> Team -> Ext Connection Method, check Use another connection method type to connect, and select extssh.

Create a new project

File -> New -> Project. Select Java -> Java Project.

Type a project name (I use jMoby), check Create project from existing source, and type the name of a directory where you have checked-out your jMoby local copy.

Now you have jMoby data loaded in - and you may see many problems (in the bottom window). This is because Eclipse does not know yet enough about where jMoby has things and how it uses them. But before we fix that let's do one more thing...

Telling Eclipse the classpath

We need to tell Eclipse now the building structure of JMoby, so that it knows where which source files are and to where it has to compile what.
For that (and only for the first time you set up Eclipse and JMoby) rename the .classpath.template from the checkout to .classpath (and by that overwrite the .classpath file generated by Eclipse) and refresh your project either by right-click on the project and selecting Refresh or by just hitting F5.
You will now see the new source folder structure. In the case you dont have a generated/skeletons and generated/datatypes folder shown up as source folder please add this two folders. Eclipse will then automatically recognize them as source folders.

Gather 3rd-party libraries and set up JMoby

Now it's time for our real libraries. Open an Ant view by Window -> Show View -> Ant. Then right-click and select Add Buildfiles. Select build.xml from jMoby. You can Hide internal targets by clicking on the stroke green target icon.

Double-click on install. It shows progress in the bottom of the screen in a console window. After that you may Refresh your workspace.

By the way, from now, you can use any listed Ant target by double-clicking. This is almost the same as you would invoke the Ant from a command-line. More about individual targets is elsewhere in the jMoby documentation (e.g. about general targets, or about Moses).

When the task is finished, double-click on initeclipse, which will generate the file pom.xml which the Maven plugin requires to work correctly. After the task refresh your workspace and right-click on the project Maven -> Enable Dependency Management. This will now tell Eclipse to use the maven repository for the build path.
By now all your erros should be erazed and you only see several warnings (if you still got errors check here)

Fix `javadoc` location

Ant's targets using javadoc (such as docs or moses-docs) may fail reporting an error CreateProcess...javadoc.exe.... This is because the executable javadoc.exe was not found. Eclipse has not impressed me here: it can find java but but javadoc (even though I am aware that javadoc in this case is considered as an external tool). So you need to tell where is your javadoc.

Either outside of Eclipse: add it to the environment variable PATH (a usual way). Or inside Eclipse (but here I know only how to set it for an individual project, not generally): Run -> External Tools -> External Tool -> Ant Build -> jMoby build.xml, select tab Environment -> New, and create a new environment variable PATH and give it directory where is javadoc, e.g. c:\Program Files\Java\jdk1.5.0_05\bin.

Running jMoby command-line scripts

jMoby has a few scripts that can be invoked from a command-line with number of arguments. From the Eclipse point of view, they are the same as any other external tools. Perhaps the only difference is that they must be first copied from their source directory (src/config) to their destination place (build/run). The copying is not used because it matters where they are invoked from, but because they are not only copied but also updated. That's why - before you use them - you need (at least once) to run a jMoby Ant's task compile or config. Eclipse own compilation (called building) is not enough, it does not copy the scripts.

Once you have them in build/run you can run them from Eclipse (as always with external scripts, you type more the first time you use a script, but Eclipse remembers it and the next time you will see already your script name in a menu): Run -> External Tools -> External Tools -> Program -> New. Name it (e.g. run-cmdline-client), and Location -> Browse Workspace to select it (in our example find and select build/run/run-cmdline-client.bat). Most of these scripts have an option -help - so put it in Arguments - and change it each time you wish to invoke them with different arguments.

Misc

The project name now should have attached the CVS location. If not you have to help Eclipse: Right-click (jMoby) -> Team -> Share. Try CVS update from Eclipse: (jMoby) -> Team -> Update. Remember that whenever you do CVS update outside Eclipse you need refresh Eclipse: F5 or (jMoby) -> Refresh.

And, of course, for us, dinosaurs, change Windows -> Preferences -> General -> Keys -> Modify -> Schema to Emacs.

Good luck.

Martin Senger

Last modified: Thu Feb 21 19:43:36 2008