SourceForge.net Tracing API

Tracing API
Table of Contents

OOEU's debugging features


The interpreter is set up to use an external dll for tracing. I did this because I want to have a nice, windowed debugger, but I don't really want to bloat the interpreter itself with GUI code. It should be relatively easy to make a built in debugger, and this exercise is left to the reader. The dll name is currently hard coded to be ooeu_trace.dll/so. This may change in the future to use an ini file or possibly a command line switch. Also, the point at which the debugger is loaded and initialized is subject to change.

The interpreter looks first for an environment variable named OOEU_DEBUGGER. If found, it will use this for the name of the debugger library to load.

The dll must be written in euphoria, since it communicates using Euphoria native datatypes (E_OBJECT). The dll must have an initialize() function, which receives two parameters. The first is a sequence of callbacks that comprise the API for the debugger to use. The second parameter is the list of file names.

The callbacks are for the functions, respectively: 

    get_value( sequence var_name ): not implemented
    get_symbols(): not implemented
    get_line(): not implemented
    get_lines(): returns the global sequence slist (all the lines in the app)
    set_break(): sets or removes a break point
    get_files(): gets the list of file names
    set_trace( integer on ): turns trace on or off:
        0: turn of trace (like 'q' in RDS trace)
        1: turn on trace mode 1
        2: turn on trace mode 2
        3: turn on trace mode 3
        4: turn off trace for rest of program (like 'Q' in RDS trace)
        5: abort the program (like '!' in RDS trace)
    current_sub(): returns the symtab_index of the Current SubProgram
    get_pc(): Returns the program counter variable
    get_object(): Returns an object.  Used to send changed values back from the debugger.
    set_debug_io( integer setting ): Allows redirection of STDOUT to the debugger.  The debugger must
        provide a debug_io( object output ) function that will be called whenever STDOUT
        receives output from the OOEU code through a puts, print, printf or ? call
Your initialize() function must return the callback to the function to be called when a new line must be displayed. This function should take an integer, which will be the global line number (i.e., index into slist). Once your function returns, the interpreter will continue to execute the next line. The return value will be ignored.

You must also create several global functions: