Introduction

Since version 6, Mathematica has had a built-in debugger. I have never felt that this debugger is anything like as helpful as it should be, and the DebugTrace package is an attempt to design a better alternative.

Obtaining and installing the package

DebugTrace is free and Version 1.51 (adjusted to work with Both Mathematica 9, 7 and 8) can be downloaded as a ZIP file containing all the files required in their appropriate directories.. It is vital that this directory structure is preserved. Copy the file to the $UserBaseDirectory or $BaseDirectory directory, e.g. "C:\Documents and Settings\All Users\Application Data\Mathematica". Unzip the file DebugTrace.ZIP using a tool that preserves the directory structure and handles long names correctly, e.g. PKZIP(R) Version 2.50, or WinZip(R).

Recent additions

A built-in timing feature has been added, which can help track down the parts of a program that are most expensive.

A control-click on a line number, will run the program until that line – avoiding the complications of setting a breakpoint, and clearing it off again.

Principal features

DebugTrace identifies locations in your pdynamirogram using line numbers (relating to a listing that it displays), rather than highlighting the relevant portion of code, as the built-in debugger does.

This use of line numbers means that a permanent record of a debug session can be created. A feature which is of enormous advantage in complex debugging operations.

The line numbers in the (read only) 'listing notebook' can be clicked to toggle breakpoints, and also change colour to reflect the current location of the program.

DebugTrace can debug programs written at the top level (i.e. without defining functions) which are executed simply by evaluating the entire notebook. Although this style of programming is not recommended (!!), it is a style that is frequently used by beginners. Of course, DebugTrace can also handle function definitions, and even packages with complex changes of context.

Traceback stack information is given in terms of user-defined function names.

DebugTrace is mainly concerned with following the procedural logic of a program. Currently it does not step through the individual steps of functional operations such as Map. I might change this, but it can be a distraction to display too many steps.

All the steps in a particular evaluation are numbered (whether you pause on them or not). This means that on a second run of the debugger on the same problem, you can run directly to a step number in the vicinity of the area of interest. This is particularly valuable when debugging complex code.

I have used DebugTrace to explore some programs that use my Super Widget (SWP) Package to generate Java GUI's. If you run a program that uses the SWP, and enter a modal wait (SuperGUIRunModal), the DebugTrace control palette will display an extra button to gain control in this situation without exiting your GUI.

A function is supplied to access Module local variables from their base name. Thus, if you have paused your program at a point where a module is active with local variable 'foo', you can access the value of this variable without deterining the unique name of the variable (such as foo$1335).

Using DebugTrace it is possible (as of version 1.02) to explore dynamic calculations. Although pausing a dynamic calculation is not really feasible, you can collect debugging information and view it later. This information is time stamped to help in attacking problems such as slow response.

Those of you who have tried the built-in debugger, will be pleased to know that DebugTrace comes with its own manual, and a small program to illustrate the software in action.

How it works

DebugTrace uses no special hooks into Mathematica, instead it modifies the source code as it is presented to the kernel, to add the necessary hooks to allow the debugger to operate. This process imposes much less run-time overhead than TraceScan (used by M-Debug).

Further developments

The future of this package will depend on the feedback that I receive.