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