Doc: Describe profiling Qt Quick applicationsHEADdev

...by attaching them to QML Profiler in Qt Creator.

Fixes: QTVSADDINBUG-1320
Change-Id: Ib0e74287a5a2c43f7aad76eb18150009212cf249

Reviewed-by: Miguel Costa <[email protected]>

5 files changed, 73 insertions, 1 deletions

diff --git a/doc/config/qtvstools-project.qdocconf b/doc/config/qtvstools-project.qdocconf
index 9ee521ed..aee833e6 100644
--- a/doc/config/qtvstools-project.qdocconf
+++ b/doc/config/qtvstools-project.qdocconf
@@ -1,4 +1,4 @@
-include(macros.qdocconf)
+include($QT_INSTALL_DOCS/global/macros.qdocconf)
 include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf)
 include($QT_INSTALL_DOCS/global/compat.qdocconf)
 include($QT_INSTALL_DOCS/global/fileextensions.qdocconf)
diff --git a/doc/images/qtcreator-start-qml-profiler.webp b/doc/images/qtcreator-start-qml-profiler.webp
new file mode 100644
index 00000000..dd29b845
--- /dev/null
+++ b/doc/images/qtcreator-start-qml-profiler.webp
diff --git a/doc/images/qtvstools-options-qml-profiling.webp b/doc/images/qtvstools-options-qml-profiling.webp
new file mode 100644
index 00000000..e9b92595
--- /dev/null
+++ b/doc/images/qtvstools-options-qml-profiling.webp
diff --git a/doc/src/externallinks.qdoc b/doc/src/externallinks.qdoc
index 9fd13198..9180f213 100644
--- a/doc/src/externallinks.qdoc
+++ b/doc/src/externallinks.qdoc
@@ -17,11 +17,26 @@
 */
 
 /*!
+\externalpage https://doc.qt.io/qt-6/qtquick-debugging.html#starting-applications
+\title Qt Quick: Starting Applications
+*/
+
+/*!
 \externalpage https://doc.qt.io/qt-6/qtest-overview.html
 \title Qt Test Overview
 */
 
 /*!
+\externalpage https://doc.qt.io/qtcreator/creator-qml-performance-monitor.html
+\title \QC: Profiling QML applications
+*/
+
+/*!
+\externalpage https://doc.qt.io/qtcreator/creator-how-to-profile-qml.html
+\title \QC: Profile QML applications
+*/
+
+/*!
 \externalpage https://learn.microsoft.com/en-us/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file
 \title Configure unit tests by using a .runsettings file
 */
diff --git a/doc/src/qtvstools.qdoc b/doc/src/qtvstools.qdoc
index 17989c3c..d13d1910 100644
--- a/doc/src/qtvstools.qdoc
+++ b/doc/src/qtvstools.qdoc
@@ -112,6 +112,7 @@
                 \li \l {Hide output}
                 \li \l {Load Qt projects}
                 \li \l {Manage resources}
+                \li \l {Profile Qt Quick applications}
                 \li \l {Select Qt versions for a project}
                 \li \l {Set tool theme}
                 \li \l {Start \QD}
@@ -251,6 +252,7 @@
 
     \list
         \li \l {Configure Qt tests using a .runsettings file}
+        \li \l {Profile Qt Quick applications}
     \endlist
 
     \section1 Localize
@@ -2817,3 +2819,58 @@ QTEST_MAIN(QtTest)
         \li In \uicontrol {Auto activate console pane}, select \uicontrol Disable.
     \endlist
 */
+
+/*!
+    \page qtvstools-how-to-profile-qt-quick-apps.html
+    \ingroup qtvstools-how-to
+
+    \title Profile Qt Quick applications
+
+    You can use the QML Profiler integrated into \QC to profile a Qt Quick
+    application that you run from Visual Studio. With QML Profiler, you
+    can find causes for typical performance problems in your applications,
+    such as slowness and unresponsive, stuttering user interfaces.
+
+    One typical cause for such performance problems is executing too much
+    JavaScript in too few frames. All JavaScript must return before the GUI
+    thread can proceed, and frames are delayed or dropped if the GUI thread
+    is not ready. Another typical cause is creating or updating invisible
+    items, which takes time in the GUI thread.
+
+    To profile Qt Quick applications:
+
+    \list 1
+        \li In Visual Studio, open a Qt Quick application project.
+        \li In \uicontrol {Solution Explorer}, right-click the project and
+            select \uicontrol Properties in the context menu.
+        \li Select \uicontrol {Configuration Properties} >
+            \uicontrol {Qt Project Settings}.
+        \li In \uicontrol {Enable QML Debugging}, select \uicontrol {Yes}.
+            \image {qtvstools-quick-addressbook-enable-qml-debugging.webp} {Enabling QML debugging for a project}
+        \li Select \uicontrol {Debugging}.
+        \li In \uicontrol {Command arguments}, enter:
+            \c {-qmljsdebugger=port:<number>,block}
+            \image {qtvstools-options-qml-profiling.webp} {Setting command line arguments for profiling}
+            For more information, see \l {Qt Quick: Starting Applications}.
+            \note The command arguments conflict with the ones set in
+            \uicontrol {Environment} by default, so debugging won't work until
+            you remove them.
+        \li Select \uicontrol {OK}.
+        \li Go to \uicontrol Build, and then select \uicontrol {Build Solution}
+            to build the application.
+        \li Go to \uicontrol Debug, and then select
+            \uicontrol {Start without Debugging} (or press \key {Ctrl+F5})
+            to run the application.
+        \li In \QC, go to \uicontrol {Analyze}, and then select
+            \uicontrol {QML Profiler (Attach to Waiting Application)}.
+            \image {qtcreator-start-qml-profiler.webp} {Qt Creator Start QML Profiler dialog}
+        \li In \uicontrol {Port}, set the same port number as in the command
+            arguments.
+        \li Select \uicontrol {OK} to start profiling.
+        \li If profiling does not start immediately in \uicontrol {QML Profiler},
+            select \uicontrol {Enable Profiling} to start collecting data.
+    \endlist
+
+    \sa {Enable QML debugging}, {\QC: Profile QML applications},
+    {\QC: Profiling QML applications}
+*/