Debugger interface

The Mosel debugger interface provides the necessary functionality for controling the execution of a program (execution step by step, breakpoints, access to local symbols, stack frame change) that may be used, for instance, to implement an interactive debugger. This interface relies on debugging information stored in the bim file which is generated at compile time depending on compilation options (see Section Compilation):

• correspondence between a global symbol and its value: this information is available as long as the source is not compiled with option "s";
• correspondence between a local symbol (e.g. index of a loop or variable local to a function) and its value: this information is generated when model is compiled with option "g";
• correspondence between source code and compiled code: the source location information is also constructed if option "g" was used for compilation;
• tracing facility to enable the Mosel virtual machine to suspend execution at a specified location (breakpoint) or execute one statement at a time: as opposed to the previous features, this information requires insertion of instructions in the compiled code (and may alter the execution speed of a model). To enable this extension, option "G" has to be used when compiling the source model.

A model to be run through the debugger interface should be compiled with flag "g" or "G".

For the functions described below, the source location is indicated by means of line indices: each of these indices is associated to a statement, a data structure declaration or an end of subroutine (just before it returns). The function XPRMdbg_getlocation makes the correspondence between a line index and an actual source location (i.e. file name and line number). The first statement of the program has always index 0 and the total number of indices can be obtained using XPRMdbg_getnblndx. It is also possible to retrieve all indices at once using XPRMdbg_getlndx. The index of the first statement of a function is returned by XPRMdbg_findproclndx.

The execution of a program normally terminates when an error occurs or simply when all instructions have been run. Using the function XPRMdbg_setbrkp, it is possible to specify locations in the program where execution must be suspended. From these breakpoints, one can examine current value of variables, install new breakpoints then continue or cancel execution for instance.

Before procedures (or functions) are called during execution of a program, the execution context of the system (mainly local symbols and a reference to the next instruction) is saved on top of a stack. This way, after the routine returns, the state of the machine can be restored and the execution resumed. When the execution of the program is suspended, it may be interesting to change the current position in the stack, or stack frame, in order to view variables that are not defined at the current level because they are declared by the calling procedure. This can be achieved using function XPRMdbg_setstacklev.

In order to use the debugger interface, the program has to be run with the function XPRMdbg_runmod: this special version of XPRMrunmod requires an extra parameter specifying a function reference, Mosel calls this function whenever the program has to be interrupted. If there is no error condition, the return value of the function decides whether execution should continue or not. During the interruption, most functions listed in this manual can be used to retrieve information about the current state of the program. Moreover, XPRMfindident returns references to locally defined symbols when called from the debugger interface.