~ chicken-core (chicken-5) /manual/Debugging

  1[[tags:manual]]
  2
  3== Debugging
  4
  5
  6=== Introduction
  7
  8This document describes "Feathers", a debugger for compiled CHICKEN programs.
  9
 10"Feathers" is a [[http://tcl.tk|Tcl/Tk]] script, installed together with
 11all other components of the CHICKEN system. To use the debugger, Tcl/Tk version
 128.5 or later must be installed.
 13
 14Once the debugger is started, it waits for a client program to connect to
 15it. You can also run a program explicitly by pressing the {{F1}} key and
 16selecting an executable to run. If the executable has been compiled with
 17debugging information, it will connect to the debugger and the source code
 18of the program will be shown in the debugger window, if the original source
 19files of the program are available in the search path (see below for more
 20details on this.)
 21
 22To enable debugging in compiled programs a number of requirements must be met:
 23
 24* The program must be compiled with debug-level 3 or higher (option {{-d3}}) or by providing the {{-debug-info}} option.
 25
 26* The environment variable {{CHICKEN_DEBUGGER}} must be set to the address and port of a running instance of the debugger, e.g. {{CHICKEN_DEBUGGER=localhost:9999}} (port 9999 is the default port). If you start a program directly out of the debugger, then this variable does not need to be set.
 27
 28* The source code files must be in the current directory, or in the current "search path" of the debugger. The search path defaults to the current directory, the directory of the debugged program and any additional directories selected by pressing the {{F3}} key.
 29
 30You can also run the debugger from the command line and directly pass the program
 31to be debugged, including any additional arguments that the program should receive:
 32
 33{{% feathers myprogram 1 2 3}}
 34
 35The debugger understands a number of command-line options: {{-port PORT}} changes the
 36port on which the debugger listens (the default is 9999), {{-dir DIRECTORY}} adds
 37{{DIRECTORY}} to the search path (this option can be given multiple times), and
 38{{-n}} disables loading of a custom init file ({{~/.feathers}} or {{./.feathers}}).
 39
 40Debug-level 3 adds intrumentation to the compiled code to allow interacting with
 41it from the debugger. This has a slight performance cost, so it should not be
 42enabled with performance sensitive code.
 43
 44Debugging is mostly unintrusive: timing and dynamic (nursery) allocation may be
 45influenced by the debugging, but otherwise the program will behave exactly as it
 46would without embedded debugging-information: no additional heap allocation
 47takes place, and no Scheme library code will be invoked.
 48
 49User-interrupts triggered from the debugger use {{SIGUSR2}} to indicate that
 50the program should be suspended. Be aware of that in case your program implements
 51a signal handler for {{SIGUSR2}}.
 52
 53Remote debugging should be no problem: all communication between debugger and the
 54client program takes place over TCP sockets. Note that the source files for
 55the debugged program need to be available on the machine that does the debugging.
 56
 57
 58=== Usage
 59
 60Initially a single window is shown, holding the contents of the source file that
 61contains the currently executing code. When the execution changes to another file,
 62the contents of the window will be automatically updated. The combo-box at the
 63top shows all source-files for which debug-information is currently available.
 64Note that this may change during the execution of the program, as files are
 65dynamically loaded or statically linked units are not yet initialized.
 66
 67The "focus" (a line marked blue) shows at what location the program is currently
 68suspended. You can move the focus up and down with the {{Up}} and {{Down}} arrow
 69keys.
 70
 71Lines that contain "debug events" are highlighted: these lines can be used to
 72set breakpoints by clicking with the left mouse button or by pressing {{Enter}} while
 73the focus is on that line. Clicking a line that
 74contains a breakpoint will disable the breakpoint. Note that a single line
 75can contain multiple "debug events". Setting a breakpoint on such a line
 76will interrupt the program on any event that exists on that line.
 77
 78The following debug events exist:
 79
 80* Procedure call
 81
 82* Procedure entry
 83
 84* Assignment to global variable
 85
 86* Signal (an error or interrupt)
 87
 88The topmost line shows the current file and also displays "events" as the debugged
 89program runs and interacts with the debugger.
 90
 91At the bottom the following buttons are visible, each of them can also be activated
 92by pressing the function-key shown on the button:
 93
 94; F1 : Run an executable under the debugger. If a program is already debugged, then the current program will be terminated and the debugger is reinitialized.
 95
 96; F2 : Move focus back to location where the debugged program has been suspended.
 97
 98; F3 : Add another directory to the current search path.
 99
100; F4 : Open the "data" view (see below.)
101
102; F5 : Continue execution of the program until the next breakpoint is hit, an error occurs, or the program terminates.
103
104; F6 : Execute a single "step", until the next debug-event occurs. You can also press the {{Space}} key to single-step.
105
106; F7 : If text is marked in the current window, search backwards and show the most previous occurrence of the marked text that is not already visible.
107
108: F8 : Search for next occurrence of marked text.
109
110: F9 : Open "C" view (see below.)
111
112: F10 : Terminate the currently debugged program and exit the debugger.
113
114Pressing the {{Esc}} key while the program is executing will suspend it on the
115next debug-event (so this may not take place instantly.)
116
117The keys {{+}} (plus) and {{-}} (minus) increase and decrease the current font-size,
118respectively.
119
120
121=== The "Data" View
122
123When {{F4}} is pressed, a window appears that allows inspection of the current
124arguments of a suspended procedure, together with any additional global variables
125that have been marked for inspection. By opening value items in the shown tree
126view, values can be inspected to arbitrary depth. Note that the values are retrieved
127from the debug-client on-demand, so the textual representation of a value shown
128will only reflect its currently inspected contents.
129
130The entry-field below the view for variables and arguments can be used to add
131global variables to the list of watched variables. Double-clicking on a variable
132(or pressing {{Enter}} while it is
133selected) sets a "watchpoint" - a breakpoint that is trigged when the variable
134is assigned a new value.
135
136The bars indicate current heap-, scratchspace- and nursery
137utilization. These bars update only when the program is suspended.
138
139At the bottom the current call-trace of the executing program is shown. Note
140that this is not a "stack-trace", but a list of recently performed calls,
141ordered from top (earlier) to bottom (later).
142
143
144=== The "C" View
145
146Pressing {{F9}} opens another text-window which shows the current location where
147the program is suspended, but in the compiled C code generated by the {{chicken}}
148compiler. The contents of the window are automatically updated on every suspension
149of the debugged program.
150This may be useful when you want to understand how CHICKEN compiles
151Scheme to C, or when you are doing low-level debugging.
152
153Text can be marked and searched as in the source-code window with {{F7}} and {{F8}}.
154
155
156---
157Previous: [[Extensions to the standard]]
158
159Next: [[Interface to external functions and variables]]