doc/src/declarative/qdeclarativedebugging.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  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 Timer
  53
  54 \c console.time and console.timeEnd log the time (in milliseconds) that was spent between
  55 the calls. Both take a string argument that identifies the measurement. For example:
  56
  57 \qml
  58 function f() {
  59     console.time("wholeFunction");
  60     console.time("firstPart");
  61     // first part
  62     console.timeEnd("firstPart");
  63     // second part
  64     console.timeEnd("wholeFunction");
  65 }
  66 \endqml
  67
  68 \section2 Trace
  69
  70 \c console.trace prints the stack trace of JavaScript execution at the point where
  71 it was called. The stack trace info contains function name, file name, line number
  72 and column number. The stack trace is limited to last 10 stack frames.
  73
  74 \section2 Count
  75
  76 \c console.count prints the current number of times a particular piece of code has been executed,
  77 along with a message. That is,
  78
  79 \qml
  80 function f() {
  81   console.count("f called");
  82 }
  83 \endqml
  84
  85 will print \c{f called: 1}, \c{f called: 2} ... whenever \c{f()} is executed.
  86
  87 \section2 Profile
  88
  89 \c console.profile turns on the QML and JavaScript profilers. Nested calls are not
  90 supported and a warning will be printed to the console.
  91
  92 \c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
  93 without a previous call to console.profile will print a warning to the console. A
  94 profiling client should have been attached before this call to receive and store the
  95 profiling data. For example:
  96
  97 \qml
  98 function f() {
  99     console.profile();
 100     //Call some function that needs to be profiled.
 101     //Ensure that a client is attached before ending
 102     //the profiling session.
 103     console.profileEnd();
 104 }
 105 \endqml
 106
 107 \section1 Debugging Transitions
 108
 109 When a transition doesn't look quite right, it can be helpful to view it in slow
 110 motion to see what is happening more clearly. This functionality is supported
 111 in the \l {QML Viewer} tool: to enable this,
 112 click on the "Debugging" menu, then "Slow Down Animations".
 113
 114
 115 \section1 Debugging module imports
 116
 117 The \c QML_IMPORT_TRACE environment variable can be set to enable debug output
 118 from QML's import loading mechanisms.
 119
 120 For example, for a simple QML file like this:
 121
 122 \qml
 123 import QtQuick 1.0
 124
 125 Rectangle { width: 100; height: 100 }
 126 \endqml
 127
 128 If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer}
 129 (or your QML C++ application), you will see output similar to this:
 130
 131 \code
 132 QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports"
 133 QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
 134 QDeclarativeImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
 135 QDeclarativeImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
 136 QDeclarativeImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
 137 \endcode
 138
 139
 140 \section1 Debugging with Qt Creator
 141
 142 \l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in
 143 support for QML debugging. QML projects and standalone C++ applications that
 144 utilize QML can be debugged on desktops as well as on remote devices.
 145 For more information, see the Qt Creator Manual.
 146
 147 */