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
|
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtquick-debugging.html
\ingroup qtquick-tools
\title Debugging QML Applications
\brief Provides information on how to use QML's debugging tools.
When you develop an application with QML, there are many ways to debug possible issues that you
may face. The sections below describe the debugging tools available and how to use them.
\section1 Console API
\table
\header
\li Feature
\li Description
\row
\keyword console log
\li Log
\li Use \c{console.log}, \c{console.debug}, \c{console.info}, \c{console.warn}, or
\c{console.error} to print debugging information to the console.
For example:
\code
function f(a, b) {
console.log("a is ", a, "b is ", b);
}
\endcode
The output is generated using the qCDebug, qCWarning, or qCCritical methods in C++,
with a category of \c qml or \c js, depending on the type of file doing the logging.
See also \l {Debugging Techniques}.
\row
\keyword console assert
\li Assert
\li \c console.assert tests that an expression is true. If not, it writes an optional
message to the console and prints the stack trace.
For example:
\code
function f() {
var x = 12
console.assert(x == 12, "This will pass");
console.assert(x > 12, "This will fail");
}
\endcode
\row
\keyword console time
\keyword console timeEnd
\li Timer
\li \c{console.time} and \c{console.timeEnd} log the time (in milliseconds) that was spent
between the calls. Both take a string argument that identifies the measurement.
For example:
\code
function f() {
console.time("wholeFunction");
console.time("firstPart");
// first part
console.timeEnd("firstPart");
// second part
console.timeEnd("wholeFunction");
}
\endcode
\row
\keyword console trace
\li Trace
\li \c console.trace prints the stack trace of the JavaScript execution at the point where
it was called. This stack trace information contains the function name, file name,
line number, and column number. The stack trace is limited to last 10 stack frames.
\row
\keyword console count
\li Count
\li \c console.count prints the current number of times a particular piece of code has run,
along with a message.
For example:
\code
function f() {
console.count("f called");
}
\endcode
The code sample above prints \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is
run.
\row
\keyword console profile
\li Profile
\li \c console.profile turns on the QML and JavaScript profilers. Nested calls are not
supported and prints a warning to the console.
\row
\keyword console profileEnd
\li ProfileEnd
\li \c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
without a previous call to \c console.profile prints a warning to the console. A
profiling client needs to be attached before this call to receive and store the
profiling data.
For example:
\code
function f() {
console.profile();
//Call some function that needs to be profiled.
//Ensure that a client is attached before ending
//the profiling session.
console.profileEnd();
}
\endcode
\row
\keyword console exception
\li Exception
\li \c console.exception prints an error message together with the stack trace of
JavaScript execution at the point where it is called.
\endtable
\section1 Debugging Module Imports
Set the \c QML_IMPORT_TRACE environment variable to enable debug output from QML's import loading
mechanisms.
For example, for a simple QML file like this:
\qml
import QtQuick 2.3
Rectangle { width: 100; height: 100 }
\endqml
If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qmlscene.html}{QML Scene} or your
QML C++ application, you will see output similar to:
\code
QQmlImportDatabase::addImportPath "/qt-sdk/imports"
QQmlImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
QQmlImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
QQmlImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
QQmlImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
\endcode
\section1 QML Debugging Infrastructure
\keyword declarative_debug
\keyword qml debug
The \l{Qt QML} module provides services for debugging, inspecting, and profiling applications via a
TCP port or a local socket.
\note The \c qmltooling plugins that are required for debugging and profiling
QML applications on devices are automatically installed during Qt installation.
They must be deployed to the devices for debugging and profiling to work.
\section2 Enabling the Infrastructure
When you compile your application, you must explicitly enable the debugging infrastructure. If you
use qmake, you can add the configuration parameters to the project \c{.pro} file:
\list
\li Qt Quick 1: \c {CONFIG+=declarative_debug}
\li Qt Quick 2: \c {CONFIG+=qml_debug}
\endlist
If you use another build system, you can pass the following defines to the compiler:
\list
\li Qt Quick 1: \c {QT_DECLARATIVE_DEBUG}
\li Qt Quick 2: \c {QT_QML_DEBUG}
\endlist
\note Enabling the debugging infrastructure may compromise the integrity of your application and
system, and therefore, you should only enable it in a controlled environment. When the
infrastructure is enabled, the application displays the following warning:
\c {QML debugging is enabled. Only use this in a safe environment.}
\section2 Starting Applications
To enable debugging -- from the start or to attach a debugger later on -- start the application
with the following arguments:
\c {-qmljsdebugger=port:<port_from>[,port_to][,host:<ip address>][,block][,file:<local socket>][,services:<comma-separated list of services to enable>]}
Where:
\list
\li the mandatory \c {port_from} specifies either the debugging port or the start port of a
range of ports when \c {port_to} is specified
\li the optional \c {ip address} specifies the IP address of the host where the application is
running
\li the optional \c block prevents the application from running until the debug client connects
to the server
\li the optional \c {file} specifies the local socket.
\li the optional \c {services} specifies the services to enable; the default is all that are
found. Note that the \c{v4 debug} service disables the JIT.
\endlist
After the application has successfully started, it displays the following message:
\c {QML Debugger: Waiting for connection on port <port_number>}
or
\c {QML Debugger: Connecting to socket at <file>"}
\section2 Connecting to Applications
When the application is running, an IDE or a tool that implements the binary protocol can connect
to the open port.
Qt provides a \c qmlprofiler command line tool to capture profiling data in a file. To run this
tool, enter the following command:
\c {qmlprofiler -p <port> -attach <ip address>}
\section1 Debugging with Qt Creator
Qt Creator uses the debugging infrastructure to debug, inspect, and profile Qt Quick applications
on the desktop as well as on remote devices. Qt Creator provides integrated clients for debugging
JavaScript, inspecting the object tree, and profiling the activities of a QML engine. For more
information, see \l{Qt Creator: Debugging Qt Quick Projects}.
*/
|
