Update copyright headers
[qt:qt.git] / doc / src / scripting / qtscriptdebugger-manual.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
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 */