VIVO development can be made easier by running VIVO with a debugger. The ability to set breakpoints, see the values of variables, and follow the program flow can frequently save the a lot of time.

These instructions tell how to connect the Eclipse debugger to Tomcat, running as an remote application. This is only one possible configuration. We welcome input from developers who have used other configurations. When is one configuration better than another?

These instructions assume that you are working with a released version of VIVO. If you prefer to get VIVO directly from the Subversion repositories, your process will be slightly different.

These instructions were written using Eclipse 3.7 (Indigo) and Tomcat 7.0, running on Mac OS X 10.6 (Snow Leopard).

Obtain and install VIVO

Get the latest release of VIVO from SourceForge at
VIVO Application Source

Unpack the release, configure and install VIVO according to the instructions in install.html.

Create a VIVO project in eclipse

This is one way to do it, which will work with a released copy of VIVO. If you prefer to get VIVO directly from the Subversion repositories, your process will be slightly different.

• Remove the .build directory from your VIVO install directory. If this directory is present when you create the Eclipse project, you will need to remove all of its source directories and JAR files from your project.

• In Eclipse, create a new Java project. Uncheck the box for “Use default location” and use your VIVO installation directory instead. Click on “Finish”.
  
  

• In the Problems view in Eclipse, you will see error messages saying that some types are already defined. This is because of the way that VIVO source files overlay some of the Vitro source files. You can ignore these messages, or you can remove the Vitro source files that are causing them.
  

Create a debug script for Tomcat

Tomcat will start in debug mode if a few simple environment variables are set. The easiest way to do this is to start Tomcat with a script. For example, you can create a script called debugTomcat that looks like this:

• The value of dt_socket for JPDA_TRANSPORT says that Tomcat will use a socket connection to Eclipse.
• The value of “8000” for JPDA_ADDRESS is arbitrary, but must match the port number that you will set for the Eclipse debug configuration.
• The value of “y” for JPDA_SUSPEND means that Tomcat will not begin running until the connection with Eclipse is established. This is very helpful if you are debugging the startup code in VIVO.

Create a debug configuration in Eclipse

You need to set the parameters for connecting Eclipse to Tomcat. This is mostly a matter of accepting the defaults for an external application. Assign a name to the configuration and make sure that the correct project name is selected. Then click “Apply”.

Set breakpoints in the code

You can add or remove breakpoints at any time, but if you are debugging code that runs when VIVO starts, you will want to set the breakpoints before starting Tomcat.
To set a breakpoint, open the source file, move your mouse to the left margin of the line where you want the break, and right-click. The context menu that appears should include the option to “Toggle Breakpoint”.

Start Tomcat in debug mode

Use the script that you created to start Tomcat. Note that Tomcat will wait for the connection to Eclipse, so you will not see any new entries in the log, or any signs of activity until the connection is made.

Start debugging in Eclipse

Select the debug configuration that you created and start choose “Debug” .

Ending the session

You can stop Tomcat as you usually would, or you can choose to terminate it from within Eclipse. You can also choose to disconnect Eclipse from Tomcat which will allow Tomcat to continue running normally.