Req:debug module

--Dchassin 14:09, 6 August 2012 (UTC)

Req:debug module - Debug module requirements

As of debugging is no longer supported directly in the core. Instead it is implemented by the debug module, which functions much like the assert module but provides a mechanism for users to input commands and alter the behavior of the debugging objects while the simulation is running. By default this user interface is the command line, but an API is provided to hook in graphical user interfaces as well.

Application Concept
The debug module allows modelers to include debugging object in models. Debugging objects allow inspection of properties and global while the simulation is running. Some illustrative examples are


 * Break on a global variable
 * The following illustrates stopping the simulation when the clock reaches a specified date and time

// Examples:debug_clock.glm module debug { break "clock == '2001-01-01 00:00:00';  action "prompt"; }


 * The following behavior occurs

host% gridlabd --debugger debug_clock.glm DEBUG: break on clock == '2001-01-01 00:00:00'; DEBUG> quit host%


 * provide more examples taken from integrated debugger

Definitions

 * Breakpoint : A breakpoint defines a condition that causes the debugger to stop when the condition is satisfied.
 * Debug command : A debug command is a command that is interpreted by a debug object.
 * Debug context : The debug context determines the scope within which command are interpreted.
 * Debug object : A debug object is an object that is capable of accepting debug commands.
 * Watchpoint : A watchpoint defines a value that causes the debugger to stop when the value changes.

R1

 * Activation
 * Objects defined in the debug module shall be active only when the global variable debug is set to a non-zero value.

R2

 * Context
 * Debug objects shall establish the context in which debug commands are interpreted.

R2.1

 * Global context
 * Debug object with no parent shall use the global context.

R2.2

 * Local context
 * Debug objects with a parent shall use the parent object's context.

R3

 * Breakpoints
 * Debug objects shall stop and accept commands when a breakpoint condition is satisfied.

R4

 * Watchpoints
 * Debug objects shall stop and accept commands when a watchpoint variable is modified.

Version
The debug module is supported as of.