16.8 Controlling the debugger

16.8.1. Setting the program name and arguments
16.8.2. How programs are loaded
16.8.3. Search path for files
16.8.4. Working directory
16.8.5. Turning reverse execution on and off
16.8.6. Communication between the debugger and the program
16.8.7. Fine-tuning the debugger
16.8.8. User-defined printers

16.8.1 Setting the program name and arguments

set program file

Set the program name to file.

set arguments arguments

Give arguments as command-line arguments for the


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, and inputs are not properly replayed when running the program backwards.

16.8.2 How programs are loaded

The loadingmode variable controls how the program is executed.

set loadingmode direct

The program is run directly by the debugger. This is the default mode.

set loadingmode runtime

The debugger execute the Objective Caml runtime ocamlrun on the program. Rarely useful; moreover it prevents the debugging of programs compiled in "custom runtime" mode.

set loadingmode manual

The user starts manually the program, when asked by the debugger. Allows remote debugging (see section 16.8.6).

16.8.3 Search path for files

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.

directory directorynames

Add the given directories to the search path. These directories are added at the front, and will therefore be searched first.


Reset the search path. This requires confirmation.

16.8.4 Working directory

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.

cd directory

Set the working directory for camldebug to directory.


Print the working directory for camldebug.

16.8.5 Turning reverse execution on and off

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.

set checkpoints on/off

Select whether the debugger makes checkpoints or not.

16.8.6 Communication between the debugger and the program

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.

set socket socket

Use socket for communication with the program. socket can be either a file name, or an Internet port specification host:port, where host is a host name or an Internet address in dot notation, and port is a port number on the host.

On the debugged program side, the socket name is passed through the CAML_DEBUG_SOCKET environment variable.

16.8.7 Fine-tuning the debugger

Several variables enables to fine-tune the debugger. Reasonable defaults are provided, and you should normally not have to change them.

set processcount count

Set the maximum number of checkpoints to count. More checkpoints facilitate going far back in time, but use more memory and create more Unix processes.

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.

set bigstep count

Set the number of events between two checkpoints for long displacements.

set smallstep count

Set the number of events between two checkpoints for small displacements.

The following commands display information on checkpoints and events:

info checkpoints

Print a list of checkpoints.

info events [module]

Print the list of events in the given module (the current module, by default).

16.8.8 User-defined printers

Just as in the toplevel system (section 9.2), the user can register functions for printing values of certain types. For technical reasons, the debugger cannot call printing functions that reside in the program being debugged. The code for the printing functions must therefore be loaded explicitly in the debugger.

load_printer "file-name"

Load in the debugger the indicated .cmo or .cma object file. The file is loaded in an environment consisting only of the Objective Caml standard library plus the definitions provided by object files previously loaded using load_printer. If this file depends on other object files not yet loaded, the debugger automatically loads them if it is able to find them in the search path. The loaded file does not have direct access to the modules of the program being debugged.

install_printer printer-name

Register the function named printer-name (a value path) as a printer for objects whose types match the argument type of the function. That is, the debugger will call printer-name when it has such an object to print. The printing function printer-name must use the Format library module to produce its output, otherwise its output will not be correctly located in the values printed by the toplevel loop.

The value path printer-name must refer to one of the functions defined by the object files loaded using load_printer. It cannot reference the functions of the program being debugged.

remove_printer printer-name

Remove the named function from the table of value printers.