summaryrefslogtreecommitdiffstats
path: root/doc/src/scripting/qtscriptdebugger-manual.qdoc
blob: 0b1f0f4593eb5a52a348b26eac90da9139e6938d (plain)
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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qtscriptdebugger-manual.html
    \title Qt Script Debugger Manual
    \brief A manual describing how to use the Qt Script debugger.

  The Qt Script debugger is a tool for debugging script execution in
  Qt applications that use Qt Script. Application developers can embed
  the debugger into their application through the
  QScriptEngineDebugger class. This manual describes how to use the
  debugger. We assume that the reader is somewhat familiar with
  general debugging concepts and existing debugging tools.

  We assume that the debugger has been integrated into the application
  through the QScriptEngineDebugger::standardWindow()
  function, which provides the standard debugger configuration.

  \tableofcontents

  \section1 Getting Started

  The following image shows the debugger as created with
  \l{QScriptEngineDebugger::}{standardWindow()}:

  \image qtscript-debugger.png Running a script under the Qt Script debugger.

  The debugger will start, i.e., take control over the script's
  execution when any of these conditions are met:

  \list
    \o The \c{debugger} statement is encountered in the script.
    \o Clicking the \gui Interrupt menu item from the \gui Debug
        menu in the main window.
    \o A breakpoint is reached.
    \o An uncaught script exception is thrown.
  \endlist

  Once the debugger is started, the execution state can be inspected,
  e.g., the value of variables can be queried and the current program
  stack shown. New breakpoints can be set.

  The debugger will resume, i.e., give the control back to the script
  engine, when the user clicks \gui Continue menu item from the \gui
  Debug menu. It will be invoked again if one of the conditions
  described in the list above is met.

  \section1 Overview of Debugger Components

  The debugger's functionality is divided into a series of components,
  each being a widget that can be shown in the main window of the
  debugger. The following table describes each component and how they
  relate to each other.

  \table
    \header
      \o Component
      \o Description
  \row
  \o Console Widget 
  \o The console widget provides a command-line interface to the
  debugger's functionality, and also serves as an interactive script
  interpreter. The set of commands and their syntax is inspired by
  GDB, the GNU Debugger. Commands and script variables are
  auto-completed through the TAB key.

  Any console command that causes a change in the debugger or debugger
  target's state will immediately be reflected in the other debugger
  components (e.g. breakpoints or local variables changed).

  The console provides a simple and powerful way of manipulating the
  script environment. For example, typing "x" and hitting enter will
  evaluate "x" in the current stack frame and display the result.
  Typing "x = 123" will assign the value 123 to the variable \c{x} in
  the current scope (or create a global variable \c{x} if there isn't
  one -- scripts evaluated through the console can have arbitrary side
  effects, so be careful).

  \row
  \o Stack Widget
  \o The stack widget shows a backtrace of the script execution state.
  Each row represents one frame in the stack. A row contains the
  frame index (0 being the inner-most frame), the name of the script function,
  and the location (file name and line number). To select a particular
  stack frame to inspect, click on its row.

  \row
  \o Locals Widget
  \o The locals widget shows the variables that are local to the
  currently selected stack frame; that is, the properties of the
  objects in the scope chain and the \c{this}-object. Objects can be
  expanded, so that their properties can be examined, recursively.
  Properties whose value has changed are shown in bold font.

  Properties that are not read-only can be edited. Double-click on the
  value and type in the new value; the value can be an arbitrary
  expression. The expression will be evaluated in the associated stack
  frame. While typing, you can press the TAB key to get possible
  completions for the expression.

  \row
  \o Code Widget
  \o The code widget shows the code of the currently selected script.
    The widget displays an arrow in the left margin, marking the
    code line that is being executed.
    Clicking in the margin of a line will cause a breakpoint to be
    toggled at that line. A breakpoint has to be set on a line that
    contains an actual statement in order to be useful.When an uncaught script exception occurs, the
    offending line will be shown with a red background.

    The code widget is read-only; it cannot currently be used to edit
    and (re)evaluate scripts. This is however possible from the
    command-line interface, see \l{Console Command Reference}.

  \row
  \o Scripts Widget

  \o The scripts widget shows the scripts that are currently loaded in
  the script engine. Clicking on a script will cause its code to be
  shown in the code widget. When a script is no longer referenced by
  the debugger target it is removed from the scripts widget. Code
  evaluated through QScriptEngine::evaluate() without a name specified, will be
  displayed in the widget as Anonymous.

  \row
    \o Breakpoints Widget

  \o The breakpoints widget shows all the breakpoints that are set.  A
  breakpoint can be disabled or enabled by clicking the checkbox next
  to the breakpoint's ID (the ID is provided so that the breakpoint
  can be manipulated through the console widget as well).

  A condition can be associated with the breakpoint; the condition can
  be an arbitrary expression that should evaluate to true or
  false. The breakpoint will only be triggered when its location is
  reached \bold{and} the condition evaluates to true.

  Similarly, if the breakpoint's ignore-count is set to N, the
  breakpoint will be ignored the next N times it is hit.

  A new breakpoint can be set by clicking the New Breakpoint button
  and typing in a location of the form <filename>\bold{:}<linenumber>.
  The breakpoint location can refer to an already loaded script, or
  one that has not been loaded yet.

  \row
  \o Debug Output Widget
  \o The debug output widget shows messages generated by the print()
  script function. Scripts can use the special variables \c{__FILE__}
  and \c{__LINE__} to include the current location information in the
  messages.

  \row
  \o Error Log Widget
  \o The error log widget shows error messages that have been generated.
     All uncaught exceptions that occur in the engine will appear here.

  \endtable

  \section2 Resuming Script Evaluation

  Script evaluation can be resumed in one of the following ways:

  \list
  \o \bold{Continue}: Evaluation will resume normally.
  \o \bold{Step Into}: Evaluation will resume until the next statement is reached.
  \o \bold{Step Over}: Evaluation will resume until the next statement is reached;
                but if the current statement is a function call, the debugger
                will treat it as a single statement.
  \o \bold{Step Out}: Evaluation will resume until the current function exits and
               the next statement is reached.
  \o \bold{Run to Cursor}: Run until the statement at the cursor is reached.
  \o \bold{Run to New Script}: Run until the first statement of a new script is reached.
  \endlist

  In any case, script evaluation can also be stopped due to either of the
  following reasons:

  \list
  \o A \c{debugger} statement is encountered.
  \o A breakpoint is hit.
  \o An uncaught script exception occurs.
  \endlist

  \section2 Resuming After an Uncaught Exception

  When an uncaught script exception occurs, it is not possible to
  continue evaluating the current function normally. However, you can
  use the console command \bold{return} to catch the exception and
  return a value to the calling function.

  \section1 Console Command Reference

  Note that you can also get help on the available commands by typing
  ".help" in the console.

  \section2 Breakpoint-related Commands

  Break points is set

  \section3 break <location>

  Sets a breakpoint at a given code line.

  \code
  .break foo.qs:123
  \endcode

  This command sets a breakpoint at \c{foo.qs}, line 123.

  \code
  .break 123
  \endcode

  This command sets a breakpoint at line 123 in the current script; the current script
  is the script associated with the current stack frame.

  Each breakpoint has a unique identifier (an integer) associated with it.
  This identifier is needed by other breakpoint-related commands.

  \section3 clear <location>

  \code
  .clear foo.qs:123
  \endcode

  clears (deletes) the breakpoint at \c{foo.qs}, line 123.

  \code
  clear 123
  \endcode

  clears (deletes) the breakpoint at line 123 in the current script;
  the current script is the script associated with the current stack
  frame.

  \section3 condition <breakpoint-id> <expression>

  Sets a condition for a breakpoint.

  \code
  .condition 1 i > 42
  \endcode

  specifies that breakpoint 1 should only be triggered if the variable \c{i}
  is greater than 42.

  The expression can be an arbitrary one, i.e. it can have
  side-effects. It can be any valid QScript conditional
  expression.

  \section3 delete <breakpoint-id>

  Deletes a breakpoint, i.e., removes it from the current debugging
  session.

  \section3 disable <breakpoint-id>

  Disables a breakpoint. The breakpoint will continue to exist, but
  will not stop program execution.

  \section3 enable <breakpoint-id>

  Enables a breakpoint. Breakpoints are enabled by default, so you
  only need to use this command if you have disabled to breakpoint
  previously.

  \section3 ignore <breakpoint-id> <count>
  
  Sets the ignore-count of a breakpoint, i.e., the breakpoint will not
  stop the program execution unless it have been reached \c count
  times. This can, for instance, be useful in loops to stop at a
  specific iteration.

  \code
  .ignore 1 5
  \endcode

  Specifies that breakpoint 1 should be ignored the next 5 times it is
  hit.

  \section3 info breakpoints

  Lists the breakpoints that are set.

  \code
    .info breakpoints
  \endcode

  \section3 tbreak <location>

  Sets a temporary breakpoint. This command is identical to the
  \c{break} command, only the breakpoint will be automatically deleted
  the first time it is hit.

  \section2 File-related Commands

  \section3 list <location>

  Lists the contents of a script around a given location, where the
  location is given as a line number and, optionally, the name of the
  file from which you will print. If only a line number is given, \c
  {.list} will use the file of the current stack frame.

  \code
    .list foo.qs:125
  \endcode

  When no arguments are given, \c{list} will incrementally list
  sections of the current script.

  \section3 info scripts

  Lists the scripts that are currently loaded.

  \section2 Execution-related Commands

  \section3 advance <location>

  Advances execution to a given location. The syntax of the location
  is the same as for setting breakpoints. For example:

  \code
    .advance foo.qs:125
  \endcode

  \section3 continue

  Continues execution normally, i.e, gives the execution control over
  the script back to the QScriptEngine.

  \section3 eval <program>

  Evaluates a program. 

  \section3 finish

  Continues execution until the current function exits and the next
  statement is reached (i.e., the statement after the call to the
  function).

  \section3 interrupt

  Requests that execution should be interrupted. Interruption will
  occur as soon as a new script statement is reached.

  \section3 next <count = 1>

  Continues execution until a new statement is reached; but if the
  current statement is a function call, the function call will be
  treated as a single statement. This will be done \c count times
  before execution is stopped; the default is one.

  \section3 return <expression>

  Makes the current frame return to its caller. If \c expression is
  given, it will sent as the result of the function (i.e., replacing
  the functions return value). \c expression can be any valid QScript
  expression.

  \section3 step <count = 1>

  Continues execution until a new statement is reached. If the number
  \c count is given as argument, this will be done \c count times
  before execution is stopped. As opposed to \l{next <count = 1>},  \c
  step will enter functions when encountering a function call
  statement.

  \section2 Stack-related Commands

  \section3 backtrace

  Shows a backtrace of the current execution. The trace will list the
  function name and its position in the script for each stack frame.

  \section3 down

  Selects the previous (inner) stack frame. The execution will not
  return to this frame, but you will get access to its local
  variables. 

  \section3 frame <index>

  This command moves to the stack frame with the given \c index. The
  index of the frame on the top of the stack is 0. Previous frames are
  numbered from 1 and upwards (the bottom frame in the stack has the
  largest index).

  \section3 info locals

  Lists the variables that are in the scope of the current frame.

  \section3 up

  Selects the next (outer) stack frame.

*/