UPoC Debugger solution

UPoC debugging support has not been added to the Cloverleaf IDE. As an interim solution, you can use NetBeans as the user-facing debugger.

Netbeans is the official IDE for Java 8. It has built-in debugging support for Java and JavaScript. Plug-ins for Tcl and Python are also available. The testing tools and server Tcl have been modified so that NetBeans can be used for Cloverleaf UPoC debugging.

A Tcl plug-in is available for NetBeans that works on NetBeans 8. To make it work with UPoC testing tools, changes are required on both the plug-in and the Cloverleaf server.

Debugging protocol

A line-based text protocol is used by the Tcl plug-in. The user sends a request to the server, and the server sends a response back to the user.

The response is optional. For the run requests stepover, continue, and so on, no response is sent back.

This protocol must be implemented in the Tcl server.

Request and response formats are:

  • Status request and response.

    Status request is used to get the current location where the program stops.

    Request:
    status
    Response:
    <file>:<line>

    <file> is a full path name and <line> is a line number.

  • File request and response.

    This file request does not exist in the original Tcl plug-in. It is used to retrieve a source file from the server.

    Request:
    file <file>
    Response:
    <N>
    <line 1>
    ...
    <line N>

    <file> is a full path name, <N> is the number of lines in the file, and lines <line 1>...<line N> are the file contents.

  • Variables request and response.

    Variables request is used to get names and values of current visible variables, including local variables and global ones.

    Request:
    variables
    Response:
    <M>
    <lvar_1>=<lval_1>
    ...
    <lvar_M>=<lval_M>
    <N>
    <gvar_1>=<gval_1>
    ...
    <gvar_N>=<gval_N>

    <M> and <N> are the numbers of local and global variables respectively. <lvar_x>/<gvar_x> is a local/global variable name and <lval_x>/<gval_x> is its value.

    This is an example of variables response:

    2
    args="{mytest: calling a proc in this file}"
    i="0"
    0

    This means there are 2 local variables args and i, and no global variable.

  • Callstack request and response.

    Callstack request is used to get the callstack information of the stopped program.

    Request:
    callstack
    Response:
    <N>
    <frame_1>
    ...
    <frame_N>

    <N> is the number of frames, and <frame_x> is the frame information that has four lines with this format:

    <Tcl command>
    <level>
    <file>
    <line>

    <Tcl command> is the Tcl command string of the frame. <level> is the level number. <file> is the full path name. <line> is the line number.

    This is an example of a callstack response:

    3
    "mytest {MSGID message0} {CONTEXT sms_ib_data} {ARGS {}} {MODE run} {VERSION 3.0}"
    1
    ???
    1
    "proc_in_this_file \"mytest: calling a proc in this file\""
    2
    /work/co_dev/6.2P/integrator/t-dtc/tclprocs/mytps.tcl
    53
    "for {set i 0} {$i < 5} {incr i} {\n proc_deep $i\n }"
    3
    /work/co_dev/6.2P/integrator/t-dtc/tclprocs/mytps.tcl
    21

    In this example, there are three frames total.

    Note: If the file name is ???, then this indicates the command is not from a file. It could be a string being evaluated. The Tcl command can be a multi-line string in which the new line character is replaced with the escape sequence \n.
  • Breakpoints request.

    Breakpoints request is used to set breakpoints. No response.

    Request:
    breakpoints
    <N>
    <breakpoints_in_file_1>
    ...
    <breakpoints_in_file_N>

    <N> is the number of files with breakpoints set, and <breakpoints_in_file_x> is the breakpoint information that has two lines, using this format:

    <file>
    <line_1> <line_2> ... <line_M> 

    <file> is the full path name of a file with breakpoints in it, <line_x> is a line number.

    This is an example of the breakpoints request:

    breakpoints
    1
    /work/quovadx_dev/qdx6.2P/integrator/t-dtc/tclprocs/mytps.tcl
    14 53

    In this example, the mytps.tcl Tcl source file contains two breakpoints set at line 14 and 53.

  • Program run requests are used to control the running of the program. There is no response for these requests.
    Requests:
    continue
    step
    stepover
    stepout

    Request step is the same thing as stepinto.

Attach Debugger

The original NetBeans Tcl plug-in can only do local debugging. For example, starting a Tcl program and controlling its running.

The plug-in cannot:

  • Attach to a running Tcl program.
  • Debug a Tcl program running on another machine.
  • Debug a Tcl script run by a Tcl interpreter that is embedded in a C program. For example, the Cloverleaf testing tools.

To debug Cloverleaf UPoCs, the Tcl plug-in must be extended with the attach and remote debugging functionality. A CLUD/Tcl debugger type is added in the Attach Debugger dialog box. Users can specify the target machine, using the host name or IP address, and TCP port.

Local copies of source files

The Tcl source files opened in NetBeans during a debugging session are local copies retrieved from the debugger server. The files are saved in a temporary folder and their contents are shown read-only to prevent any modification.

You must use the Cloverleaf IDE to do Tcl source file editing. Ensure the changes are made to the server files and that tclIndex is updated. After this, you can debug again to see the changes take effect in NetBeans.

When the debugging session ends, the temporary folder and all files in it should be deleted.

NetBeans for Java/JavaScript UPoC debugging

NetBeans has built-in support for Java and JavaScript debugging. To debug Cloverleaf Java/JavaScript UPoC, the CLJAVA_INIT environment variable must be set to start the JVM in debugging mode.

$ setenv CLJAVA_INIT -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=<port>

After the testing tool starts, the JVM listens on the TCP port <port> and waits for the debugger to attach.

Python UPoC debugging

In the interim solution, Python UPoC debugging is only supported in the command line using Python’s pdb module. The {DEBUG 1} argument is used to enable debugging.

For example:

$ hcitpstest -r run -x ASCII -f nl -c sms_ib_data -e "hcitpstestshowbydisp " 
$HCISITEDIR/in.txt 'cljTPS {CLASS ScriptTPS} {LANG python} 
{SCRIPT "if mode == \"run\":\n msg.setContent(msg.getContent().upper())\n dl.add(dl.CONTINUE, msg)"} 
{DEBUG 1}'