This chapter describes the Caml Light source-level replay debugger camldebug.
Before the debugger can be used, the program must be compiled and linked with the -g option: all .zo files that are part of the program should have been created with camlc -g, and they must be linked together with camlc -g.
Compiling with -g entails no penalty on the running time of programs: .zo files and bytecode executable files are bigger and take slightly longer to produce, but the executable files run at exactly the same speed as if they had been compiled without -g. It is therefore perfectly acceptable to compile always in -g mode.
The Caml Light debugger is invoked by running the program camldebug with the name of the bytecode executable file as argument:
camldebug program
The following command-line options are recognized:
The command quit exits the debugger. You can also exit the debugger by typing an end-of-file character (usually ctrl-D).
Typing an interrupt character (usually ctrl-C) will not exit the debugger, but will terminate the action of any debugger command that is in progress and return to the debugger command level.
A debugger command is a single line of input. It starts with a command name, which is followed by arguments depending on this name. Examples:
run
goto 1000
set arguments arg1 arg2
A command name can be truncated as long as there is no ambiguity. For instance, go 1000 is understood as goto 1000, since there are no other commands whose name starts with go. For the most frequently used commands, ambiguous abbreviations are allowed. For instance, r stands for run even though there are others commands starting with r. You can test the validity of an abbreviation using the help command.
If the previous command has been successful, a blank line (typing just RET) will repeat it.
The Caml Light debugger has a simple on-line help system, which gives a brief description of each command and variable.
Events are ``interesting'' locations in the source code, corresponding to the beginning or end of evaluation of ``interesting'' sub-expressions. Events are the unit of single-stepping (stepping goes to the next or previous event encountered in the program execution). Also, breakpoints can only be set at events. Thus, events play the role of line numbers in debuggers for conventional languages.
During program execution, a counter is incremented at each event encountered. The value of this counter is referred as the current time. Thanks to reverse execution, it is possible to jump back and forth to any time of the execution.
Here is where the debugger events (written ¤) are located in the source code:
(f arg)¤
fun x¤ y¤ z -> ¤ ...If a curried function is defined by pattern-matching with several cases, events corresponding to the passing of arguments are displayed on the first case of the function, because pattern-matching has not yet determined which case to select:
fun pat1¤ pat2¤ pat3 -> ¤ ... | ...
function pat1 -> ¤ expr1
| ...
| patN -> ¤ exprN
expr1; ¤ expr2; ¤ ...; ¤ exprN
if cond then ¤ expr1 else ¤ expr2
while cond do ¤ body done for i = a to b do ¤ body done
The debugger starts executing the debugged program only when needed. This allows setting breapoints or assigning debugger variables before execution starts. There are several ways to start execution:
The execution of a program is affected by certain information it receives when the debugger starts it, such as the command-line arguments to the program and its working directory. The debugger provides commands to specify this information (set arguments and cd). These commands must be used before program execution starts. If you try to change the arguments or the working directory after starting your program, the debugger will kill the program (after asking for confirmation).
The following commands execute the program forward or backward, starting at the current time. The execution will stop either when specified by the command or when a breakpoint is encountered.
You can jump directly to a given time, without stopping on breakpoints, using the goto command.
As you move through the program, the debugger maintains an history of the successive times you stop at. The last command can be used to revisit these times: each last command moves one step back through the history. That is useful mainly to undo commands such as step and next.
A breakpoint causes the program to stop whenever a certain point in the program is reached. It can be set in several ways using the break command. Breakpoints are assigned numbers when set, for further reference.
Each time the program performs a function application, it saves the location of the application (the return address) in a block of data called a stack frame. The frame also contains the local variables of the caller function. All the frames are allocated in a region of memory called the call stack. The command backtrace (or bt) displays parts of the call stack.
At any time, one of the stack frames is ``selected'' by the debugger; several debugger commands refer implicitly to the selected frame. In particular, whenever you ask the debugger for the value of a local variable, the value is found in the selected frame. The commands frame, up and down select whichever frame you are interested in.
When the program stops, the debugger automatically selects the currently executing frame and describes it briefly as the frame command does.
The debugger can print the current value of a program variable (either a global variable or a local variable relative to the selected stack frame). It can also print selected parts of a value by matching it against a pattern.
Variable names can be specified either fully qualified (module-name__var-name) or unqualified (var-name). Unqualified names either correspond to local variables, or are completed into fully qualified global names by looking at a list of ``opened'' modules that define the same name (see section 10.8 for how to open modules in the debugger.) The completion follows the same rules as in the Caml Light language (see section 3.3).
The syntax of patterns for the match command extends the one for Caml Light patterns:
pattern:
ident
| _
| ( pattern )
| ncconstr pattern
| pattern , pattern {, pattern}
| { label = pattern {; label = pattern} }
| [ ]
| [ pattern {; pattern} ]
| pattern :: pattern
| # integer-literal pattern
| > pattern
The pattern ident, where ident is an identifier, matches any
value, and binds the identifier to this value. The pattern
# n pattern matches a list, a vector or a tuple whose n-th
element matches pattern.
The pattern > pattern matches any
constructed value whose argument matches pattern, regardless of the
constructor; it is a shortcut for skipping a constructor.
Example: assuming the value of a is Constr{x = [1;2;3;4]}, the command match a > {x = # 2 k} prints k = 3.
A shell is used to pass the arguments to the debugged program. You can therefore use wildcards, shell variables, and file redirections inside the arguments. To debug programs that read from standard input, it is recommended to redirect their input from a file (using set arguments < input-file), otherwise input to the program and input to the debugger are not properly separated.
The loadingmode variable controls how the program is executed.
The debugger searches for source files and compiled interface files in a list of directories, the search path. The search path initially contains the current directory . and the standard library directory. The directory command adds directories to the path.
Whenever the search path is modified, the debugger will clear any information it may have cached about the files.
Each time a program is started in the debugger, it inherits its working directory from the current working directory of the debugger. This working directory is initially whatever it inherited from its parent process (typically the shell), but you can specify a new working directory in the debugger with the cd command or the -cd command-line option.
Like the Caml Light compiler, the debugger maintains a list of opened modules in order to resolves variable name ambiguities. The opened modules also affect the printing of values: whether fully qualified names or short names are used for constructors and record labels.
When a program is executed, the debugger automatically opens the modules of the standard library it uses.
In some cases, you may want to turn reverse execution off. This speeds up the program execution, and is also sometimes useful for interactive programs.
Normally, the debugger takes checkpoints of the program state from time to time. That is, it makes a copy of the current state of the program (using the Unix system call fork). If the variable checkpoints is set to off, the debugger will not take any checkpoints.
The debugger communicate with the program being debugged through a Unix socket. You may need to change the socket name, for example if you need to run the debugger on a machine and your program on another.
On the debugged program side, the socket name is passed either by the -D command line option to camlrun, or through the CAML_DEBUG_SOCKET environment variable.
Several variables enables to fine-tune the debugger. Reasonable defaults are provided, and you should normally not have to change them.
As checkpointing is quite expensive, it must not be done too often. On the other hand, backward execution is faster when checkpoints are taken more often. In particular, backward single-stepping is more responsive when many checkpoints have been taken just before the current time. To fine-tune the checkpointing strategy, the debugger does not take checkpoints at the same frequency for long displacements (e.g. run) and small ones (e.g. step). The two variables bigstep and smallstep contain the number of events between two checkpoints in each case.
The following commands display information on checkpoints and events: