7.1 Quick overview

This section gives a quick and simple guide to getting started with the debugger. The remainder of this chapter contains more detailed documentation.

To use the debugger, you must first compile your program with debugging enabled. You can do this by using one of the ‘--debug’ or ‘--decl-debug’ options when invoking ‘mmc’, or by including ‘GRADEFLAGS = --debug’ or ‘GRADEFLAGS = --decl-debug’ in your Mmakefile.

bash$ mmc --debug hello.m

Once you have compiled with debugging enabled, you can use the ‘mdb’ command to invoke your program under the debugger:

bash$ mdb ./hello arg1 arg2 …

Any arguments (such as ‘arg1 arg2 …’ in this example) that you pass after the program name will be given as arguments to the program.

The debugger will print a start-up message and will then show you the first trace event, namely the call to main/2:

       1:      1  1 CALL pred hello:main/2-0 (det)
                         hello.m:13
mdb>

By hitting enter at the ‘mdb>’ prompt, you can step through the execution of your program to the next trace event:

       2:      2  2 CALL pred io:write_string/3-0 (det)
                         io.m:2837 (hello.m:14)
mdb>
Hello, world
       3:      2  2 EXIT pred io:write_string/3-0 (det)
                         io.m:2837 (hello.m:14)
mdb>

For each trace event, the debugger prints out several pieces of information. The three numbers at the start of the display are the event number, the call sequence number, and the call depth. (You don’t really need to pay too much attention to those.) They are followed by the event type (e.g. ‘CALL’ or ‘EXIT’). After that comes the identification of the procedure in which the event occurred, consisting of the module-qualified name of the predicate or function to which the procedure belongs, followed by its arity, mode number and determinism. This may sometimes be followed by a “path” (see Tracing of Mercury programs). At the end is the file name and line number of the called procedure and (if available) also the file name and line number of the call.

The most useful mdb commands have single-letter abbreviations. The ‘alias’ command will show these abbreviations:

mdb> alias
?      =>    help
EMPTY  =>    step
NUMBER =>    step
P      =>    print *
b      =>    break
c      =>    continue
d      =>    stack
f      =>    finish
g      =>    goto
h      =>    help
p      =>    print
r      =>    retry
s      =>    step
v      =>    vars

The ‘P’ or ‘print *’ command will display the values of any live variables in scope. The ‘f’ or ‘finish’ command can be used if you want to skip over a call. The ‘b’ or ‘break’ command can be used to set breakpoints. The ‘d’ or ‘stack’ command will display the call stack. The ‘quit’ command will exit the debugger.

That should be enough to get you started. But if you have GNU Emacs installed, you should strongly consider using the Emacs interface to ‘mdb’ — see the following section.

For more information about the available commands, use the ‘?’ or ‘help’ command, or see Debugger commands.