DEB(1)                                                     DEB(1)

     NAME
          deb - graphical Limbo debugger

     SYNOPSIS
          wm/deb [-f file] [-p pid]

     DESCRIPTION
          Wm/deb displays two windows, the main debugging window and a
          stack window for browsing the data values of the thread cur-
          rently being debugged.

          Debugging is performed using the facilities of the prog
          device bound to the local /prog directory (see prog(3)).
          Debugging of code running on a remote machine can be per-
          formed by binding the remote /prog directory in place of the
          local one. (See bind(1)).

          In order to display source code and set breakpoints accu-
          rately, an up to date symbol file (.sbl) must be available
          as well as the limbo source file (.b).

        Main window
          The main window is comprised of a menu bar, an icon bar and
          three text panels.  One panel, labelled Threads, lists the
          process IDs (PIDs) of the threads being debugged.  Another
          panel, labelled Break, lists the set of breakpoints, each
          given a unique number.  The third and largest panel displays
          the source code of the thread being debugged.

          Breakpoint positions are shown by red text in the source
          code display.  Clicking on a breakpoint number in the Break
          panel results in the source code panel being scrolled or
          updated to show the breakpoint.  Breakpoints are toggled by
          clicking on the statement or sub-expression in the source
          code window and clicking the breakpoint button on the icon
          bar.  A breakpoint can be hit by any of the threads being
          debugged - breakpoints are set on source code, not on indi-
          vidual threads.

          Clicking on a PID in the Threads panel results in the source
          code panel being scrolled or updated to highlight where in
          the code the thread is blocked, broken or halted on a break-
          point.

          A running thread can be halted by clicking the stop button
          on the icon bar.  A thread will also halt when it hits a
          breakpoint.  Once a thread is halted (not blocked or broken)
          its execution can be advanced a step at a time by means of
          the buttons on the icon bar.  The thread can be stepped one
          operation at a time or a statement at a time.  Normally when

     DEB(1)                                                     DEB(1)

          single stepping, function calls are stepped into.  Stepping
          commands allow for stepping over function calls, whereby the
          function is still called but its whole execution is treated
          as a single step.  Stepping out of a function is also pro-
          vided, whereby execution continues unabated until returning
          from the function.  Execution of the halted thread can be
          continued, running until it terminates, breaks or hits
          another breakpoint.

          Any of the threads being debugged can be killed or detached
          from the debugger using buttons on the icon bar.  Detaching
          a halted thread resumes its execution.

          The main window provides a set of menus for viewing source
          files, attaching to other threads, setting debugger options
          and searching for text in the source code window.

        Stack Window
          The stack window is used to inspect the values of local and
          global variables and function arguments.  Items are dis-
          played in a hierarchical manner.  Any item that contains
          other items, such as a variable of an ADT type, can be
          expanded to show the values of the sub-items.  The sub-items
          are displayed by clicking on the expand button on the left
          of the containing item, they can be hidden by pressing the
          button again.  The sub-item list is displayed indented from
          its container as a visual cue to their association.

          The stack window shows the full stack trace of the current
          thread.  The stack trace is displayed as a list of frames,
          the current frame displayed at the top of the window.  Each
          frame is given by the function name and source location of
          the code being executed in the frame.  Each frame has the
          following sub-items:

          locals    Local variables declared in the function of the
                    frame.

          args      The arguments passed to the frame function.

          module    The module global variables in the implementation
                    module of the frame function.

          Clicking on the name of a variable or function argument
          highlights the declaration of that name in the source panel
          of the main debug window.  Clicking on the function name of
          a stack frame causes the main window source panel to display
          the current statement of the frame.

          The debugger has a stack button which simply brings that
          window to the front of the display.

     DEB(1)                                                     DEB(1)

          The options menu has a layout configuration which allows the
          user to have a horizontal scroll bar or to wrap long lines
          (the default); and an option to strip carriage return char-
          acters that precede newlines (for the benefit of those using
          Windows' editors).  The state of the options is saved in the
          file /usr/username/lib/deb if that file can be created. The
          debugger attempts to read this file on startup to set the
          user's preferred options.

     OPTIONS
          -f file   Specifies a source file (.b) to load.  The associ-
                    ated executable file (.dis) is not launched until
                    the continue (run to breakpoint) button is
                    pressed.  This option takes precedence over the -p
                    option.

          -p pid    Attach to the already running thread given by pid.

     PLUMBING
          wm/deb plumbs the address of text selected using button 3 in
          the source display panel, as text of the form

               file-name:line-number

     FILES
          /prog/n/*
          /usr/username/lib/deb

     SOURCE
          /appl/wm/deb.b
          /appl/wm/debdata.b
          /appl/wm/debsrc.b

     SEE ALSO
          limbo(1), prog(3)

     BUGS
          Displaying large arrays in the Stack window can use exces-
          sive amounts of memory.

          When setting breakpoints there is no visual cue for the
          selected statement or operation until the breakpoint is
          actually set.

          It is only possible to debug modules executed by the inter-
          preter.  Code that has been JITed, the compilation execution
          method, yields stack information that does not correspond to
          information in the symbol (.sbl) file.