1
<html><head><title>Debugger</title></head>
2
<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#000099" alink="#FF0000">
4
<center><a href="index.html"><img SRC="contents.gif" ALT="Home" BORDER=0></a></center>
6
<table BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="100%" BGCOLOR="#000000" >
8
<table BORDER=0 CELLSPACING=0 WIDTH="100%" BGCOLOR="#FFFFFF" >
9
<tr><td BGCOLOR="#ddeeff">
10
<center><img SRC="dot.gif" height=1 width=1></center>
19
<img SRC="Debugger.jpg" height=32 width=32> Debugger</h2>
25
<p>Boa now has a stable out of process debugger that can debug almost any Python
26
application. This includes threads, most popular Python GUI toolkits, Zope Python
27
debugging and even specialised support for debugging Zope Python Scripts.
29
<p>To debug an application, save any unsaved changes and click the red play
30
button <img src="Debug.jpg" height=16 width=16> on the toolbar or choose
31
<i>File->Debug</i> application. This applies to application modules and any modules
32
part of an application. To debug an individual module that is part of an
33
application, choose <i>File->Debug module</i>.<br>
34
The Debugger window should appear at the same place as the Inspector and
35
debugging will trace until the very first line of source.<br>
37
<b>Important:</b> When debugging wxPython applications on wxPython versions
38
lower than 2.3.3 on windows, there is a bug in wxProcess/wxExecute which prevents
39
the main frame of the application from being displayed.<br>
40
To work around this the main frame must be shown, hidden and shown again. e.g.
41
<font color="#101090"><pre>
42
frame.Show();frame.Hide();frame.Show()
44
<p>The standard debugging pages:
45
<table CELLSPACING=0 CELLPADDING=0 BORDER=0 BGCOLOR="#000000"><tr><td>
46
<table CELLSPACING=2 CELLPADDING=4>
48
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
51
<td VALIGN=TOP BGCOLOR="#ddeeff" >
53
List of items, each representing a level of the execution stack.
54
<br>The selected item represents the current frame for the watch and namespace windows.
55
<br>Double-click on an item to jump to the corresponding line in the source.</td>
59
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
61
<a name="Breakpoints"></a><b>Breakpoints</b></td>
62
<td VALIGN=TOP BGCOLOR="#ddeeff" >
64
List of breakpoints defined for the debugger.
66
Breakpoints can be edited, disabled or deleted by selecting them and
67
right clicking in this view.
68
<br>Double-clicking on a breakpoint will take you to where it is defined in the
70
<br>Add a breakpoint by clicking on the left side of the target line in the code
71
next to the line number or by putting your caret at the desired line in the
72
source and choosing Edit->Toggle breakpoint.
73
<p><b>Hard breakpoints</b> are breakpoints defined in your source code like this:
74
<font color="#101090"><pre>
75
if hasattr(sys, 'breakpoint'): sys.breakpoint()
77
When the debugger encounters a hard breakpoint it will be added to the breakpoint
78
list. You may also mark a hard breakpoint with a soft one before it is triggered
79
by the debugger. This allows you disable hardpoints. Right-click on a breakpoint
80
in the breakpoint list for options.
82
Hard breakpoints are primarily useful for <a href="#DebuggingThreads">debugging
83
threads</a>.<br> They can also be used to speed up startup time of an application
84
being debugged. There is an inevitable slowdown because of the overhead of
85
tracing the executing code. When the <img SRC="DebugFullSpeed.png" height=16 width=16>
86
<b>Debug / Continue full speed</b> button is clicked, the execution continues
87
without the overhead of the tracer. The only way to break into the execution now
88
is with a hard breakpoint.
94
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
97
<td VALIGN=TOP BGCOLOR="#ddeeff" >
99
Shows a list of user defined watches, evaluated in
100
the scope of the selected stack level.
102
Select/right-click for menu.
104
New watches can be added from the Locals and Globals pages or from the right-click
105
menu of the Watches page. Double-click an existing watch to edit it. Note
106
that watches does not need to be only variable names, any valid Python expression
109
Another way to watch a variable is to put the Debugger in <b>Debug Browsing</b>
110
mode. On the Toolbar, toggle the <img SRC="DebugBrowse.png" height=16 width=16>
111
button. Like <a href="Editor.html">Code Browsing</a> you have to hold down the
112
Ctrl key and move your mouse over variables in the source code. The name in the
113
source should be underlined in red and it's current value is displayed in the
114
Editor status bar. Clicking on an underlined variable adds it as a watch.<br>
116
The last way to inspect variables is to use the <b>Shell Debug</b> mode.
117
On the Toolbar, toggle the <img SRC="ShellDebug.png" height=16 width=16>
118
button. The Editor should switch to the Shell and display a debugging prompt.
119
Here you may also type any valid Python expression. Toggle the button again to
120
return to a normal shell prompt.
125
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
128
<td VALIGN=TOP BGCOLOR="#ddeeff" >
130
List of all objects in local scope of the selected stack level.
131
<br>Select/right-click to add as a watch or add your own locals watch
133
Note that this view is only updated when it is active, when there are many
134
objects in scope this can degrade performance so only keep it active when you
139
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
142
<td VALIGN=TOP BGCOLOR="#ddeeff" >
144
List of all objects in global scope of the selected stack level.
145
<br>Select/right-click to add as a watch or add your own globals watch.
147
Note that this view is only updated when it is active, when there are many
148
objects in scope this can degrade performance so only keep it active when you
154
<a name="DebuggingThreads"></a>
155
<h3>Debugging Threads</h3>
157
The biggest difficulty in debugging Python threads is that the Python debug
158
tracing hook must be set per thread. Therefor a normal breakpoint in a
159
other thread than the main thread (the one the debugger started up with)
160
will never be hit by the main thread's tracer.<br>
161
<a href="#Breakpoints">Hard breakpoints</a> to the rescue! When a hard breakpoint
162
is triggered from within a non-main-thread the debugger has access to the thread
163
and can set the tracer for it, allowing us to step further.
165
<h3>Remote Debugging</h3>
167
Because the debugger server runs out of process anyway (controlled via xmlrpc)
168
it is a small step to debugging a process on a different machine.
170
The first step is to start up the process that you want to debug on the remote
171
machine, create a RemoteServer and install the tracer.
173
There are a few ways to do this.
175
One way is to create a script called e.g. <i>bcrdb</i> which looks like this:
176
<font color="#101090"><pre>
180
sys.path.append('/path/to/boa')
182
from Debugger.RemoteServer import start
183
start('username', 'password')
186
execfile(sys.argv[0], {'__name__': '__main__',
187
'__builtins__': __builtins__})
190
You can now use this script (bcrdb script) instead of Python (python script) to
191
debug remote scripts.
193
You have to add the following snippet to your program to turn on the tracer:
194
<font color="#101090"><pre>
195
if hasattr(sys, 'debugger_control'):
196
sys.debugger_control.set_traceable()
198
Breakpoints encountered in code after the tracer was installed will be caught
201
If Boa is installed normally on the remote machine, <i>Boa.py -R script</i>
202
can be used instead of <i>bcrdb script</i>. (Boa.py imports almost nothing
203
on this code path so no 'pollution' to worry about)
205
The second step is to connect to the Remote Debugger from the Boa IDE. From an
206
open python module, select File->Attach to debugger, and fill in the dialog.
207
You should now be attached to the remote debugger.
209
It is your responsibility to assure that the file paths to the source files are
210
identical on both machines.
213
<a name="ZopeDebugging"></a>
214
<h3>Zope Debugging</h3>
216
Two forms of Zope debugging is provided.<br>
218
Firstly you may debug Zope as a normal Python application.<br>
219
Open up <b>z2.py</b> in the Editor, set it's command-line parameter to <b>-D</b>
220
(File->Set command-line parameters). Now debug it like any other module.<br>
221
Set a hard breakpoint in your Product code to break into your code.
223
Secondly you may directly debug and step through Zope Python Scripts.
224
You should have a working Zope Connection defined in the Explorer. Open the
225
Python Script you want to debug.<br>
226
Now run Zope as described in the first step. The easiest way to break into a
227
Python Script (remember that they execute in a different thread than <b>z2.py</b>) is to
228
install the extremely small Zope Product found in Debugger/ZopeBreakpoint.zip.
229
All this product does is to allow Scripts to access <b>sys.breakpoint</b>.
230
Then using the normal sys.breakpoint() call in your Python Script will break
231
at that line. From now on, normal soft breakpoints will work for the Script.<br>
232
If you don't want to install the Product you can still step through
233
Python Scripts by setting a hard break somewhere in the Zope code that runs in
234
the same thread as the Script. After hitting the hard break, normal breakpoints
235
in your Script should work.
237
Because of the new Signals support added to Zope 2.6. under unix platforms z2.py
238
must be patched on those platforms.<br>
239
(Because the debugger doesn't run programs in the main thread and Signals require this).<br>
241
To patch z2.py, from line 526, change:
242
<font color="#101090"><pre>
243
# install signal handlers if on posix
244
if os.name == 'posix':
245
from Signals import Signals
246
Signals.registerZopeSignals()
249
<font color="#101090"><pre>
250
# install signal handlers if on posix
251
if os.name == 'posix' and not hasattr(sys, 'boa_debugger'):
252
from Signals import Signals
253
Signals.registerZopeSignals()
256
<p> There is limited support provided for debugging Page Templates too.<br>
257
You may add soft breakpoints next to <tal:*> tags inside <metal:use-macro*>
258
sections. The debugger should stop at these breakpoints and you can inspect the
259
namespace with watches or the Debugger shell. Stepping is not supported.
261
Another way to debug Zope from Boa is to install the functions in the
262
<b>Debugger/BoaDebugServer.py</b> module as ExternalMethods.
264
This allows you to start and hook Zope into the Boa Debug Server at runtime without
265
running z2.py in the debugger from the IDE.<br>
266
(This also avoids the Signal problems problem on linux and works with an unpatched z2.py)
268
To install the runtime hooking follow the next steps:
270
<li>Boa must be installed on the Zope machine.</li>
271
<li>Copy <b>Debugger/BoaDebugServer.py</b> to Zope's <b>Extensions</b> directory.</li>
272
<li>Edit BoaDebugServer.py and replace <b>c:/Path/To/Boa</b> with the actual path
273
to the installation. You may also optionally replace the username, password passed to the <b>start</b>
274
function for security.</li>
275
<li>You may create the ExternalMethods anywhere you please, I have the following structure:<br>
276
BoaDebugger [Folder]<br>
277
StartDebugServer [ExternalMethod]<br>
278
HookDebugServer [ExternalMethod]<br>
282
To use the runtime hooking follow these steps:
284
<li>With a browser, execute the <b>StartDebugServer</b> method.</li>
285
<li>From the IDE (with any Python module open) choose File->Attach to debugger. </li>
286
<li>With a browser, execute the <b>HookDebugServer</b> method.</li>
289
The debugger is now hooked and ready and soft breakpoints should work.
291
<p> A new way to manage a DebugServer in Zope it to install the BoaDebugger
292
product. The product can be downloaded seperately or built with the
293
Debugger/BoaDebugger/BuildProduct.py script.
297
<table BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="100%" BGCOLOR="#000000" >
299
<table BORDER=0 CELLSPACING=0 WIDTH="100%" BGCOLOR="#FFFFFF" >
300
<tr><td BGCOLOR="#ddeeff">
301
<center><img SRC="dot.gif" height=1 width=1></center>
308
<div align=right><font size="-1">Boa Constructor - Application Help - <b>Debugger</b></font></div>
1
<html><head><title>Debugger</title></head>
2
<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#000099" alink="#FF0000">
4
<center><a href="index.html"><img SRC="contents.gif" ALT="Home" BORDER=0></a></center>
6
<table BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="100%" BGCOLOR="#000000" >
8
<table BORDER=0 CELLSPACING=0 WIDTH="100%" BGCOLOR="#FFFFFF" >
9
<tr><td BGCOLOR="#ddeeff">
10
<center><img SRC="dot.gif" height=1 width=1></center>
19
<img SRC="Debugger.jpg" height=32 width=32> Debugger</h2>
25
<p>Boa now has a stable out of process debugger that can debug almost any Python
26
application. This includes threads, most popular Python GUI toolkits, Zope Python
27
debugging and even specialised support for debugging Zope Python Scripts.
29
<p>To debug an application, save any unsaved changes and click the red play
30
button <img src="Debug.jpg" height=16 width=16> on the toolbar or choose
31
<i>File->Debug</i> application. This applies to application modules and any modules
32
part of an application. To debug an individual module that is part of an
33
application, choose <i>File->Debug module</i>.<br>
34
The Debugger window should appear at the same place as the Inspector and
35
debugging will trace until the very first line of source.<br>
37
<b>Important:</b> When debugging wxPython applications on wxPython versions
38
lower than 2.3.3 on windows, there is a bug in wxProcess/wxExecute which prevents
39
the main frame of the application from being displayed.<br>
40
To work around this the main frame must be shown, hidden and shown again. e.g.
41
<font color="#101090"><pre>
42
frame.Show();frame.Hide();frame.Show()
44
<p>The standard debugging pages:
45
<table CELLSPACING=0 CELLPADDING=0 BORDER=0 BGCOLOR="#000000"><tr><td>
46
<table CELLSPACING=2 CELLPADDING=4>
48
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
51
<td VALIGN=TOP BGCOLOR="#ddeeff" >
53
List of items, each representing a level of the execution stack.
54
<br>The selected item represents the current frame for the watch and namespace windows.
55
<br>Double-click on an item to jump to the corresponding line in the source.</td>
59
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
61
<a name="Breakpoints"></a><b>Breakpoints</b></td>
62
<td VALIGN=TOP BGCOLOR="#ddeeff" >
64
List of breakpoints defined for the debugger.
66
Breakpoints can be edited, disabled or deleted by selecting them and
67
right clicking in this view.
68
<br>Double-clicking on a breakpoint will take you to where it is defined in the
70
<br>Add a breakpoint by clicking on the left side of the target line in the code
71
next to the line number or by putting your caret at the desired line in the
72
source and choosing Edit->Toggle breakpoint.
73
<p><b>Hard breakpoints</b> are breakpoints defined in your source code like this:
74
<font color="#101090"><pre>
75
if hasattr(sys, 'breakpoint'): sys.breakpoint()
77
When the debugger encounters a hard breakpoint it will be added to the breakpoint
78
list. You may also mark a hard breakpoint with a soft one before it is triggered
79
by the debugger. This allows you disable hardpoints. Right-click on a breakpoint
80
in the breakpoint list for options.
82
Hard breakpoints are primarily useful for <a href="#DebuggingThreads">debugging
83
threads</a>.<br> They can also be used to speed up startup time of an application
84
being debugged. There is an inevitable slowdown because of the overhead of
85
tracing the executing code. When the <img SRC="DebugFullSpeed.png" height=16 width=16>
86
<b>Debug / Continue full speed</b> button is clicked, the execution continues
87
without the overhead of the tracer. The only way to break into the execution now
88
is with a hard breakpoint.
94
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
97
<td VALIGN=TOP BGCOLOR="#ddeeff" >
99
Shows a list of user defined watches, evaluated in
100
the scope of the selected stack level.
102
Select/right-click for menu.
104
New watches can be added from the Locals and Globals pages or from the right-click
105
menu of the Watches page. Double-click an existing watch to edit it. Note
106
that watches does not need to be only variable names, any valid Python expression
109
Another way to watch a variable is to put the Debugger in <b>Debug Browsing</b>
110
mode. On the Toolbar, toggle the <img SRC="DebugBrowse.png" height=16 width=16>
111
button. Like <a href="Editor.html">Code Browsing</a> you have to hold down the
112
Ctrl key and move your mouse over variables in the source code. The name in the
113
source should be underlined in red and it's current value is displayed in the
114
Editor status bar. Clicking on an underlined variable adds it as a watch.<br>
116
The last way to inspect variables is to use the <b>Shell Debug</b> mode.
117
On the Toolbar, toggle the <img SRC="ShellDebug.png" height=16 width=16>
118
button. The Editor should switch to the Shell and display a debugging prompt.
119
Here you may also type any valid Python expression. Toggle the button again to
120
return to a normal shell prompt.
125
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
128
<td VALIGN=TOP BGCOLOR="#ddeeff" >
130
List of all objects in local scope of the selected stack level.
131
<br>Select/right-click to add as a watch or add your own locals watch
133
Note that this view is only updated when it is active, when there are many
134
objects in scope this can degrade performance so only keep it active when you
139
<td WIDTH="25%" VALIGN=TOP BGCOLOR="#ddeeff" >
142
<td VALIGN=TOP BGCOLOR="#ddeeff" >
144
List of all objects in global scope of the selected stack level.
145
<br>Select/right-click to add as a watch or add your own globals watch.
147
Note that this view is only updated when it is active, when there are many
148
objects in scope this can degrade performance so only keep it active when you
154
<a name="DebuggingThreads"></a>
155
<h3>Debugging Threads</h3>
157
The biggest difficulty in debugging Python threads is that the Python debug
158
tracing hook must be set per thread. Therefor a normal breakpoint in a
159
other thread than the main thread (the one the debugger started up with)
160
will never be hit by the main thread's tracer.<br>
161
<a href="#Breakpoints">Hard breakpoints</a> to the rescue! When a hard breakpoint
162
is triggered from within a non-main-thread the debugger has access to the thread
163
and can set the tracer for it, allowing us to step further.
165
<h3>Remote Debugging</h3>
167
Because the debugger server runs out of process anyway (controlled via xmlrpc)
168
it is a small step to debugging a process on a different machine.
170
The first step is to start up the process that you want to debug on the remote
171
machine, create a RemoteServer and install the tracer.
173
There are a few ways to do this.
175
One way is to create a script called e.g. <i>bcrdb</i> which looks like this:
176
<font color="#101090"><pre>
180
sys.path.append('/path/to/boa')
182
from Debugger.RemoteServer import start
183
start('username', 'password')
186
execfile(sys.argv[0], {'__name__': '__main__',
187
'__builtins__': __builtins__})
190
You can now use this script (bcrdb script) instead of Python (python script) to
191
debug remote scripts.
193
You have to add the following snippet to your program to turn on the tracer:
194
<font color="#101090"><pre>
195
if hasattr(sys, 'debugger_control'):
196
sys.debugger_control.set_traceable()
198
Breakpoints encountered in code after the tracer was installed will be caught
201
If Boa is installed normally on the remote machine, <i>Boa.py -R script</i>
202
can be used instead of <i>bcrdb script</i>. (Boa.py imports almost nothing
203
on this code path so no 'pollution' to worry about)
205
The second step is to connect to the Remote Debugger from the Boa IDE. From an
206
open python module, select File->Attach to debugger, and fill in the dialog.
207
You should now be attached to the remote debugger.
209
It is your responsibility to assure that the file paths to the source files are
210
identical on both machines.
213
<a name="ZopeDebugging"></a>
214
<h3>Zope Debugging</h3>
216
Two forms of Zope debugging is provided.<br>
218
Firstly you may debug Zope as a normal Python application.<br>
219
Open up <b>z2.py</b> in the Editor, set it's command-line parameter to <b>-D</b>
220
(File->Set command-line parameters). Now debug it like any other module.<br>
221
Set a hard breakpoint in your Product code to break into your code.
223
Secondly you may directly debug and step through Zope Python Scripts.
224
You should have a working Zope Connection defined in the Explorer. Open the
225
Python Script you want to debug.<br>
226
Now run Zope as described in the first step. The easiest way to break into a
227
Python Script (remember that they execute in a different thread than <b>z2.py</b>) is to
228
install the extremely small Zope Product found in Debugger/ZopeBreakpoint.zip.
229
All this product does is to allow Scripts to access <b>sys.breakpoint</b>.
230
Then using the normal sys.breakpoint() call in your Python Script will break
231
at that line. From now on, normal soft breakpoints will work for the Script.<br>
232
If you don't want to install the Product you can still step through
233
Python Scripts by setting a hard break somewhere in the Zope code that runs in
234
the same thread as the Script. After hitting the hard break, normal breakpoints
235
in your Script should work.
237
Because of the new Signals support added to Zope 2.6. under unix platforms z2.py
238
must be patched on those platforms.<br>
239
(Because the debugger doesn't run programs in the main thread and Signals require this).<br>
241
To patch z2.py, from line 526, change:
242
<font color="#101090"><pre>
243
# install signal handlers if on posix
244
if os.name == 'posix':
245
from Signals import Signals
246
Signals.registerZopeSignals()
249
<font color="#101090"><pre>
250
# install signal handlers if on posix
251
if os.name == 'posix' and not hasattr(sys, 'boa_debugger'):
252
from Signals import Signals
253
Signals.registerZopeSignals()
256
<p> There is limited support provided for debugging Page Templates too.<br>
257
You may add soft breakpoints next to <tal:*> tags inside <metal:use-macro*>
258
sections. The debugger should stop at these breakpoints and you can inspect the
259
namespace with watches or the Debugger shell. Stepping is not supported.
261
Another way to debug Zope from Boa is to install the functions in the
262
<b>Debugger/BoaDebugServer.py</b> module as ExternalMethods.
264
This allows you to start and hook Zope into the Boa Debug Server at runtime without
265
running z2.py in the debugger from the IDE.<br>
266
(This also avoids the Signal problems problem on linux and works with an unpatched z2.py)
268
To install the runtime hooking follow the next steps:
270
<li>Boa must be installed on the Zope machine.</li>
271
<li>Copy <b>Debugger/BoaDebugServer.py</b> to Zope's <b>Extensions</b> directory.</li>
272
<li>Edit BoaDebugServer.py and replace <b>c:/Path/To/Boa</b> with the actual path
273
to the installation. You may also optionally replace the username, password passed to the <b>start</b>
274
function for security.</li>
275
<li>You may create the ExternalMethods anywhere you please, I have the following structure:<br>
276
BoaDebugger [Folder]<br>
277
StartDebugServer [ExternalMethod]<br>
278
HookDebugServer [ExternalMethod]<br>
282
To use the runtime hooking follow these steps:
284
<li>With a browser, execute the <b>StartDebugServer</b> method.</li>
285
<li>From the IDE (with any Python module open) choose File->Attach to debugger. </li>
286
<li>With a browser, execute the <b>HookDebugServer</b> method.</li>
289
The debugger is now hooked and ready and soft breakpoints should work.
291
<p> A new way to manage a DebugServer in Zope it to install the BoaDebugger
292
product. The product can be downloaded seperately or built with the
293
Debugger/BoaDebugger/BuildProduct.py script.
297
<table BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="100%" BGCOLOR="#000000" >
299
<table BORDER=0 CELLSPACING=0 WIDTH="100%" BGCOLOR="#FFFFFF" >
300
<tr><td BGCOLOR="#ddeeff">
301
<center><img SRC="dot.gif" height=1 width=1></center>
308
<div align=right><font size="-1">Boa Constructor - Application Help - <b>Debugger</b></font></div>
added
removed
Docs/boa/apphelp/Debugger.html
