doc/src/declarative/qdeclarativedebugging.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   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.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 Profile
  75
  76 \c console.profile turns on the QML and JavaScript profilers. Nested calls are not
  77 supported and a warning will be printed to the console.
  78
  79 \c console.profileEnd turns off the QML and JavaScript profilers. Calling this function
  80 without a previous call to console.profile will print a warning to the console. A
  81 profiling client should have been attached before this call to receive and store the
  82 profiling data. For example:
  83
  84 \qml
  85 function f() {
  86     console.profile();
  87     //Call some function that needs to be profiled.
  88     //Ensure that a client is attached before ending
  89     //the profiling session.
  90     console.profileEnd();
  91 }
  92 \endqml
  93
  94 \section1 Debugging Transitions
  95
  96 When a transition doesn't look quite right, it can be helpful to view it in slow
  97 motion to see what is happening more clearly. This functionality is supported
  98 in the \l {QML Viewer} tool: to enable this,
  99 click on the "Debugging" menu, then "Slow Down Animations".
 100
 101
 102 \section1 Debugging module imports
 103
 104 The \c QML_IMPORT_TRACE environment variable can be set to enable debug output
 105 from QML's import loading mechanisms.
 106
 107 For example, for a simple QML file like this:
 108
 109 \qml
 110 import QtQuick 1.0
 111
 112 Rectangle { width: 100; height: 100 }
 113 \endqml
 114
 115 If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer}
 116 (or your QML C++ application), you will see output similar to this:
 117
 118 \code
 119 QDeclarativeImportDatabase::addImportPath "/qt-sdk/imports"
 120 QDeclarativeImportDatabase::addImportPath "/qt-sdk/bin/QMLViewer.app/Contents/MacOS"
 121 QDeclarativeImportDatabase::addToImport 0x106237370 "." -1.-1 File as ""
 122 QDeclarativeImportDatabase::addToImport 0x106237370 "Qt" 4.7 Library as ""
 123 QDeclarativeImportDatabase::resolveType "Rectangle" = "QDeclarativeRectangle"
 124 \endcode
 125
 126
 127 \section1 Debugging with Qt Creator
 128
 129 \l{http://qt.nokia.com/products/developer-tools}{Qt Creator} provides built-in
 130 support for QML debugging. QML projects and standalone C++ applications that
 131 utilize QML can be debugged on desktops as well as on remote devices.
 132 For more information, see the Qt Creator Manual.
 133
 134 */