Debugging QML Applications

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.

Console API

 function f(a, b) {
   console.log("a is ", a, "b is ", b);
 }

 function f() {
   var x = 12
   console.assert(x == 12, "This will pass");
   console.assert(x > 12, "This will fail");
 }

 function f() {
     console.time("wholeFunction");
     console.time("firstPart");
     // first part
     console.timeEnd("firstPart");
     // second part
     console.timeEnd("wholeFunction");
 }

 function f() {
   console.count("f called");
 }

 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();
 }

Debugging Module Imports

Set the QML_IMPORT_TRACE environment variable to enable debug output from QML's import loading mechanisms.

For example, for a simple QML file like this:

 import QtQuick

 Rectangle { width: 100; height: 100 }

If you set QML_IMPORT_TRACE=1 before running the QML Scene or your QML C++ application, you will see output similar to:

 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"

QML Debugging Infrastructure

The Qt QML module provides services for debugging, inspecting, and profiling applications via a TCP port or a local socket.

Note: The 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.

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 .pro file:

• Qt Quick 1: CONFIG+=declarative_debug
• Qt Quick 2: CONFIG+=qml_debug

If you use another build system, you can pass the following defines to the compiler:

• Qt Quick 1: QT_DECLARATIVE_DEBUG
• Qt Quick 2: QT_QML_DEBUG

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:

QML debugging is enabled. Only use this in a safe environment.

Starting Applications

To enable debugging -- from the start or to attach a debugger later on -- start the application with the following arguments:

-qmljsdebugger=port:<port_from>[,port_to][,host:<ip address>][,block][,file:<local socket>][,services:<comma-separated list of services to enable>]

Where:

• the mandatory port_from specifies either the debugging port or the start port of a range of ports when port_to is specified
• the optional ip address specifies the IP address of the host where the application is running
• the optional block prevents the application from running until the debug client connects to the server
• the optional file specifies the local socket.
• the optional services specifies the services to enable; the default is all that are found. Note that the v4 debug service disables the JIT.

After the application has successfully started, it displays the following message:

QML Debugger: Waiting for connection on port <port_number> or QML Debugger: Connecting to socket at <file>"

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 qmlprofiler command line tool to capture profiling data in a file. To run this tool, enter the following command:

qmlprofiler -p <port> -attach <ip address>

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 Qt Creator: Debugging Qt Quick Projects.