16.4 Executing a program

16.4.1. Events
16.4.2. Starting the debugged program
16.4.3. Running the program
16.4.4. Time travel
16.4.5. Killing the program

16.4.1 Events

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:

  • Following a function application:
                (f arg)§§
              
  • On entrance to a function:
                fun x y z -> §§ ...
              
  • On each case of a pattern-matching definition (function, match...with construct, try...with construct):
                function pat1 -> §§ expr1
                | ...
                | patN -> §§ exprN
              
  • Between subexpressions of a sequence:
                expr1; §§ expr2; §§ ...; §§ exprN
              
  • In the two branches of a conditional expression:
                if cond then §§ expr1 else §§ expr2
              
  • At the beginning of each iteration of a loop:
                while cond do §§ body done
                for i = a to b do §§ body done
              

Exceptions: A function application followed by a function return is replaced by the compiler by a jump (tail-call optimization). In this case, no event is put after the function application.

16.4.2 Starting the debugged program

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:

run

Run the program until a breakpoint is hit, or the program terminates.

step 0

Load the program and stop on the first event.

goto time

Load the program and execute it until the given time. Useful when you already know approximately at what time the problem appears. Also useful to set breakpoints on function values that have not been computed at time 0 (see section 16.5).

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).

16.4.3 Running the program

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.

run

Execute the program forward from current time. Stops at next breakpoint or when the program terminates.

reverse

Execute the program backward from current time. Mostly useful to go to the last breakpoint encountered before the current time.

step [count]

Run the program and stop at the next event. With an argument, do it count times.

backstep [count]

Run the program backward and stop at the previous event. With an argument, do it count times.

next [count]

Run the program and stop at the next event, skipping over function calls. With an argument, do it count times.

previous [count]

Run the program backward and stop at the previous event, skipping over function calls. With an argument, do it count times.

finish

Run the program until the current function returns.

start

Run the program backward and stop at the first event before the current function invocation.

16.4.4 Time travel

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.

goto time

Jump to the given time.

last [count]

Go back to the latest time recorded in the execution history. With an argument, do it count times.

set history size

Set the size of the execution history.

16.4.5 Killing the program

kill

Kill the program being executed. This command is mainly useful if you wish to recompile the program without leaving the debugger.