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 |
|
---|
|
---|