/usr/share/qt5/doc/qtdoc/qtquick-debugging.html is in qt5-doc-html 5.9.5-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- debugging.qdoc -->
<title>Debugging QML Applications | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td >Debugging QML Applications</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.5 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<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="#qml-debugging-infrastructure">QML Debugging Infrastructure</a></li>
<li class="level2"><a href="#enabling-the-infrastructure">Enabling the Infrastructure</a></li>
<li class="level2"><a href="#starting-applications">Starting Applications</a></li>
<li class="level2"><a href="#connecting-to-applications">Connecting to Applications</a></li>
<li class="level1"><a href="#debugging-with-qt-creator">Debugging with Qt Creator</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></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 id="console-api">Console API</h2>
<a name="log"></a>
<h3 >Log</h3>
<p><code>console.log</code>, 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 <a href="../qtcore/qloggingcategory.html#qCDebug">qCDebug</a>, <a href="../qtcore/qloggingcategory.html#qCWarning">qCWarning</a>, <a href="../qtcore/qloggingcategory.html#qCCritical">qCCritical</a> methods in C++, with a category of "qml" or "js", depending on the type of file doing the logging. See also <a href="debug.html">Debugging Techniques</a>.</p>
<a name="assert"></a>
<h3 >Assert</h3>
<p><code>console.assert</code> 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><code>console.time</code> 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><code>console.trace</code> 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><code>console.count</code> 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 <code>f called: 1</code>, <code>f called: 2</code> ... whenever <code>f()</code> is executed.</p>
<a name="profile"></a>
<h3 >Profile</h3>
<p><code>console.profile</code> turns on the QML and JavaScript profilers. Nested calls are not supported and a warning will be printed to the console.</p>
<p><code>console.profileEnd</code> 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><code>console.exception</code> 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 id="debugging-module-imports">Debugging Module Imports</h2>
<p>The <code>QML_IMPORT_TRACE</code> 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.3
<span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></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 <code>QML_IMPORT_TRACE=1</code> 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"><a href="../qtqml/qqmlimportdatabase.html">QQmlImportDatabase</a></span><span class="operator">::</span>addImportPath <span class="string">"/qt-sdk/imports"</span>
<span class="type"><a href="../qtqml/qqmlimportdatabase.html">QQmlImportDatabase</a></span><span class="operator">::</span>addImportPath <span class="string">"/qt-sdk/bin/QMLViewer.app/Contents/MacOS"</span>
<span class="type"><a href="../qtqml/qqmlimportdatabase.html">QQmlImportDatabase</a></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"><a href="../qtqml/qqmlimportdatabase.html">QQmlImportDatabase</a></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"><a href="../qtqml/qqmlimportdatabase.html">QQmlImportDatabase</a></span><span class="operator">::</span>resolveType <span class="string">"Rectangle"</span> <span class="operator">=</span> <span class="string">"QDeclarativeRectangle"</span>
</pre>
<a name="qml-debugging-infrastructure"></a>
<h2 id="qml-debugging-infrastructure">QML Debugging Infrastructure</h2>
<p>The <a href="../qtqml/qtqml-index.html">Qt QML</a> module provides services for debugging, inspecting, and profiling applications via a TCP port.</p>
<a name="enabling-the-infrastructure"></a>
<h3 >Enabling the Infrastructure</h3>
<p>You have to explicitly enable the debugging infrastructure when compiling your application. If you use qmake, you can add the configuration parameters to the project .pro file:</p>
<ul>
<li>Qt Quick 1: <code>CONFIG+=declarative_debug</code></li>
<li>Qt Quick 2: <code>CONFIG+=qml_debug</code></li>
</ul>
<p>If you use some other build system, you can pass the following defines to the compiler:</p>
<ul>
<li>Qt Quick 1: <code>QT_DECLARATIVE_DEBUG</code></li>
<li>Qt Quick 2: <code>QT_QML_DEBUG</code></li>
</ul>
<p><b>Note: </b>Enabling the debugging infrastructure might compromise the integrity of the 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:</p><p><code>QML debugging is enabled. Only use this in a safe environment.</code></p>
<a name="starting-applications"></a>
<h3 >Starting Applications</h3>
<p>Start the application with the following arguments:</p>
<p><code>-qmljsdebugger=port:<port_from>[,port_to][,host:<ip address>][,block]</code></p>
<p>Where <code>port_from</code> (mandatory) specifies either the debugging port or the start port of a range of ports when <code>port_to</code> is specified, <code>ip address</code> (optional) specifies the IP address of the host where the application is running, and <code>block</code> (optional) prevents the application from running until the debug client connects to the server. This enables debugging from the start.</p>
<p>After the application has successfully started, it displays the following message:</p>
<p><code>QML Debugger: Waiting for connection on port <port_number></code></p>
<a name="connecting-to-applications"></a>
<h3 >Connecting to Applications</h3>
<p>When the application is running, an IDE or a tool that implements the binary protocol can connect to the open port.</p>
<p>Qt provides a <code>qmlprofiler</code> command line tool to capture profiling data in a file. To run the tool, enter the following command:</p>
<p><code>qmlprofiler -p <port> -attach <ip address></code></p>
<a name="debugging-with-qt-creator"></a>
<h2 id="debugging-with-qt-creator">Debugging with Qt Creator</h2>
<p>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 JS, inspecting the object tree, and profiling the activities of a QML engine. For more information, see <a href="http://doc.qt.io/qtcreator/creator-debugging-qml.html">Qt Creator: Debugging Qt Quick Projects</a>.</p>
</div>
<!-- @@@qtquick-debugging.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> 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.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|