<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- debugging.qdoc -->
<title>Debugging QML Applications | QtDoc 5.1</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader"></div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#console-api">Console API</a></li>
<li class="level2"><a href="#log">Log</a></li>
<li class="level2"><a href="#assert">Assert</a></li>
<li class="level2"><a href="#timer">Timer</a></li>
<li class="level2"><a href="#trace">Trace</a></li>
<li class="level2"><a href="#count">Count</a></li>
<li class="level2"><a href="#profile">Profile</a></li>
<li class="level2"><a href="#exception">Exception</a></li>
<li class="level1"><a href="#debugging-module-imports">Debugging module imports</a></li>
<li class="level1"><a href="#debugging-with-qt-creator">Debugging with Qt Creator</a></li>
</ul>
</div>
<h1 class="title">Debugging QML Applications</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-debugging.html-description -->
<div class="descr"> <a name="details"></a>
<a name="console-api"></a>
<h2>Console API</h2>
<a name="log"></a>
<h3>Log</h3>
<p><tt>console.log</tt>, console.debug, console.info, console.warn and console.error can be used to print debugging information to the console. For example:</p>
<pre class="cpp">function f(a<span class="operator">,</span> b) {
console<span class="operator">.</span>log(<span class="string">"a is "</span><span class="operator">,</span> a<span class="operator">,</span> <span class="string">"b is "</span><span class="operator">,</span> b);
}</pre>
<p>The output is generated using the qDebug, qWarning, qCritical methods in C++ (see also <a href="debug.html">Debugging Techniques</a>).</p>
<p>Setting the environment variable QML_CONSOLE_EXTENDED also prints the source code location of the call.</p>
<a name="assert"></a>
<h3>Assert</h3>
<p><tt>console.assert</tt> tests that an expression is true. If not, it will write an optional message to the console and print the stack trace.</p>
<pre class="cpp">function f() {
var x <span class="operator">=</span> <span class="number">12</span>
console<span class="operator">.</span>assert(x <span class="operator">=</span><span class="operator">=</span> <span class="number">12</span><span class="operator">,</span> <span class="string">"This will pass"</span>);
console<span class="operator">.</span>assert(x <span class="operator">></span> <span class="number">12</span><span class="operator">,</span> <span class="string">"This will fail"</span>);
}</pre>
<a name="timer"></a>
<h3>Timer</h3>
<p><tt>console.time</tt> and console.timeEnd log the time (in milliseconds) that was spent between the calls. Both take a string argument that identifies the measurement. For example:</p>
<pre class="cpp">function f() {
console<span class="operator">.</span>time(<span class="string">"wholeFunction"</span>);
console<span class="operator">.</span>time(<span class="string">"firstPart"</span>);
<span class="comment">// first part</span>
console<span class="operator">.</span>timeEnd(<span class="string">"firstPart"</span>);
<span class="comment">// second part</span>
console<span class="operator">.</span>timeEnd(<span class="string">"wholeFunction"</span>);
}</pre>
<a name="trace"></a>
<h3>Trace</h3>
<p><tt>console.trace</tt> prints the stack trace of the JavaScript execution at the point where it was called. The stack trace info contains the function name, file name, line number and column number. The stack trace is limited to last 10 stack frames.</p>
<a name="count"></a>
<h3>Count</h3>
<p><tt>console.count</tt> prints the current number of times a particular piece of code has been executed, along with a message. That is,</p>
<pre class="cpp">function f() {
console<span class="operator">.</span>count(<span class="string">"f called"</span>);
}</pre>
<p>will print <tt>f called: 1</tt>, <tt>f called: 2</tt> ... whenever <tt>f()</tt> is executed.</p>
<a name="profile"></a>
<h3>Profile</h3>
<p><tt>console.profile</tt> turns on the QML and JavaScript profilers. Nested calls are not supported and a warning will be printed to the console.</p>
<p><tt>console.profileEnd</tt> turns off the QML and JavaScript profilers. Calling this function without a previous call to console.profile will print a warning to the console. A profiling client should have been attached before this call to receive and store the profiling data. For example:</p>
<pre class="cpp">function f() {
console<span class="operator">.</span>profile();
<span class="comment">//Call some function that needs to be profiled.</span>
<span class="comment">//Ensure that a client is attached before ending</span>
<span class="comment">//the profiling session.</span>
console<span class="operator">.</span>profileEnd();
}</pre>
<a name="exception"></a>
<h3>Exception</h3>
<p><tt>console.exception</tt> prints an error message together with the stack trace of JavaScript execution at the point where it is called.</p>
<a name="debugging-module-imports"></a>
<h2>Debugging module imports</h2>
<p>The <tt>QML_IMPORT_TRACE</tt> environment variable can be set to enable debug output from QML's import loading mechanisms.</p>
<p>For example, for a simple QML file like this:</p>
<pre class="qml">import QtQuick 2.0
<span class="type">Rectangle</span> { <span class="name">width</span>: <span class="number">100</span>; <span class="name">height</span>: <span class="number">100</span> }</pre>
<p>If you set <tt>QML_IMPORT_TRACE=1</tt> before running the <a href="qtquick-qmlscene.html">QML Scene</a> (or your QML C++ application), you will see output similar to this:</p>
<pre class="cpp"><span class="type">QQmlImportDatabase</span><span class="operator">::</span>addImportPath <span class="string">"/qt-sdk/imports"</span>
<span class="type">QQmlImportDatabase</span><span class="operator">::</span>addImportPath <span class="string">"/qt-sdk/bin/QMLViewer.app/Contents/MacOS"</span>
<span class="type">QQmlImportDatabase</span><span class="operator">::</span>addToImport <span class="number">0x106237370</span> <span class="string">"."</span> <span class="operator">-</span><span class="number">1.</span><span class="operator">-</span><span class="number">1</span> File as <span class="string">""</span>
<span class="type">QQmlImportDatabase</span><span class="operator">::</span>addToImport <span class="number">0x106237370</span> <span class="string">"Qt"</span> <span class="number">4.7</span> Library as <span class="string">""</span>
<span class="type">QQmlImportDatabase</span><span class="operator">::</span>resolveType <span class="string">"Rectangle"</span> <span class="operator">=</span> <span class="string">"QDeclarativeRectangle"</span></pre>
<a name="debugging-with-qt-creator"></a>
<h2>Debugging with Qt Creator</h2>
<p><a href="http://qt-project.org/doc/qtcreator">Qt Creator</a> provides built-in support for QML debugging. QML projects and standalone C++ applications that utilize QML can be debugged on desktops as well as on remote devices. For more information, see the Qt Creator Manual.</p>
</div>
<!-- @@@qtquick-debugging.html -->
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
