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