doc/src/declarative/qdeclarativedebugging.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qdeclarativedebugging.html
  30 \inqmlmodule QtQuick 2
  31 \title Debugging QML
  32
  33 \section1 Console API
  34
  35 \section2 Log
  36
  37 \c console.log, console.debug, console.info, console.warn and console.error can be used to print
  38 debugging information to the console. For example:
  39
  40 \qml
  41 function f(a, b) {
  42   console.log("a is ", a, "b is ", b);
  43 }
  44 \endqml
  45
  46 The output is generated using the qDebug, qWarning, qCritical methods in C++
  47 (see also http://doc.qt.nokia.com/latest/debug.html#warning-and-debugging-messages).
  48
  49 \hint Setting the environment variable QML_CONSOLE_EXTENDED also prints the source
  50 code location of the call.
  51
  52 \section2 Assert
  53
  54 \c console.assert tests that an expression is true. If not, it will write an optional message
  55 to the console and print the stack trace.
  56
  57 \qml
  58 function f() {
  59   var x = 12
  60   console.assert(x == 12, "This will pass");
  61   console.assert(x > 12, "This will fail");
  62 }
  63 \endqml
  64
  65 \section2 Timer
  66
  67 \c console.time and console.timeEnd log the time (in milliseconds) that was spent between
  68 the calls. Both take a string argument that identifies the measurement. For example:
  69
  70 \qml
  71 function f() {
  72     console.time("wholeFunction");
  73     console.time("firstPart");
  74     // first part
  75     console.timeEnd("firstPart");
  76     // second part
  77     console.timeEnd("wholeFunction");
  78 }
  79 \endqml
  80
  81 \section2 Trace
  82
  83 \c console.trace prints the stack trace of JavaScript execution at the point where
  84 it was called. The stack trace info contains function name, file name, line number
  85 and column number. The stack trace is limited to last 10 stack frames.
  86
  87 \section2 Count
  88
  89 \c console.count prints the current number of times a particular piece of code has been executed,
  90 along with a message. That is,
  91
  92 \qml
  93 function f() {
  94   console.count("f called");
  95 }
  96 \endqml
  97
  98 will print \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is executed.
  99
 100 \section2 Profile
 101
 102 \c console.profile turns on the QML and JavaScript profilers. Nested calls are not
 103 supported and a warning will be printed to the console.
 104
 105 \c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
 106 without a previous call to console.profile will print a warning to the console. A
 107 profiling client should have been attached before this call to receive and store the
 108 profiling data. For example:
 109
 110 \qml
 111 function f() {
 112     console.profile();
 113     //Call some function that needs to be profiled.
 114     //Ensure that a client is attached before ending
 115     //the profiling session.
 116     console.profileEnd();
 117 }
 118 \endqml
 119
 120 \section2 Exception
 121
 122 \c console.exception prints an error message together with the stack trace of JavaScript
 123 execution at the point where it is called.
 124
 125 \section1 Debugging Transitions
 126
 127 When a transition doesn't look quite right, it can be helpful to view it in slow
 128 motion to see what is happening more clearly. This functionality is supported
 129 in the \l {QML Viewer} tool: to enable this,
 130 click on the "Debugging" menu, then "Slow Down Animations".
 131
 132
 133 \section1 Debugging module imports
 134
 135 The \c QML_IMPORT_TRACE environment variable can be set to enable debug output
 136 from QML's import loading mechanisms.
 137
 138 For example, for a simple QML file like this:
 139
 140 \qml
 141 import QtQuick 1.0
 142
 143 Rectangle { width: 100; height: 100 }
 144 \endqml
 145
 146 If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer}
 147 (or your QML C++ application), you will see output similar to this:
 148
 149 \code
 150 QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports"
 151 QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
 152 QDeclarativeImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
 153 QDeclarativeImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
 154 QDeclarativeImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
 155 \endcode
 156
 157
 158 \section1 Debugging with Qt Creator
 159
 160 \l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in
 161 support for QML debugging. QML projects and standalone C++ applications that
 162 utilize QML can be debugged on desktops as well as on remote devices.
 163 For more information, see the Qt Creator Manual.
 164
 165 */