1debugger_init(n) Ajuba Debugger debugger_init(n)
2
6 debugger_init, debugger_eval, debugger_break - debugging embedded
7 scripts and debugging remotely.
8
10 debugger_init ?host ?port??
11 debugger_eval ?switches? script
13 debugger_attached
15 debugger_break ?str?
17
20 The Tcl procedures defined here allow the Ajuba Debugger to be used to
21 debug remote, embedded and CGI applications. In order for your appli‐
22 cation to establish and maintain communication with the debugger, you
23 must modify your application to source the initdebug.tcl file and call
24 the debugger_init and debugger_eval procedures.
25
27 The following procedures are provided by the debugger library:
28 debugger_init ?hostname ?port??
30 Establish the connection with the debugger that is currently
31 running on hostname and listening on port. By default hostname
32 is localhost and the port is 2576. After the connection has
33 been made, the debugger will instrument any files that are
34 sourced into the interpreter with the source command, or any
35 commands that appear in the arg list of the debugger_eval com‐
36 mand. The command returns 1 if the connection was successful
37 and returns 0 if the connection failed.
38 debugger_eval ?switches? script
40 The debugger_eval command instruments and invokes the specified
41 script. The debugger_eval command allows a program to explic‐
42 itly instrument a block of code that might not otherwise be
43 instrumented by the debugger. If the script is not currently
44 connected to the debugger, debugger_eval simply evaluates the
45 script argument.
46 If the initial arguments to debugger_eval start with -, then
48 they are treated as switches. The following switches are cur‐
49 rently supported:
50 -name name Associate a name with the script. This causes
52 the debugger to remember breakpoint information
53 as if the script were sourced from a file of the
54 given name. This feature can be useful in remote
55 debugger situations, or when evaluating blocks of
56 dynamically generated code that are used multiple
57 times. By creating a unique name for each block,
58 the user can set breakpoints in the block that
59 persist across invocations.
60 -- Marks the end of switches. The argument follow‐
62 ing this one will be treated as script even if it
63 starts with a -.
64 debugger_attached
66 The debugger_attached returns 1 if the script is currently con‐
67 nected to the debugger. Otherwise it returns 0.
68 debugger_break ?str?
70 The debugger_break command will cause a break to occur when exe‐
71 cuted. The effect is similar to the effect of a break-point on
72 the line containing the debugger_break command (the only differ‐
73 ence is that str is evaulated before the break occurs). When
74 the break occurs a dialog is presented in the debugger's GUI.
75 If str is given (and not empty) the value of str is presented in
76 the dialog box. If the script is not currently connected to the
77 debugger, debugger_break acts as a no-op.
78
81 The example code below demonstrates the simplest way to establish a
82 remote connection and debug an entire script remotely. The connection
83 is established between the local machine and remoteMachine via port
84 2576. At this point it is assumed that the debugger is running on
85 remomoteMachine and is listening on port 2576. See the User's Guide or
86 online help system for more information on how to specify the port that
87 the debugger listens on. The file main.tcl is then sourced, which will
88 cause the contents of the file, and any subsequent sourced files, to
89 become instrumented (unless the preferences set in the debugger indi‐
90 cate otherwise.)
91 source initdebug.tcl if {[debugger_init remoteMachine 2576] == 0} {
93 return "cannot communicate with remoteMachine on port 2576" }
94 source main.tcl
95 The next example shows how to control exactly which commands become
97 instrumented. Establish the connection exactly like the previous exam‐
98 ple. The commands that create the variables x, y and z will not be
99 instrumented and the debugger will not step through theses lines. The
100 commands that create the variables a, b and c are inside the debug‐
101 ger_eval. This causes these commands to be instrumented and the debug‐
102 ger will step through these commands.
103 source initdebug.tcl if {[debugger_init remoteMachine 2576] == 0} {
105 return "cannot communicate with remoteMachine on port 2576" } set x
106 1 set y 2 set z 3 debugger_eval {
107 set a [expr {$x + 1}]
108 set b [expr {$y + 1}]
109 set c [expr {$z + 1}] }
110 This example is especially relevant when debugging embedded scripts.
112 Simply add the first two lines to the beginning of the script and wrap
113 the existing script in a call to debugger_eval.
114
117 remote debugging, debugger_init, debugger_eval, instrument, attach,
118 detach
119Ajuba 1.4 debugger_init(n)