View source for Slicer3::Debugging with Eclipse Instructions

There are a few  key things about interactive debugging under Eclipse that once are done right, then it just works:

# build Slicer totally first the normal way, either with cmake or getbuildtest.tcl. 
# Create the project in Eclipse by referring to the makefile and entering an external make command line

Instructions for the build steps can be found at [[Slicer3::New_Eclipse_Instructions|http://www.slicer.org/slicerWiki/index.php/Slicer3::New_Eclipse_Instructions]]

Assuming that Slicer is building under Eclipse, we'll take off from this point on:

==Understanding Slicer's startup process==
The executable xxxx/Slicer3-build/Slicer3 is not the real program, instead it is just a "launcher".   This executable sets up a bunch of paths and environment variables, then launches the real executable.   The "real" Slicer3 program is stored in:  xxxx/Slicer3-build/bin/Slicer3-real.    So when we are asking Eclipse to run Slicer under the debugger, we really want Eclipse to startup and attach to an instance of "Slicer3-real".  

'''Step 1:''' There is a script in xxx/Slicer3-build/bin/Slicer3SetupPaths.sh or Slicer3SetupPaths.csh which sets up the same paths as the launcher.  If we run this script in a shell window (on Mac or Linux), then run eclipse from the same shell, we will have the environment defined.  This is how to try it the first few times, but there is a cleaner way we will try after we know debugging is working.   So if you are on either a Mac or Linux, open a shell and source this setup script, please. 

Then in the same shell, start eclipse.  It will be something like this:

#% source /usr/local/slicers/trunk/Slicer3-build/bin/Slicer3SetupPaths.sh
#% ~/Desktop/eclipse/eclipse &

'''Step 2:''' Then in the Eclipse window, open the Project/Properties by right-clicking on the Project Explorer entry for your Slicer build.  Then select the "Run/Debug Settings" entry.  We want to set the executable to point to "Slicer3-real" instead of "Slicer3".  This plus running the script in the shell Eclipse was started from *may* be enough to get the debugger started on Slicer.    

If you are using a Mac, shared library loading can be slow and gdb can timeout during Slicer's loading process.  I have not had this problem on Linux and can't comment on Windows since I have not tried it in under Windows.  It was helpful on Mac under Leopard and Snow Leopard to increase the default timeout allowed by Eclipse if your Mac needs a bit more time to get everything initialized when first beginning a debugging session.

== Note to Snow Leopard users ==
In the Summer of 2010, we found moving to Snow Leopard caused debugging to stop working.  The newest (nightly build) of Eclipse was needed to get breakpoints to actually force the program to stop again.  Debugging worked without tweaking Eclipse for systems running Tiger and Leopard.  However, the 64-bit only mode of Snow Leopard meant a 64-bit Eclipse is needed for debugging.   It is expected that these issues will be resolved in the release version of Eclipse 3.6 (Helios). Do remember that debugging only works using a 64-bit version of Eclipse  on Snow Leopard (because the build is now a 64-bit build.)