source: trunk/doc/src/scripting/qtscriptdebugger-manual.qdoc@ 973

Last change on this file since 973 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

  • Property svn:eol-style set to native
File size: 14.0 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \page qtscriptdebugger-manual.html
30 \title Qt Script Debugger Manual
31 \brief A manual describing how to use the Qt Script debugger.
32
33 The Qt Script debugger is a tool for debugging script execution in
34 Qt applications that use Qt Script. Application developers can embed
35 the debugger into their application through the
36 QScriptEngineDebugger class. This manual describes how to use the
37 debugger. We assume that the reader is somewhat familiar with
38 general debugging concepts and existing debugging tools.
39
40 We assume that the debugger has been integrated into the application
41 through the QScriptEngineDebugger::standardWindow()
42 function, which provides the standard debugger configuration.
43
44 \tableofcontents
45
46 \section1 Getting Started
47
48 The following image shows the debugger as created with
49 \l{QScriptEngineDebugger::}{standardWindow()}:
50
51 \image qtscript-debugger.png Running a script under the Qt Script debugger.
52
53 The debugger will start, i.e., take control over the script's
54 execution when any of these conditions are met:
55
56 \list
57 \o The \c{debugger} statement is encountered in the script.
58 \o Clicking the \gui Interrupt menu item from the \gui Debug
59 menu in the main window.
60 \o A breakpoint is reached.
61 \o An uncaught script exception is thrown.
62 \endlist
63
64 Once the debugger is started, the execution state can be inspected,
65 e.g., the value of variables can be queried and the current program
66 stack shown. New breakpoints can be set.
67
68 The debugger will resume, i.e., give the control back to the script
69 engine, when the user clicks \gui Continue menu item from the \gui
70 Debug menu. It will be invoked again if one of the conditions
71 described in the list above is met.
72
73 \section1 Overview of Debugger Components
74
75 The debugger's functionality is divided into a series of components,
76 each being a widget that can be shown in the main window of the
77 debugger. The following table describes each component and how they
78 relate to each other.
79
80 \table
81 \header
82 \o Component
83 \o Description
84 \row
85 \o Console Widget
86 \o The console widget provides a command-line interface to the
87 debugger's functionality, and also serves as an interactive script
88 interpreter. The set of commands and their syntax is inspired by
89 GDB, the GNU Debugger. Commands and script variables are
90 auto-completed through the TAB key.
91
92 Any console command that causes a change in the debugger or debugger
93 target's state will immediately be reflected in the other debugger
94 components (e.g. breakpoints or local variables changed).
95
96 The console provides a simple and powerful way of manipulating the
97 script environment. For example, typing "x" and hitting enter will
98 evaluate "x" in the current stack frame and display the result.
99 Typing "x = 123" will assign the value 123 to the variable \c{x} in
100 the current scope (or create a global variable \c{x} if there isn't
101 one -- scripts evaluated through the console can have arbitrary side
102 effects, so be careful).
103
104 \row
105 \o Stack Widget
106 \o The stack widget shows a backtrace of the script execution state.
107 Each row represents one frame in the stack. A row contains the
108 frame index (0 being the inner-most frame), the name of the script function,
109 and the location (file name and line number). To select a particular
110 stack frame to inspect, click on its row.
111
112 \row
113 \o Locals Widget
114 \o The locals widget shows the variables that are local to the
115 currently selected stack frame; that is, the properties of the
116 objects in the scope chain and the \c{this}-object. Objects can be
117 expanded, so that their properties can be examined, recursively.
118 Properties whose value has changed are shown in bold font.
119
120 Properties that are not read-only can be edited. Double-click on the
121 value and type in the new value; the value can be an arbitrary
122 expression. The expression will be evaluated in the associated stack
123 frame. While typing, you can press the TAB key to get possible
124 completions for the expression.
125
126 \row
127 \o Code Widget
128 \o The code widget shows the code of the currently selected script.
129 The widget displays an arrow in the left margin, marking the
130 code line that is being executed.
131 Clicking in the margin of a line will cause a breakpoint to be
132 toggled at that line. A breakpoint has to be set on a line that
133 contains an actual statement in order to be useful.When an uncaught script exception occurs, the
134 offending line will be shown with a red background.
135
136 The code widget is read-only; it cannot currently be used to edit
137 and (re)evaluate scripts. This is however possible from the
138 command-line interface, see \l{Console Command Reference}.
139
140 \row
141 \o Scripts Widget
142
143 \o The scripts widget shows the scripts that are currently loaded in
144 the script engine. Clicking on a script will cause its code to be
145 shown in the code widget. When a script is no longer referenced by
146 the debugger target it is removed from the scripts widget. Code
147 evaluated through QScriptEngine::evaluate() without a name specified, will be
148 displayed in the widget as Anonymous.
149
150 \row
151 \o Breakpoints Widget
152
153 \o The breakpoints widget shows all the breakpoints that are set. A
154 breakpoint can be disabled or enabled by clicking the checkbox next
155 to the breakpoint's ID (the ID is provided so that the breakpoint
156 can be manipulated through the console widget as well).
157
158 A condition can be associated with the breakpoint; the condition can
159 be an arbitrary expression that should evaluate to true or
160 false. The breakpoint will only be triggered when its location is
161 reached \bold{and} the condition evaluates to true.
162
163 Similarly, if the breakpoint's ignore-count is set to N, the
164 breakpoint will be ignored the next N times it is hit.
165
166 A new breakpoint can be set by clicking the New Breakpoint button
167 and typing in a location of the form <filename>\bold{:}<linenumber>.
168 The breakpoint location can refer to an already loaded script, or
169 one that has not been loaded yet.
170
171 \row
172 \o Debug Output Widget
173 \o The debug output widget shows messages generated by the print()
174 script function. Scripts can use the special variables \c{__FILE__}
175 and \c{__LINE__} to include the current location information in the
176 messages.
177
178 \row
179 \o Error Log Widget
180 \o The error log widget shows error messages that have been generated.
181 All uncaught exceptions that occur in the engine will appear here.
182
183 \endtable
184
185 \section2 Resuming Script Evaluation
186
187 Script evaluation can be resumed in one of the following ways:
188
189 \list
190 \o \bold{Continue}: Evaluation will resume normally.
191 \o \bold{Step Into}: Evaluation will resume until the next statement is reached.
192 \o \bold{Step Over}: Evaluation will resume until the next statement is reached;
193 but if the current statement is a function call, the debugger
194 will treat it as a single statement.
195 \o \bold{Step Out}: Evaluation will resume until the current function exits and
196 the next statement is reached.
197 \o \bold{Run to Cursor}: Run until the statement at the cursor is reached.
198 \o \bold{Run to New Script}: Run until the first statement of a new script is reached.
199 \endlist
200
201 In any case, script evaluation can also be stopped due to either of the
202 following reasons:
203
204 \list
205 \o A \c{debugger} statement is encountered.
206 \o A breakpoint is hit.
207 \o An uncaught script exception occurs.
208 \endlist
209
210 \section2 Resuming After an Uncaught Exception
211
212 When an uncaught script exception occurs, it is not possible to
213 continue evaluating the current function normally. However, you can
214 use the console command \bold{return} to catch the exception and
215 return a value to the calling function.
216
217 \section1 Console Command Reference
218
219 Note that you can also get help on the available commands by typing
220 ".help" in the console.
221
222 \section2 Breakpoint-related Commands
223
224 Break points is set
225
226 \section3 break <location>
227
228 Sets a breakpoint at a given code line.
229
230 \code
231 .break foo.qs:123
232 \endcode
233
234 This command sets a breakpoint at \c{foo.qs}, line 123.
235
236 \code
237 .break 123
238 \endcode
239
240 This command sets a breakpoint at line 123 in the current script; the current script
241 is the script associated with the current stack frame.
242
243 Each breakpoint has a unique identifier (an integer) associated with it.
244 This identifier is needed by other breakpoint-related commands.
245
246 \section3 clear <location>
247
248 \code
249 .clear foo.qs:123
250 \endcode
251
252 clears (deletes) the breakpoint at \c{foo.qs}, line 123.
253
254 \code
255 clear 123
256 \endcode
257
258 clears (deletes) the breakpoint at line 123 in the current script;
259 the current script is the script associated with the current stack
260 frame.
261
262 \section3 condition <breakpoint-id> <expression>
263
264 Sets a condition for a breakpoint.
265
266 \code
267 .condition 1 i > 42
268 \endcode
269
270 specifies that breakpoint 1 should only be triggered if the variable \c{i}
271 is greater than 42.
272
273 The expression can be an arbitrary one, i.e. it can have
274 side-effects. It can be any valid QScript conditional
275 expression.
276
277 \section3 delete <breakpoint-id>
278
279 Deletes a breakpoint, i.e., removes it from the current debugging
280 session.
281
282 \section3 disable <breakpoint-id>
283
284 Disables a breakpoint. The breakpoint will continue to exist, but
285 will not stop program execution.
286
287 \section3 enable <breakpoint-id>
288
289 Enables a breakpoint. Breakpoints are enabled by default, so you
290 only need to use this command if you have disabled to breakpoint
291 previously.
292
293 \section3 ignore <breakpoint-id> <count>
294
295 Sets the ignore-count of a breakpoint, i.e., the breakpoint will not
296 stop the program execution unless it have been reached \c count
297 times. This can, for instance, be useful in loops to stop at a
298 specific iteration.
299
300 \code
301 .ignore 1 5
302 \endcode
303
304 Specifies that breakpoint 1 should be ignored the next 5 times it is
305 hit.
306
307 \section3 info breakpoints
308
309 Lists the breakpoints that are set.
310
311 \code
312 .info breakpoints
313 \endcode
314
315 \section3 tbreak <location>
316
317 Sets a temporary breakpoint. This command is identical to the
318 \c{break} command, only the breakpoint will be automatically deleted
319 the first time it is hit.
320
321 \section2 File-related Commands
322
323 \section3 list <location>
324
325 Lists the contents of a script around a given location, where the
326 location is given as a line number and, optionally, the name of the
327 file from which you will print. If only a line number is given, \c
328 {.list} will use the file of the current stack frame.
329
330 \code
331 .list foo.qs:125
332 \endcode
333
334 When no arguments are given, \c{list} will incrementally list
335 sections of the current script.
336
337 \section3 info scripts
338
339 Lists the scripts that are currently loaded.
340
341 \section2 Execution-related Commands
342
343 \section3 advance <location>
344
345 Advances execution to a given location. The syntax of the location
346 is the same as for setting breakpoints. For example:
347
348 \code
349 .advance foo.qs:125
350 \endcode
351
352 \section3 continue
353
354 Continues execution normally, i.e, gives the execution control over
355 the script back to the QScriptEngine.
356
357 \section3 eval <program>
358
359 Evaluates a program.
360
361 \section3 finish
362
363 Continues execution until the current function exits and the next
364 statement is reached (i.e., the statement after the call to the
365 function).
366
367 \section3 interrupt
368
369 Requests that execution should be interrupted. Interruption will
370 occur as soon as a new script statement is reached.
371
372 \section3 next <count = 1>
373
374 Continues execution until a new statement is reached; but if the
375 current statement is a function call, the function call will be
376 treated as a single statement. This will be done \c count times
377 before execution is stopped; the default is one.
378
379 \section3 return <expression>
380
381 Makes the current frame return to its caller. If \c expression is
382 given, it will sent as the result of the function (i.e., replacing
383 the functions return value). \c expression can be any valid QScript
384 expression.
385
386 \section3 step <count = 1>
387
388 Continues execution until a new statement is reached. If the number
389 \c count is given as argument, this will be done \c count times
390 before execution is stopped. As opposed to \l{next <count = 1>}, \c
391 step will enter functions when encountering a function call
392 statement.
393
394 \section2 Stack-related Commands
395
396 \section3 backtrace
397
398 Shows a backtrace of the current execution. The trace will list the
399 function name and its position in the script for each stack frame.
400
401 \section3 down
402
403 Selects the previous (inner) stack frame. The execution will not
404 return to this frame, but you will get access to its local
405 variables.
406
407 \section3 frame <index>
408
409 This command moves to the stack frame with the given \c index. The
410 index of the frame on the top of the stack is 0. Previous frames are
411 numbered from 1 and upwards (the bottom frame in the stack has the
412 largest index).
413
414 \section3 info locals
415
416 Lists the variables that are in the scope of the current frame.
417
418 \section3 up
419
420 Selects the next (outer) stack frame.
421
422*/
Note: See TracBrowser for help on using the repository browser.