Using the DDT Debugger

DDT is a debugger from Allinea with a graphical user interface for debugging Fortran, C, and C++ programs that have been parallelized with MPI. Additional information can be found at http://www.allinea.com/index.php?page=48 Often programs are debugged by inserting print statements into the program and then running the program and examining the values printed out. However, it is much faster and much easier to use a debugger, such as DDT, to find program errors instead of inserting print statements.

The following is a list of the important functions allowed by DDT:

• Stepping though the program one statement at a time and displaying all variable values.

• Running the program to a selected statement where a breakpoint has been set and then displaying variable values.

• Stepping into and out from functions/subprograms.

• Running a program and having the program stop execution where a problem occurs. Then one knows where the program stopped execution and values of variables at that point.

• Stepping can be done with all MPI processes stepping together or selected MPI processes stepping independently.

DDT sends displays to your desktop using X connections. To find out if your desktop computer accepts X connections enter: xterm -e tcsh If your desktop machine accepts X connections, then this command will open a window. If your desktop does not accept X connections, then you will need to find another desktop computer to be able to use DDT.

For many desktop machines, logging onto hpc-class with ssh -X provides the needed information DDT needs to send its display to your desktop. If not, then you can do the following:

• To tell hpc-class which machine to display the DDT window on, when logged onto hpc-class enter: setenv DISPLAY desktop_machine_name:0.0 For most machines you can find desktop_machine_name by issuing echo $REMOTEHOST on hpc-class.

• To allow access to the X display on your desktop, enter on your desktop machine: set xhost +hpc-class.iastate.edu This is needed at login, so you should put this is your .login or .cshrc startup file (or .cshrc.mine on a Vincent machine).

The following lists the steps needed to use DDT on hpc-class:

Step 1: Compile with the -g option, e.g. for Fortran use: mpif90 -g prog.f90 (If you also want checking for out-of-bounds array references, add the -C option.)

Step 2: Enter: ddt a.out Two DDT windows should then pop up. At the lower left portion of the Session Control Window (the smaller of the two windows), there is a box for the number of nodes needed for the MPI job. (DDT is set up for 2 MPI processes/node and the ISU license allows no more than 16 nodes.)

Step 3: Select the Submit button in the Session Control Window. The Session Control Window will disappear and the program is now ready to be executed under the control of DDT. The remaining window is likely small, so it is a good idea to "maximize" it.

Step 4: In the Project Files Window (left center), select the source file for the main program. The source code for this file will then appear in the center window.

Step 5: Setting breakpoints. Scroll to the statement and right click on this statement and select "add breakpoint";. This sets a break point on this line. Breakpoints may be selected for the MPI processes listed in the All, Root, or Workers toolbar by first left clicking on one of these in the toolbar.

Step 6: Controlling Program Execution. The following summarizes the most useful items from the toolbars at the top of the DDT window:

• Session: restart and exit

• Select: allows one to select the MPI processes in All, Root, or Workers to step through the program with.

• Search: allows one to easily go to any line of the program displayed in the middle window and to search for strings.

• View: allows one turn on and off viewing of various items.

• Help: allows one to view and print the DDT User Guide and displays a FAQ.

• Current Group: Allows one to select All, Root, or Workers for stepping through the program.

• Play: starts program execution from where it was stopped and runs to the next breakpoint or until the program stops.

• Pause: pauses program execution on all MPI processes.

• Step Into: execution proceeds into the function/subroutine if stopped at a function or subroutine; therwise, execution continues to the next statement.

• Step Over: execution continues to the next statement and not into a function/subroutine.

• Step Out: allows one to step out from a function/subroutine.

• All: displays all MPI processes that are to be executed under the control of DDT. One can drag an MPI process from this window to the Root or Workers windows.

• Root: Shows the MPI processes selected to be Root. One can drag MPI processes from the All window to the Root window. One can also delete MPI processes from this window by clicking on them and then hitting the delete key.

• Workers: Shows MPI processes in this group. One can add and delete MPI processes from this group as described above.

When stepping through the program one can step using the groups All, Root, or Workers. To synchronize on a line of the program, right click on this line and select Synchronize Group.

Values of local variables are displayed in the right center window for the MPI process selected for the place where execution has stopped. Multi-dimensional array values can be viewed by selecting Multi-Dimensional Array Viewer listed under View.