diff options
Diffstat (limited to 'doc/qtcreator')
185 files changed, 3829 insertions, 3501 deletions
diff --git a/doc/qtcreator/config/style/qt5-sidebar.html b/doc/qtcreator/config/style/qt5-sidebar.html index 509808af11..e7671b2b25 100644 --- a/doc/qtcreator/config/style/qt5-sidebar.html +++ b/doc/qtcreator/config/style/qt5-sidebar.html @@ -13,12 +13,8 @@ <li><a href="creator-getting-started.html">Getting Started</a></li> <li><a href="creator-project-creating.html">Creating Projects</a></li> <li><a href="creator-configuring-projects.html">Configuring Projects</a></li> - <li><a href="creator-live-preview.html">Validating with Target Hardware</a></li> - <li><a href="creator-connecting-mobile.html">Connecting Devices</a></li> - <li><a href="creator-deployment.html">Deploying to Devices</a></li> <li><a href="creator-debugging.html">Debugging</a></li> <li><a href="creator-analyze-mode.html">Analyzing Code</a></li> - <li><a href="creator-squish.html">Using Squish</a></li> </ul> </div> </div> @@ -51,6 +47,7 @@ <li><a href="creator-how-tos.html#create-models-and-diagrams">Create Models and Diagrams</a></li> <li><a href="creator-how-tos.html#debug">Debug</a></li> <li><a href="creator-how-tos.html#design-uis">Design UIs</a></li> + <li><a href="creator-how-tos.html#develop-for-devices">Develop for Devices</a></li> <li><a href="creator-how-tos.html#edit-code">Edit Code</a></li> <li><a href="creator-how-tos.html#manage-kits">Manage Kits</a></li> <li><a href="creator-how-tos.html#manage-projects">Manage Projects</a></li> @@ -74,12 +71,15 @@ <li><a href="creator-keyboard-shortcuts.html">Keyboard Shortcuts</a></li> <li><a href="creator-known-issues.html">Known Issues</a></li> <li><a href="technical-support.html">Technical Support</a></li> + <li><a href="creator-version-control.html">Version Control Systems</a></li> + <li><a href="creator-reference.html#analyzers">Analyzers</a></li> <li><a href="creator-reference.html#build-systems">Build Systems</a></li> - <li><a href="creator-reference.html#Editors">Editors</a></li> + <li><a href="creator-reference.html#debuggers">Debuggers</a></li> + <li><a href="creator-reference.html#devices">Devices</a></li> + <li><a href="creator-reference.html#editors">Editors</a></li> <li><a href="creator-reference.html#platforms">Platforms</a></li> <li><a href="creator-reference.html#preferences">Preferences</a></li> <li><a href="creator-reference.html#ui-design">UI Design</a></li> - <li><a href="creator-version-control.html">Version Control Systems</a></li> <li><a href="creator-reference.html#views">Views</a></li> <li><a href="creator-reference.html">See All</a></li> </ul> diff --git a/doc/qtcreator/images/numbers/01.png b/doc/qtcreator/images/numbers/01.png Binary files differindex 4c8b10b26c..1190a99cc6 100644 --- a/doc/qtcreator/images/numbers/01.png +++ b/doc/qtcreator/images/numbers/01.png diff --git a/doc/qtcreator/images/numbers/02.png b/doc/qtcreator/images/numbers/02.png Binary files differindex df24ef459e..9ae3bae02c 100644 --- a/doc/qtcreator/images/numbers/02.png +++ b/doc/qtcreator/images/numbers/02.png diff --git a/doc/qtcreator/images/numbers/03.png b/doc/qtcreator/images/numbers/03.png Binary files differindex 525bd92699..9d29cb93ff 100644 --- a/doc/qtcreator/images/numbers/03.png +++ b/doc/qtcreator/images/numbers/03.png diff --git a/doc/qtcreator/images/numbers/04.png b/doc/qtcreator/images/numbers/04.png Binary files differindex 6c6b489d5c..206e929462 100644 --- a/doc/qtcreator/images/numbers/04.png +++ b/doc/qtcreator/images/numbers/04.png diff --git a/doc/qtcreator/images/numbers/05.png b/doc/qtcreator/images/numbers/05.png Binary files differindex 6d831b204d..6baa13123d 100644 --- a/doc/qtcreator/images/numbers/05.png +++ b/doc/qtcreator/images/numbers/05.png diff --git a/doc/qtcreator/images/numbers/06.png b/doc/qtcreator/images/numbers/06.png Binary files differindex b7adb30f96..4f398dc263 100644 --- a/doc/qtcreator/images/numbers/06.png +++ b/doc/qtcreator/images/numbers/06.png diff --git a/doc/qtcreator/images/numbers/07.png b/doc/qtcreator/images/numbers/07.png Binary files differindex a160038f0e..c71842702f 100644 --- a/doc/qtcreator/images/numbers/07.png +++ b/doc/qtcreator/images/numbers/07.png diff --git a/doc/qtcreator/images/numbers/08.png b/doc/qtcreator/images/numbers/08.png Binary files differindex 6ccf88b7eb..f0d894c106 100644 --- a/doc/qtcreator/images/numbers/08.png +++ b/doc/qtcreator/images/numbers/08.png diff --git a/doc/qtcreator/images/numbers/09.png b/doc/qtcreator/images/numbers/09.png Binary files differindex 0ed195b154..0bf3bc7fb1 100644 --- a/doc/qtcreator/images/numbers/09.png +++ b/doc/qtcreator/images/numbers/09.png diff --git a/doc/qtcreator/images/numbers/10.png b/doc/qtcreator/images/numbers/10.png Binary files differindex 8c468d9998..bec47399a8 100644 --- a/doc/qtcreator/images/numbers/10.png +++ b/doc/qtcreator/images/numbers/10.png diff --git a/doc/qtcreator/images/qtcreator-configure-project.webp b/doc/qtcreator/images/qtcreator-configure-project.webp Binary files differnew file mode 100644 index 0000000000..6f77d3a2a9 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-configure-project.webp diff --git a/doc/qtcreator/images/qtcreator-custom-wizard.png b/doc/qtcreator/images/qtcreator-custom-wizard.png Binary files differdeleted file mode 100644 index 73d3b417b8..0000000000 --- a/doc/qtcreator/images/qtcreator-custom-wizard.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-custom-wizard.webp b/doc/qtcreator/images/qtcreator-custom-wizard.webp Binary files differnew file mode 100644 index 0000000000..6e0f5ddc71 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-custom-wizard.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-threads.webp b/doc/qtcreator/images/qtcreator-debugger-threads.webp Binary files differindex 1a84d6ae2b..155c178155 100644 --- a/doc/qtcreator/images/qtcreator-debugger-threads.webp +++ b/doc/qtcreator/images/qtcreator-debugger-threads.webp diff --git a/doc/qtcreator/images/qtcreator-devices-qnx.webp b/doc/qtcreator/images/qtcreator-devices-qnx.webp Binary files differnew file mode 100644 index 0000000000..a431e883b2 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-devices-qnx.webp diff --git a/doc/qtcreator/images/qtcreator-edit-cmake-configuration-self-built-qt.webp b/doc/qtcreator/images/qtcreator-edit-cmake-configuration-self-built-qt.webp Binary files differnew file mode 100644 index 0000000000..820461039e --- /dev/null +++ b/doc/qtcreator/images/qtcreator-edit-cmake-configuration-self-built-qt.webp diff --git a/doc/qtcreator/images/qtcreator-editor-open-files.webp b/doc/qtcreator/images/qtcreator-editor-open-files.webp Binary files differindex 3ec7e58ae9..f01cf7c52d 100644 --- a/doc/qtcreator/images/qtcreator-editor-open-files.webp +++ b/doc/qtcreator/images/qtcreator-editor-open-files.webp diff --git a/doc/qtcreator/images/qtcreator-editor-symbols.webp b/doc/qtcreator/images/qtcreator-editor-symbols.webp Binary files differindex 70bcc2b442..a42455aab8 100644 --- a/doc/qtcreator/images/qtcreator-editor-symbols.webp +++ b/doc/qtcreator/images/qtcreator-editor-symbols.webp diff --git a/doc/qtcreator/images/qtcreator-filesystem-view-design.png b/doc/qtcreator/images/qtcreator-filesystem-view-design.png Binary files differdeleted file mode 100644 index da8766a9c2..0000000000 --- a/doc/qtcreator/images/qtcreator-filesystem-view-design.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-filesystem-view-design.webp b/doc/qtcreator/images/qtcreator-filesystem-view-design.webp Binary files differnew file mode 100644 index 0000000000..9d5995e416 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-filesystem-view-design.webp diff --git a/doc/qtcreator/images/qtcreator-filesystem-view.webp b/doc/qtcreator/images/qtcreator-filesystem-view.webp Binary files differindex 957a0e4b1b..f16a8060c4 100644 --- a/doc/qtcreator/images/qtcreator-filesystem-view.webp +++ b/doc/qtcreator/images/qtcreator-filesystem-view.webp diff --git a/doc/qtcreator/images/qtcreator-heob-in-terminal.webp b/doc/qtcreator/images/qtcreator-heob-in-terminal.webp Binary files differnew file mode 100644 index 0000000000..f36ac70144 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-heob-in-terminal.webp diff --git a/doc/qtcreator/images/qtcreator-heob.png b/doc/qtcreator/images/qtcreator-heob.png Binary files differdeleted file mode 100644 index c3b75ec847..0000000000 --- a/doc/qtcreator/images/qtcreator-heob.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-ios-preferences.png b/doc/qtcreator/images/qtcreator-ios-preferences.png Binary files differdeleted file mode 100644 index 935a528d6c..0000000000 --- a/doc/qtcreator/images/qtcreator-ios-preferences.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-kit-selector-devices.webp b/doc/qtcreator/images/qtcreator-kit-selector-devices.webp Binary files differnew file mode 100644 index 0000000000..7cb2b74e82 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-kit-selector-devices.webp diff --git a/doc/qtcreator/images/qtcreator-live-preview-kit.png b/doc/qtcreator/images/qtcreator-live-preview-kit.png Binary files differdeleted file mode 100644 index f76099ab82..0000000000 --- a/doc/qtcreator/images/qtcreator-live-preview-kit.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-locator-customize.webp b/doc/qtcreator/images/qtcreator-locator-customize.webp Binary files differindex 5a6d4e90d3..34b96a8d6f 100644 --- a/doc/qtcreator/images/qtcreator-locator-customize.webp +++ b/doc/qtcreator/images/qtcreator-locator-customize.webp diff --git a/doc/qtcreator/images/qtcreator-mcu-kit.png b/doc/qtcreator/images/qtcreator-mcu-kit.png Binary files differdeleted file mode 100644 index c218ad647e..0000000000 --- a/doc/qtcreator/images/qtcreator-mcu-kit.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-mcu-new-project.webp b/doc/qtcreator/images/qtcreator-mcu-new-project.webp Binary files differnew file mode 100644 index 0000000000..270907c08b --- /dev/null +++ b/doc/qtcreator/images/qtcreator-mcu-new-project.webp diff --git a/doc/qtcreator/images/qtcreator-mcu-options.png b/doc/qtcreator/images/qtcreator-mcu-options.png Binary files differdeleted file mode 100644 index a7234466e4..0000000000 --- a/doc/qtcreator/images/qtcreator-mcu-options.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-new-project.webp b/doc/qtcreator/images/qtcreator-new-project.webp Binary files differindex 1c0570b8b6..d073622419 100644 --- a/doc/qtcreator/images/qtcreator-new-project.webp +++ b/doc/qtcreator/images/qtcreator-new-project.webp diff --git a/doc/qtcreator/images/qtcreator-open-project-kits.png b/doc/qtcreator/images/qtcreator-open-project-kits.png Binary files differdeleted file mode 100644 index 8434389fa1..0000000000 --- a/doc/qtcreator/images/qtcreator-open-project-kits.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-options-android-main.png b/doc/qtcreator/images/qtcreator-options-android-main.png Binary files differdeleted file mode 100644 index 5ecea57d99..0000000000 --- a/doc/qtcreator/images/qtcreator-options-android-main.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-options-android-sdk-tools.png b/doc/qtcreator/images/qtcreator-options-android-sdk-tools.png Binary files differdeleted file mode 100644 index f3057ce0bc..0000000000 --- a/doc/qtcreator/images/qtcreator-options-android-sdk-tools.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-preferences-android.webp b/doc/qtcreator/images/qtcreator-preferences-android.webp Binary files differnew file mode 100644 index 0000000000..3c6e909df2 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-android.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp b/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp Binary files differindex c763689496..4826e22fc6 100644 --- a/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp +++ b/doc/qtcreator/images/qtcreator-preferences-build-run-general.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp b/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp Binary files differindex 9ac81bce22..c3c4798c55 100644 --- a/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp +++ b/doc/qtcreator/images/qtcreator-preferences-debugger-gdb.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-kits-mcu.webp b/doc/qtcreator/images/qtcreator-preferences-kits-mcu.webp Binary files differnew file mode 100644 index 0000000000..cf61f131ec --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-kits-mcu.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-mcu.webp b/doc/qtcreator/images/qtcreator-preferences-mcu.webp Binary files differnew file mode 100644 index 0000000000..83d6fd17e0 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-mcu.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-qnx.webp b/doc/qtcreator/images/qtcreator-preferences-qnx.webp Binary files differnew file mode 100644 index 0000000000..435ce04034 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-qnx.webp diff --git a/doc/qtcreator/images/qtcreator-projects-cpp-code-model.webp b/doc/qtcreator/images/qtcreator-projects-cpp-code-model.webp Binary files differnew file mode 100644 index 0000000000..259d8092f3 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-projects-cpp-code-model.webp diff --git a/doc/qtcreator/images/qtcreator-qml-performance-monitor.png b/doc/qtcreator/images/qtcreator-qml-performance-monitor.png Binary files differdeleted file mode 100644 index 2f256ce3d6..0000000000 --- a/doc/qtcreator/images/qtcreator-qml-performance-monitor.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-qml-profiler-toolbar.webp b/doc/qtcreator/images/qtcreator-qml-profiler-toolbar.webp Binary files differnew file mode 100644 index 0000000000..b0b7ba4d7c --- /dev/null +++ b/doc/qtcreator/images/qtcreator-qml-profiler-toolbar.webp diff --git a/doc/qtcreator/images/qtcreator-qml-profiler.webp b/doc/qtcreator/images/qtcreator-qml-profiler.webp Binary files differnew file mode 100644 index 0000000000..281c7c94e6 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-qml-profiler.webp diff --git a/doc/qtcreator/images/qtcreator-scxml-editor.webp b/doc/qtcreator/images/qtcreator-scxml-editor.webp Binary files differindex d57a50dfb7..f78f7ff3d3 100644 --- a/doc/qtcreator/images/qtcreator-scxml-editor.webp +++ b/doc/qtcreator/images/qtcreator-scxml-editor.webp diff --git a/doc/qtcreator/images/qtcreator-sidebar.png b/doc/qtcreator/images/qtcreator-sidebar.png Binary files differdeleted file mode 100644 index 47d4e5e1f8..0000000000 --- a/doc/qtcreator/images/qtcreator-sidebar.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-sidebar.webp b/doc/qtcreator/images/qtcreator-sidebar.webp Binary files differnew file mode 100644 index 0000000000..fdf8640025 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-sidebar.webp diff --git a/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp b/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp Binary files differindex c8438ae002..d4170d4bc1 100644 --- a/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp +++ b/doc/qtcreator/images/qtcreator-toggle-progress-bar.webp diff --git a/doc/qtcreator/images/qtcreator-valgrind-memcheck.png b/doc/qtcreator/images/qtcreator-valgrind-memcheck.png Binary files differdeleted file mode 100644 index 8131846ef5..0000000000 --- a/doc/qtcreator/images/qtcreator-valgrind-memcheck.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-valgrind-memcheck.webp b/doc/qtcreator/images/qtcreator-valgrind-memcheck.webp Binary files differnew file mode 100644 index 0000000000..c60fdbb72d --- /dev/null +++ b/doc/qtcreator/images/qtcreator-valgrind-memcheck.webp diff --git a/doc/qtcreator/images/qtcreator-welcome-open-projects.webp b/doc/qtcreator/images/qtcreator-welcome-open-projects.webp Binary files differindex 5281669b40..05af411f2d 100644 --- a/doc/qtcreator/images/qtcreator-welcome-open-projects.webp +++ b/doc/qtcreator/images/qtcreator-welcome-open-projects.webp diff --git a/doc/qtcreator/images/qtcreator-welcome-session.png b/doc/qtcreator/images/qtcreator-welcome-session.png Binary files differdeleted file mode 100644 index 669ec91423..0000000000 --- a/doc/qtcreator/images/qtcreator-welcome-session.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-welcome-session.webp b/doc/qtcreator/images/qtcreator-welcome-session.webp Binary files differnew file mode 100644 index 0000000000..7a67042f1c --- /dev/null +++ b/doc/qtcreator/images/qtcreator-welcome-session.webp diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint1.png b/doc/qtcreator/images/qtquick-example-setting-breakpoint1.png Binary files differdeleted file mode 100644 index 67da2556c7..0000000000 --- a/doc/qtcreator/images/qtquick-example-setting-breakpoint1.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint1.webp b/doc/qtcreator/images/qtquick-example-setting-breakpoint1.webp Binary files differnew file mode 100644 index 0000000000..0962179a6e --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-setting-breakpoint1.webp diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint2.png b/doc/qtcreator/images/qtquick-example-setting-breakpoint2.png Binary files differdeleted file mode 100644 index 788cacaf65..0000000000 --- a/doc/qtcreator/images/qtquick-example-setting-breakpoint2.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint2.webp b/doc/qtcreator/images/qtquick-example-setting-breakpoint2.webp Binary files differnew file mode 100644 index 0000000000..ab4b1c3cdf --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-setting-breakpoint2.webp diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint3.png b/doc/qtcreator/images/qtquick-example-setting-breakpoint3.png Binary files differdeleted file mode 100644 index 5d197ff92c..0000000000 --- a/doc/qtcreator/images/qtquick-example-setting-breakpoint3.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-setting-breakpoint3.webp b/doc/qtcreator/images/qtquick-example-setting-breakpoint3.webp Binary files differnew file mode 100644 index 0000000000..dfee8bc7cc --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-setting-breakpoint3.webp diff --git a/doc/qtcreator/images/qtquick-example-stack.png b/doc/qtcreator/images/qtquick-example-stack.png Binary files differdeleted file mode 100644 index 943b0af3d7..0000000000 --- a/doc/qtcreator/images/qtquick-example-stack.png +++ /dev/null diff --git a/doc/qtcreator/images/qtquick-example-stack.webp b/doc/qtcreator/images/qtquick-example-stack.webp Binary files differnew file mode 100644 index 0000000000..2bf986d004 --- /dev/null +++ b/doc/qtcreator/images/qtquick-example-stack.webp diff --git a/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc b/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc index 77bc417d03..920bd6d390 100644 --- a/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc +++ b/doc/qtcreator/src/analyze/cpu-usage-analyzer.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,136 +8,151 @@ // ********************************************************************** /*! - \previouspage creator-heob.html - \page creator-cpu-usage-analyzer.html - \nextpage creator-cppcheck.html - - \title Analyzing CPU Usage - - \QC is integrated with the Linux Perf tool that can be - used to analyze the CPU and memory usage of an application on embedded - devices and, to a limited extent, on Linux desktop platforms. The - Performance Analyzer uses the Perf tool bundled with the Linux kernel to - take periodic snapshots of the call chain of an application and visualizes - them in a timeline view or as a flame graph. - - \section1 Using the Performance Analyzer + \page creator-how-to-analyze-cpu-usage.html + \previouspage creator-how-tos.html - The Performance Analyzer usually needs to be able to locate debug symbols for - the binaries involved. + \ingroup creator-how-to-analyze - Profile builds produce optimized binaries with separate debug symbols and - should generally be used for profiling. + \title Analyze CPU usage - To manually set up a build configuration that generates separate debug - symbols, edit the project build settings: + With Perf, you can analyze the CPU and memory usage of an application + on Linux desktop and embedded devices. \l{Performance Analyzer} uses the + Perf tool bundled with the Linux kernel to take periodic snapshots of + the call chain of an application and visualizes them in a timeline view + or as a flame graph. - \list 1 - \li To generate debug symbols also for applications compiled in release - mode, select \uicontrol {Projects}, and then select - \uicontrol Enable in the \uicontrol {Separate debug info} field. - - \li Select \uicontrol Yes to recompile the project. + Usually, Performance Analyzer needs debug symbols for the profiled + binaries. Profile builds produce optimized binaries with separate debug + symbols, so use them for profiling. - \endlist + \section1 Collect data - You can start the Performance Analyzer in the following ways: + Start Performance Analyzer in the following ways to collect data: \list - \li Select \uicontrol Analyze > \uicontrol {Performance Analyzer} to + \li Go to \uicontrol Analyze > \uicontrol {Performance Analyzer} to profile the current application. - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png - (\uicontrol Start) button to start the application from the + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + (\uicontrol Start) to start the application from the \uicontrol {Performance Analyzer}. - \inlineimage qtcreator-performance-analyzer-toolbar.png "Performance Analyzer toolbar" + \image qtcreator-performance-analyzer-toolbar.png {Performance Analyzer toolbar} \endlist - \note If data collection does not start automatically, select the + \note If data collection does not start automatically, select \inlineimage icons/recordfill.png - (\uicontrol {Collect profile data}) button. + (\uicontrol {Collect profile data}). When you start analyzing an application, the application is launched, and - the Performance Analyzer immediately begins to collect data. This is indicated - by the time running in the \uicontrol Recorded field. However, as the data + Performance Analyzer immediately begins to collect data. This is indicated + by the time running in \uicontrol Recorded. However, as the data is passed through the Perf tool and an extra helper program bundled with \QC, and both buffer and process it on the fly, data may arrive in \QC - several seconds after it was generated. An estimate for this delay is given - in the \uicontrol {Processing delay} field. + several seconds after it was generated. \uicontrol {Processing delay} shows + an estimate of the delay. - Data is collected until you select the - \uicontrol {Stop collecting profile data} button or terminate the - application. + Data is collected until you select \inlineimage icons/recordfill.png + (\uicontrol {Stop collecting profile data}) or close the application. - Select the \uicontrol {Stop collecting profile data} button to disable the + Select \uicontrol {Stop collecting profile data} to turn off the automatic start of the data collection when an application is launched. - Profile data will still be generated, but \QC will discard it until you + Profile data is still generated, but \QC discards it until you select the button again. - \section1 Profiling Memory Usage on Devices + \section1 Profile memory usage on devices - To create trace points for profiling memory usage on a target device, select - \uicontrol Analyze > \uicontrol {Performance Analyzer Options} > - \uicontrol {Create Memory Trace Points} or select - \inlineimage icons/create-tracepoint.png - on the \uicontrol {Performance Analyzer} toolbar. + To create trace points for profiling memory usage on a target device: - In the \uicontrol {Create Memory Trace Points} dialog, you can modify the + \list + \li Go to \uicontrol Analyze > \uicontrol {Performance Analyzer Options} + > \uicontrol {Create Memory Trace Points}. + \li Select \inlineimage icons/create-tracepoint.png + on the \uicontrol {Performance Analyzer} toolbar. + \endlist + + In the \uicontrol {Create Memory Trace Points} dialog, modify the script to run. - \image qtcreator-performance-analyzer-create-memory-trace-points.png "Create Memory Trace Points dialog" + \image qtcreator-performance-analyzer-create-memory-trace-points.png {Create Memory Trace Points dialog} If you need root privileges to run scripts as root, select the privileges to - use in the \uicontrol {Elevate privileges using} field. + use in \uicontrol {Elevate privileges using}. Select \uicontrol OK to run the script. To add events for the trace points, see \l{Choosing Event Types}. - You can record a memory trace to view usage graphs in the samples rows of + Record a memory trace to view usage graphs in the samples rows of the timeline and to view memory allocations, peaks, and releases in the flame graph. - \section1 Specifying Performance Analyzer Settings + \section1 Generate separate debug info for qmake projects + + To manually set up a build configuration that generates debug symbols also + for applications compiled for release, edit the build settings of a qmake + project: + + \list 1 + \li Go to \uicontrol {Projects} > \uicontrol {Build Settings}. + \li In \uicontrol {Separate debug info}, select \uicontrol Enable. + \li Select \uicontrol Yes to recompile the project. + \endlist + + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Performance Analyzer}, + {Analyzing Code} +*/ + +/*! + \page creator-cpu-usage-analyzer.html + \previouspage creator-reference.html + + \ingroup creator-reference-analyzer + + \title Performance Analyzer + + \brief Analyze the CPU and memory usage of an application on Linux desktop + and embedded devices. + + To set global preferences for Performance Analyzer, go to \preferences > + \uicontrol Analyzer > \uicontrol {CPU Usage}. + + To set preferences for a particular run configuration, go to + \uicontrol Projects > \uicontrol Run, and then select \uicontrol Details + next to \uicontrol {Performance Analyzer Settings}. - To specify global settings for the Performance Analyzer, select - \preferences > \uicontrol Analyzer > - \uicontrol {CPU Usage}. For each run configuration, you can also - use specialized settings. Select \uicontrol Projects > \uicontrol Run, and - then select \uicontrol Details next to - \uicontrol {Performance Analyzer Settings}. + \image qtcreator-performance-analyzer-settings.png {Performance Analyzer Settings} - \image qtcreator-performance-analyzer-settings.png + To edit the settings for the current run configuration, select the + drop down menu next to \inlineimage icons/recordfill.png on the + Performance Analyzer toolbar. - To edit the settings for the current run configuration, you can also select - the dropdown menu next to the \uicontrol {Collect profile data} button. + \image qtcreator-performance-analyzer-toolbar.png {Performance Analyzer toolbar} - \section2 Choosing Event Types + \section1 Choosing Event Types - In the \uicontrol Events table, you can specify which events should trigger - the Performance Analyzer to take a sample. The most common way of analyzing + The events table lists the events that trigger Performance Analyzer to take + a sample. The most common way of analyzing CPU usage involves periodic sampling, driven by hardware performance counters that react to the number of instructions or CPU cycles executed. - Alternatively, a software counter that uses the CPU clock can be chosen. + You can also select a software counter that uses the CPU clock. Select \uicontrol {Add Event} to add events to the table. - In the \uicontrol {Event Type} column, you can choose the general type of + In \uicontrol {Event Type}, select the general type of event to be sampled, most commonly \uicontrol {hardware} or - \uicontrol {software}. In the \uicontrol {Counter} column, you can choose - which specific counter should be used for the sampling. For example, + \uicontrol {software}. In \uicontrol {Counter}, select the counter + for the sampling. For example, \uicontrol {instructions} in the \uicontrol {hardware} group or \uicontrol {cpu-clock} in the \uicontrol {software} group. More specialized sampling, for example by cache misses or cache hits, is - possible. However, support for it depends on specific features of the CPU - involved. For those specialized events, you can give more detailed sampling - instructions in the \uicontrol {Operation} and \uicontrol {Result} columns. - For example, you can choose a \uicontrol {cache} event for + possible. However, support for it depends on specific features of the CPU. + For those specialized events, give more detailed sampling + instructions in \uicontrol {Operation} and \uicontrol {Result}. + For example, select a \uicontrol {cache} event for \uicontrol {L1-dcache} on the \uicontrol {load} operation with a result - of \uicontrol {misses}. That would sample L1-dcache misses on reading. + of \uicontrol {misses} to sample L1-dcache misses on reading. Select \uicontrol {Remove Event} to remove the selected event from the table. @@ -145,29 +160,28 @@ Select \uicontrol {Use Trace Points} to replace the current selection of events with trace points defined on the target device and set the \uicontrol {Sample mode} to \uicontrol {event count} and the - \uicontrol {Sample period} to \c {1}. If the trace points on the target - were defined using the \uicontrol {Create Trace Points} option, the - Performance Analyzer will automatically use them to profile memory usage. + \uicontrol {Sample period} to \c {1}. If \uicontrol {Create Trace Points} + defines the trace points on the target, Performance Analyzer automatically + uses them to profile memory usage. - Select \uicontrol {Reset} to revert the selection of events, as well as the + Select \uicontrol {Reset} to revert the selection of events, as well as \uicontrol {Sample mode} and \uicontrol {Sample period} to the default values. - \section2 Choosing a Sampling Mode and Period + \section1 Choosing a Sampling Mode and Period - In the \uicontrol {Sample mode} and \uicontrol {Sample period} fields, you - can specify how samples are triggered: + In \uicontrol {Sample mode} and \uicontrol {Sample period}, specify how + samples are triggered: \list \li Sampling by \uicontrol {event count} instructs the kernel to take a sample every \c n times one of the chosen events has occurred, - where \c n is specified in the \uicontrol {Sample period} field. + where \c n is set in \uicontrol {Sample period}. \li Sampling by \uicontrol {frequency (Hz)} instructs the kernel to try and take a sample \c n times per second, by automatically adjusting the - sampling period. Specify \c n in the \uicontrol {Sample period} - field. + sampling period. Set \c n in \uicontrol {Sample period}. \endlist @@ -178,15 +192,15 @@ There may be a significant difference between the sampling period you request and the actual result. - In general, if you configure the Performance Analyzer to collect more data + In general, if you configure Performance Analyzer to collect more data than it can transmit over the connection between the target and the host device, the application may get blocked while Perf is trying to send the data, and the processing delay may grow excessively. You should then change - the \uicontrol {Sample period} or the \uicontrol {Stack snapshot size}. + the value of \uicontrol {Sample period} or \uicontrol {Stack snapshot size}. - \section2 Selecting Call Graph Mode + \section1 Selecting Call Graph Mode - In the \uicontrol {Call graph mode} field, you can specify how the + In \uicontrol {Call graph mode}, you can specify how Performance Analyzer recovers call chains from your application: \list @@ -210,32 +224,32 @@ Qt and most system libraries are compiled without frame pointers by default, so the frame pointer mode is only useful with customized systems. - \section2 Setting Stack Snapshot Size + \section1 Setting Stack Snapshot Size - The Performance Analyzer will analyze and \e unwind the stack snapshots - generated by Perf in dwarf mode. Set the size of the stack snapshots in the - \uicontrol {Stack snapshot size} field. Large stack snapshots result in a + Performance Analyzer analyzes and \e unwinds the stack snapshots + generated by Perf in dwarf mode. Set the size of the stack snapshots in + \uicontrol {Stack snapshot size}. Large stack snapshots result in a larger volume of data to be transferred and processed. Small stack snapshots may fail to capture call chains of highly recursive applications or other intense stack usage. - \section2 Adding Command-Line Options for Perf + \section1 Adding Command-Line Options for Perf - You can specify additional command-line options to be passed to Perf when - recording data in the \uicontrol {Additional arguments} field. You may want - to specify \c{--no-delay} or \c{--no-buffering} to reduce the processing + Set additional command-line options to pass to Perf when + recording data in \uicontrol {Additional arguments}. Set \c{--no-delay} + or \c{--no-buffering} to reduce the processing delay. However, those options are not supported by all versions of Perf and Perf may not start if an unsupported option is given. - \section2 Resolving Names for JIT-compiled JavaScript Functions + \section1 Resolving Names for JIT-compiled JavaScript Functions Since version 5.6.0, Qt can generate perf.map files with information about - JavaScript functions. The Performance Analyzer will read them and show the + JavaScript functions. Performance Analyzer will read them and show the function names in the \uicontrol Timeline, \uicontrol Statistics, and \uicontrol {Flame Graph} views. This only works if the process being profiled is running on the host computer, not on the target device. To switch on the generation of perf.map files, add the environment variable - \c QV4_PROFILE_WRITE_PERF_MAP to the \uicontrol {Run Environment} and set + \c QV4_PROFILE_WRITE_PERF_MAP to \uicontrol {Run Environment} and set its value to \c 1. \section1 Analyzing Collected Data @@ -243,36 +257,35 @@ The \uicontrol Timeline view displays a graphical representation of CPU usage per thread and a condensed view of all recorded events. - \image qtcreator-performance-analyzer-timeline.png "Performance Analyzer" + \image qtcreator-performance-analyzer-timeline.png {Performance Analyzer} Each category in the timeline describes a thread in the application. Move the cursor on an event (5) on a row to see how long it takes and which function in the source it represents. To display the information only when - an event is selected, disable the - \uicontrol {View Event Information on Mouseover} button (4). + an event is selected, turn off + \uicontrol {View Event Information on Mouseover} (4). The outline (9) summarizes the period for which data was collected. Drag the zoom range (7) or click the outline to move on the outline. You can - also move between events by selecting the - \uicontrol {Jump to Previous Event} and \uicontrol {Jump to Next Event} - buttons (1). + also move between events by selecting \uicontrol {Jump to Previous Event} + and \uicontrol {Jump to Next Event} (1). - Select the \uicontrol {Show Zoom Slider} button (2) to open a slider that - you can use to set the zoom level. You can also drag the zoom handles (8). + Select \uicontrol {Show Zoom Slider} button (2) to open a slider that + sets the zoom level. You can also drag the zoom handles (8). To reset the default zoom level, right-click the timeline to open the context menu, and select \uicontrol {Reset Zoom}. \section2 Selecting Event Ranges - You can select an event range (6) to view the time it represents or to zoom - into a specific region of the trace. Select the \uicontrol {Select Range} - button (3) to activate the selection tool. Then click in the timeline to + Select an event range (6) to view the time it represents or to zoom + into a specific region of the trace. Select \uicontrol {Select Range} + (3) to activate the selection tool. Then click in the timeline to specify the beginning of the event range. Drag the selection handle to define the end of the range. - You can use event ranges also to measure delays between two subsequent + Use event ranges also to measure delays between two subsequent events. Place a range between the end of the first event and the beginning - of the second event. The \uicontrol Duration field displays the delay + of the second event. \uicontrol Duration shows the delay between the events in milliseconds. To zoom into an event range, double-click it. @@ -294,10 +307,10 @@ events to move the cursor in the code editor to the part of the code the event is associated with. - As the Perf tool only collects periodic samples, the Performance Analyzer + As the Perf tool only collects periodic samples, Performance Analyzer cannot determine the exact time when a function was called or when it returned. You can, however, see exactly when a sample was taken in the - second row of each thread. The Performance Analyzer assumes that if the same + second row of each thread. Performance Analyzer assumes that if the same function is present at the same place in the call chain in multiple consecutive samples, then this represents a single call to the respective function. This is, of course, a simplification. Also, there may be other @@ -369,7 +382,7 @@ taken for a certain function, relative to the same aspect of all samples together. The nesting shows which functions were called by which other ones. - The \uicontrol {Visualize} button lets you choose what aspect to show in the + The \uicontrol {Visualize} button lets you select what aspect to show in the \uicontrol {Flame Graph}. \list @@ -396,7 +409,7 @@ \uicontrol {Releases} modes will only show any data if samples from memory trace points have been recorded. - \section2 Interaction between the views + \section2 Interaction between the Views When you select a stack frame in either of the \uicontrol {Timeline}, \uicontrol {Flame Graph}, or \uicontrol {Statistics} views, information @@ -415,7 +428,7 @@ \image qtcreator-cpu-usage-analyzer-load-perf-trace.png - The Performance Analyzer needs to know the context in which the + Performance Analyzer needs to know the context in which the data was recorded to find the debug symbols. Therefore, you have to specify the kit that the application was built with and the folder where the application executable is located. @@ -423,15 +436,15 @@ The Perf data files are generated by calling \c {perf record}. Make sure to generate call graphs when recording data by starting Perf with the \c {--call-graph} option. Also check that the necessary debug symbols are - available to the Performance Analyzer, either at a standard location + available to Performance Analyzer, either at a standard location (\c /usr/lib/debug or next to the binaries), or as part of the Qt package you are using. - The Performance Analyzer can read Perf data files generated in either frame + Performance Analyzer can read Perf data files generated in either frame pointer or dwarf mode. However, to generate the files correctly, numerous preconditions have to be met. All system images for the - \l{https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html} - {Boot2Qt:Supported Target Devices and Development Hosts} are correctly set + \l{Support Levels for Target Hardware}{supported embedded platforms} + are correctly set up for profiling in the dwarf mode. For other devices, check whether Perf can read back its own data in a sensible way by checking the output of \c {perf report} or \c {perf script} for the recorded Perf data files. @@ -443,15 +456,16 @@ \uicontrol {Performance Analyzer Options}. This format is self-contained, and therefore loading it does not require you to specify the recording environment. You can transfer such trace files to a different computer - without any tool chain or debug symbols and analyze them there. + without any toolchain or debug symbols and analyze them there. \section1 Troubleshooting - The Performance Analyzer might fail to record data for the following reasons: + Performance Analyzer might fail to record data for the following reasons: \list \li Perf events may be globally disabled on your system. - The preconfigured \l Boot2Qt images come with perf events enabled. + The preconfigured \l{\B2Q: Documentation}{\B2Q} images come with Perf + events enabled. For a custom configuration you need to make sure that the file \c {/proc/sys/kernel/perf_event_paranoid} contains a value smaller than \c {2}. For maximum flexibility in recording traces you can @@ -471,16 +485,16 @@ the values of the \uicontrol {Stack snapshot size} or \uicontrol {Sample period} settings. \li Perf may be buffering the data forever, never sending it. Add - \c {--no-delay} or \c {--no-buffering} to the - \uicontrol {Additional arguments} field. + \c {--no-delay} or \c {--no-buffering} to + \uicontrol {Additional arguments}. \li Some versions of Perf will not start recording unless given a - certain minimum sampling frequency. Try with a - \uicontrol {Sample period} value of 1000. + certain minimum sampling frequency. Try setting + \uicontrol {Sample period} to 1000. \li On some devices, in particular various i.MX6 Boards, the hardware performance counters are dysfunctional and the Linux kernel may randomly fail to record data after some time. Perf can use different types of events to trigger samples. You can get a list of available - event types by running \c {perf list} on the device and then choose + event types by running \c {perf list} on the device and then select the respective event types in the settings. The choice of event type affects the performance and stability of the sampling. The \c {cpu-clock} \c {software} event is a safe but relatively slow @@ -489,8 +503,7 @@ reboot the device. The kernel may have disabled important parts of the performance counters system. \li Perf might not be installed. The way to install it depends on your - Linux distribution. For example, you might try the following - commands: + Linux distribution. For example, try the following commands: \list \li On Ubuntu 22.04: @@ -506,5 +519,5 @@ The \l {Application Output} view shows some information even if the Performance Analyzer displays error messages. - \sa {Profiling Function Execution} + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-analyze.qdoc b/doc/qtcreator/src/analyze/creator-analyze.qdoc index f57d97b8c0..e2333cee77 100644 --- a/doc/qtcreator/src/analyze/creator-analyze.qdoc +++ b/doc/qtcreator/src/analyze/creator-analyze.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -17,70 +17,139 @@ To use a code analysis tool, select it in the \uicontrol {Analyze Menu} or in the pull-down menu of the \inlineimage icons/qtcreator-debug-button.png (\uicontrol {Start Debugging of Startup Project}) button. - When you are in the \uicontrol Debug mode, you can switch between tools by - selecting them in the menu on the debugger toolbar. + In the \uicontrol Debug mode, switch between tools by selecting them in the + menu on the debugger toolbar. - You can drag and drop the views in the \uicontrol Debug mode to new + \image qtcreator-performance-analyzer-toolbar.png {Performance Analyzer in Debug mode} + + Drag the views in the \uicontrol Debug mode to new positions on the screen. The size and position of views are saved for future sessions. Select \uicontrol View > \uicontrol Views > \uicontrol {Reset to Default Layout} to reset the views to their original sizes and positions. - You can use the following code analysis tools in the \uicontrol Debug - mode: + \section1 Improving QML Performance + + \QC comes with the \l{Profiling QML Applications}{QML Profiler} for + inspecting binding evaluations and signal handling when running QML code. + This is useful for identifying potential bottlenecks, especially in the + evaluation of bindings. + + \section1 Finding Issues in QML Code + + Run \l{JavaScript and QML Checks}{static checks} on the QML and JavaScript + code in your project to find common problems, similarly to using + \l{http://www.jslint.com}{JSLint}. + + \section1 Finding Issues in C++ Code with Clang Tools + + \QC comes with the following Clang tools for finding problems in C, C++, and + Objective-C source code by using static analysis: \list + \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which + has diagnostics and fixes for typical programming errors, + such as style violations or interface misuse. + \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which + helps Clang understand Qt semantics. It displays Qt-related compiler + warnings, ranging from unnecessary memory allocation to misuse of + API and has refactoring actions for fixing some of the issues. + \endlist - \li \l{Profiling QML Applications}{QML Profiler} + \section1 Finding Issues in C++ Code with Cppcheck - Inspect binding evaluations, signal handling, and - painting operations when running QML code. This is useful for - identifying potential bottlenecks, especially in the evaluation - of bindings. + Install the \l{http://cppcheck.sourceforge.net/}{Cppcheck} static analysis + tool to detect undefined behavior and dangerous coding constructs in + C++ code. Cppcheck analyzes the source code without actually running the + application. - \li \l{Checking Code Coverage}{Coco} + \section1 Checking Code Coverage - Analyze the way an application runs as part of a test suite, for - example, and use the results to make the tests more efficient and - complete. + Install the \l{https://doc.qt.io/coco/}{Coco} code coverage toolchain for + Tcl, QML, C# and C/C++ programs on \macOS, Linux, or Windows to analyze the + way an application runs as part of a test suite, for example. Use the + results to make the tests more efficient and complete. - \li \l{Prevent code erosion}{Axivion} + You can: - Do static code analysis and architecture analysis to detect and - eliminate unnecessary complexity of code. + \list + \li Find untested code sections. + \li Find redundant tests which can then be eliminated. Coco can + identify portions of the source code that are covered by a test. It + can detect whether a new test covers lines in the source code that + the existing tests do not cover. + \li Find dead code by displaying code that is never executed. + \li Calculate the optimum test execution order so as to maximize + test coverage for each run. This is particularly useful for manual + testing. + \li Analyze two separate versions of an application and compare the + differences. This makes it possible to see which tests are affected + by source code modifications and also to get some measure of the + test coverage of a patch or hot fix. + \li Measure the execution time of applications and tests. + \endlist - \li \l{Using Valgrind Code Analysis Tools}{Valgrind Code Analysis Tools} + \section1 Preventing Code Erosion - Detect problems in memory management by using the Memcheck - tool and find cache misses in the code by using the Callgrind tool. + Install \l{https://www.axivion.com/en/products/axivion-suite/}{Axivion Suite} + to protect software from erosion. With static code analysis, + architecture analysis, and code-smells-detection, you can: - \li \l{Clang Tools} + \list + \li Check the source code for potential runtime errors. + \li Use metrics to generate quantitative information about the + internal quality of the source code. + \li Run style checks to achieve compliance with coding guidelines. + \li Detect both duplicates and similar pieces of code in the source code. + \li Recognize cyclical dependencies at different levels. + \li Detect unreachable code. + \endlist - Detect problems in C, C++, and Objective-C programs by - using Clang-Tidy and Clazy. + \section1 Profiling with Valgrind Tools - \li \l{Detecting Memory Leaks with Heob}{Heob} + Install Memcheck and Callgrind from \l{Valgrind's Tool Suite} to detect + memory leaks and profile function execution. - Use the Heob heap observer on Windows to detect buffer - overruns and memory leaks. + You can run the Valgrind tools either \e locally on the development host or + \e remotely on another host. You can use them to analyze both applications + for which you set up a project in \QC and applications for which you do not + have a project. - \li \l{Analyzing CPU Usage}{Performance Analyzer} + Valgrind tools are supported locally only on Linux and \macos. However, + according to Valgrind.org, support on \macos 10.8 and 10.9 is experimental and + mostly broken. You can run the tools on a remote Linux machine or device + from any development host. - Analyze the CPU usage of embedded applications and Linux - desktop applications with the Performance Analyzer that integrates - the Linux Perf tool. + To run the Valgrind tools to analyze an application for which you have a + project, open the project in \QC and select the kit to run the project. The + kit specifies whether the Valgrind tools are run locally or remotely. - \li \l{Analyzing Code with Cppcheck}{Cppcheck} + For more information about analyzing applications for which you do not have + a project, see \l{Run Valgrind tools on external applications}. - Use the experimental Cppcheck plugin to detect undefined - behavior and dangerous coding constructs. + To set preferences for the Valgrind tools, select \preferences > + \uicontrol Analyzer. You can override the general + settings for each project in the \uicontrol {Run Settings} for the project. - \li \l{Visualizing Chrome Trace Events}{Chrome Trace Format Visualizer} + \section1 Detecting Memory Leaks with Heob - Use the Chrome Trace Format (CTF) Visualizer to view - Chrome trace events. This is especially useful when viewing - large trace files that are difficult to visualize using the - built-in trace-viewer (\c{chrome://tracing}). - \endlist + On Windows, install the \l{https://github.com/ssbssa/heob}{Heob} + heap observer to detect buffer overruns and memory leaks. + + \section1 Analyzing CPU Usage + + On Linux, use Perf to analyze the CPU and memory usage of an application + on Linux desktop and embedded devices. + + \l{Performance Analyzer} uses the Perf tool bundled with the Linux kernel to + take periodic snapshots of the call chain of an application and visualizes + them in a timeline view or as a flame graph. + + \section1 Visualizing Chrome Trace Events + + Use the \l{Chrome Trace Format Visualizer} to view Chrome trace events. This + is especially useful when viewing large trace files that are difficult to + visualize using the built-in trace-viewer (\c{chrome://tracing}). + \sa {Analyze}{How To: Analyze}, {Analyzers} */ diff --git a/doc/qtcreator/src/analyze/creator-axivion.qdoc b/doc/qtcreator/src/analyze/creator-axivion.qdoc index ddfbcdf288..53735a9c31 100644 --- a/doc/qtcreator/src/analyze/creator-axivion.qdoc +++ b/doc/qtcreator/src/analyze/creator-axivion.qdoc @@ -9,20 +9,6 @@ \title Prevent code erosion - \l{https://www.axivion.com/en/products/axivion-suite/}{Axivion Suite} is - a tool suite for protecting software from erosion. With static code analysis, - architecture analysis, and code-smells-detection, you can: - - \list - \li Check the source code for potential runtime errors. - \li Use metrics to generate quantitative information about the - internal quality of the source code. - \li Run style checks to achieve compliance with coding guidelines. - \li Detect both duplicates and similar pieces of code in the source code. - \li Recognize cyclical dependencies at different levels. - \li Detect unreachable code. - \endlist - Connect to an Axivion dashboard server from \QC to view results of code analysis. @@ -132,8 +118,9 @@ select the link in the details or in the \uicontrol {Right Path} or \uicontrol {Target Path} column. - \sa {Enable and disable plugins}, {Link projects to Axivion dashboards}, - {Axivion} + \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, + {Link projects to Axivion dashboards}, {Analyzers}, {Axivion}, + {Analyzing Code} */ /*! @@ -153,12 +140,18 @@ To connect to an Axivion dashboard server: - \list 1 - \li Select \uicontrol Edit to create a connection to the Axivion + \list + \li Select \uicontrol Add to add a new connection to an Axivion dashboard server. + \li Select \uicontrol Edit to modify an existing connection to + an Axivion dashboard server. \image qtcreator-edit-dashboard-configuration.webp {Edit Dashboard Configuration dialog} - \li In \uicontrol {Dashboard URL}, enter the URL of the server. - \li In \uicontrol Username, enter the username to access the server. + \list + \li In \uicontrol {Dashboard URL}, enter the URL of the server. + \li In \uicontrol Username, enter the username to access the server. + \endlist + \li Select \uicontrol Remove to remove the current selected connection + to an Axivion dashboard server. \endlist The first time you access the server, you must enter the password that @@ -186,6 +179,8 @@ \li Go to \uicontrol Projects > \uicontrol {Project Settings} > \uicontrol Axivion. \image qtcreator-preferences-axivion-project.webp {Axivion settings in Project Settings} + \li From \uicontrol {Dashboard} select one of the configured Axivion + dashboard configurations. \li Select \uicontrol {Fetch Projects} to list projects from Axivion. \li Select a project, and then select \uicontrol {Link Project} to link to it. diff --git a/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc b/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc index b1b1cd9a8f..be7eda671d 100644 --- a/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc +++ b/doc/qtcreator/src/analyze/creator-clang-static-analyzer.qdoc @@ -15,22 +15,6 @@ \title Analyze code with Clang-Tidy and Clazy - \QC comes with the following Clang tools for finding problems in C, C++, and - Objective-C source code by using static analysis: - - \list - - \li \l{https://clang.llvm.org/extra/clang-tidy/}{Clang-Tidy}, which - has diagnostics and fixes for typical programming errors, - such as style violations or interface misuse. - - \li \l{https://github.com/KDE/clazy/blob/master/README.md}{Clazy}, which - helps Clang understand Qt semantics. It displays Qt related compiler - warnings, ranging from unnecessary memory allocation to misuse of - API and has refactoring actions for fixing some of the issues. - - \endlist - \note The Clang static analyzer checks are a part of Clang-Tidy. To use the checks, you must create a custom configuration for the Clang tools and enable them for Clang-Tidy. @@ -106,7 +90,8 @@ to load diagnostics from \l{https://yaml.org/}{YAML} files that you exported using the \c {-export fixes} option. - \sa {Configure Clang Diagnostics}, {Speficy Clang tools settings}, + \sa {Check code syntax}, {Configure Clang Diagnostics}, + {Analyze}{How To: Analyze}, {Specify Clang tools settings}, {Analyzers}, {Clang Tools} */ @@ -116,7 +101,7 @@ \ingroup creator-how-to-projects-configure - \title Speficy Clang tools settings + \title Specify Clang tools settings To set Clang-Tidy and Clazy checks to run for the current project: @@ -189,7 +174,7 @@ \endlist \sa {Configure Clang diagnostics}, {Analyze code with Clang-Tidy and Clazy}, - {Speficy Clang tools settings} + {Specify Clang tools settings} */ /*! @@ -311,5 +296,5 @@ file into the \uicontrol {Edit Checks as String} field, select additional checks, and copy-paste the contents of the field to the .clang-tidy file. - \sa {Analyze code with Clang-Tidy and Clazy}, {Speficy Clang tools settings}, {Clang Tools} + \sa {Analyze code with Clang-Tidy and Clazy}, {Specify Clang tools settings}, {Clang Tools} */ diff --git a/doc/qtcreator/src/analyze/creator-coco.qdoc b/doc/qtcreator/src/analyze/creator-coco.qdoc index 341db9fc09..4b1337e123 100644 --- a/doc/qtcreator/src/analyze/creator-coco.qdoc +++ b/doc/qtcreator/src/analyze/creator-coco.qdoc @@ -2,72 +2,46 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-qml-performance-monitor.html \page creator-coco.html - \nextpage creator-axivion.html + \previouspage creator-how-tos.html - \title Checking Code Coverage + \ingroup creator-how-to-analyze - \l{https://doc.qt.io/coco/}{Coco} is a complete code coverage tool chain for - Tcl, QML, C# and C/C++ programs, which runs on \macOS, Linux, and Windows. + \title Check code coverage - Coco analyzes the way an application runs, as part of a test suite, - for example. The results enable you to make the tests more efficient and - complete. - - You can: - - \list - \li Find untested code sections. - \li Find redundant tests which can then be eliminated. Coco can - identify portions of the source code that are covered by a test. It - can detect whether a new test covers lines in the source code that - the existing tests do not cover. - \li Find dead code by displaying code that is never executed. - \li Calculate the optimum test execution order so as to maximize - test coverage for each run. This is particularly useful for manual - testing. - \li Analyze two separate versions of an application and compare the - differences. This makes it possible to see which tests are affected - by source code modifications and also to get some measure of the - test coverage of a patch or hot fix. - \li Measure the execution time of applications and tests. - \endlist - - The experimental Coco plugin integrates Coco CoverageBrowser into \QC. - It enables you to analyze the test coverage by loading an instrumentation - database (a .csmes file), which was generated by Coco CoverageScanner. - It is currently supported only on Windows, with Coco version 6.0, - or later. + With Coco CoverageBrowser, you can analyze the test coverage by loading an + instrumentation database (a .csmes file), which was generated by Coco + CoverageScanner. The experimental Coco plugin is currently supported only on + Windows, with Coco version 6.0, or later. To use the plugin, you must download and install Coco. \note Enable the Coco plugin to use it. - \section1 Configuring Coco + \section1 Configure Coco \list 1 - \li Select \uicontrol Analyze > \uicontrol {Squish Coco}. - \image qtcreator-coco.png "Coco CoverageBrowser and CSMes file" + \li Go to \uicontrol Analyze > \uicontrol {Squish Coco}. + \image qtcreator-coco.png {Coco CoverageBrowser and CSMes file} \li In \uicontrol {CoverageBrowser}, enter the path to the Coco coverage browser to use for analyzing a .csmes file. \li In \uicontrol CSMes, select the instrumentation database to load. \li Select \uicontrol Open to start CoverageBrowser. - \li In CoverageBrowser, select \uicontrol File > + \li In CoverageBrowser, go to \uicontrol File > \uicontrol {Load Execution Report} and select the .csexe for the coverage scan. - \image coco-coveragebrowser-load-execution-report.png "Load Execution Report dialog" - \li If you want to reuse the execution report, deselect the - \uicontrol {Delete execution report after loading} check box. + \image coco-coveragebrowser-load-execution-report.png {Load Execution Report dialog} + \li To keep the execution report, clear + \uicontrol {Delete execution report after loading}. \endlist - Open the analyzed files in \QC. The results of the analysis are displayed + Open the analyzed files in \QC. You can see the results of the analysis after the code in \uicontrol Edit mode. You can change the fonts and colors used for different types of results. \section1 Changing Fonts and Colors - To change the default fonts and colors, select \preferences > + To change the default fonts and colors, go to \preferences > \uicontrol {Text Editor} > \uicontrol {Font & Colors}. Create your own color scheme and select new fonts and colors for the following results: @@ -85,5 +59,6 @@ \li Implicit Manual Coverage Validation \endlist - \sa {Enable and disable plugins}, {Font & Colors} + \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, {Analyzers}, + {Font & Colors}, {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-cppcheck.qdoc b/doc/qtcreator/src/analyze/creator-cppcheck.qdoc index e3cc393d70..6f34cd5180 100644 --- a/doc/qtcreator/src/analyze/creator-cppcheck.qdoc +++ b/doc/qtcreator/src/analyze/creator-cppcheck.qdoc @@ -1,58 +1,51 @@ -// Copyright (C) 2020 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-cpu-usage-analyzer.html \page creator-cppcheck.html - \nextpage creator-ctf-visualizer.html + \previouspage creator-how-tos.html - \title Analyzing Code with Cppcheck + \ingroup creator-how-to-analyze - \l{http://cppcheck.sourceforge.net/}{Cppcheck} is a static analysis tool - that detects errors in C++ code. Static analysis is performed on the source - code without actually executing the application. + \title Detect errors in C++ code with Cppcheck - The experimental Cppcheck Diagnostics plugin integrates diagnostics - that are generated by the Cppcheck tool into the C++ editor. - - \note Enable the Cppcheck plugin to use it. + Enable the experimental Cppcheck plugin to view diagnostics that are + generated by the Cppcheck tool in the C++ editor. Cppcheck is automatically run on open files. To select the files to - check in the currently active project, select \uicontrol Analyze > + check in the currently active project, go to \uicontrol Analyze > \uicontrol Cppcheck. - - \section1 Running Cppcheck on Selected Files + \section1 Analyze selected files \list 1 - \li Select \uicontrol Analyze > \uicontrol Cppcheck. - \image qtcreator-cppcheck-run-configuration.png "Cppcheck run configuration" - \li In the \uicontrol Binary field, enter the path to the Cppcheck - executable file. - \li In the \uicontrol Checks group, select the checks to perform. + \li Go to \uicontrol Analyze > \uicontrol Cppcheck. + \image qtcreator-cppcheck-run-configuration.png {Cppcheck run configuration} + \li In uicontrol Binary, enter the path to the Cppcheck executable file. + \li In \uicontrol Checks, select the checks to perform. \note By default, Cppcheck uses multiple threads to perform checks. - Selecting the \uicontrol {Unused functions} option disables the - default behavior. - \li In the \uicontrol {Custom arguments} field, enter additional + Select \uicontrol {Unused functions} to turn off the default + behavior. + \li In \uicontrol {Custom arguments}, enter additional arguments for running Cppcheck. The arguments might be shadowed by automatically generated ones. To avoid possible conflicts in - configuration, select the \uicontrol {Show raw output} check box - to see the final arguments. - \li In the \uicontrol {Ignored file patterns} field, enter a filter + configuration, select \uicontrol {Show raw output} and check the + final arguments. + \li In \uicontrol {Ignored file patterns}, enter a filter for ignoring files that match the pattern (wildcard). You can enter multiple patterns separated by commas. Even though Cppcheck is not run on files that match the patterns, they might be implicitly checked if other files include them. - \li Select the \uicontrol {Inconclusive errors} check box to also - mark possible false positives. - \li Select the \uicontrol {Check all define combinations} check box to - check all define combinations. Enabling this option can significantly + \li Select \uicontrol {Inconclusive errors} to also mark possible false + positives. + \li Select \uicontrol {Check all define combinations} to + check all define combinations. This can significantly slow down analysis, but might help to find more issues. - \li Select the \uicontrol {Add include paths} check box to pass the - current project's include paths to Cppcheck. Enabling this option + \li Select \uicontrol {Add include paths} to pass the + current project's include paths to Cppcheck. This slows down checks on big projects, but can help Cppcheck to find missing includes. - \li Select the \uicontrol {Calculate additional arguments} check box to + \li Select \uicontrol {Calculate additional arguments} to calculate additional arguments based on current project's settings (such as the language used and standard version) and pass them to Cppcheck. @@ -64,8 +57,9 @@ marks or annotations. To specify the settings above for the automatically run checks, - select \preferences > \uicontrol Analyzer + go to \preferences > \uicontrol Analyzer > \uicontrol Cppcheck. - \sa {Enable and disable plugins} + \sa {Enable and disable plugins}, {Analyze}{How To: Analyze}, + {Analyzing Code}, {Analyzers} */ diff --git a/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc b/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc index a2bf118f3f..8f02ee0607 100644 --- a/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc +++ b/doc/qtcreator/src/analyze/creator-ctf-visualizer.qdoc @@ -8,11 +8,14 @@ // ********************************************************************** /*! - \previouspage creator-cppcheck.html \page creator-ctf-visualizer.html - \nextpage creator-autotest.html + \previouspage creator-reference.html - \title Visualizing Chrome Trace Events + \ingroup creator-reference-analyzer + + \title Chrome Trace Format Visualizer + + \brief Visualize Chrome trace events generated in Chrome Trace Format (CTF). You can use \e {full stack tracing} to trace from the top level QML or JavaScript down to the C++ and all the way to the kernel space. This @@ -110,7 +113,7 @@ LTTng is a tracing toolkit for Linux that you can apply on embedded Linux systems to find out how to optimize the startup time of an application. - Since Qt 5.13, Qt has a set of kernel trace points and a tracing + Qt has a set of kernel trace points and a tracing subsystem for custom user space trace points. \section2 Configuring the Kernel @@ -218,4 +221,6 @@ \code ctf2ctf -o trace.json path/to/lttng trace/ \endcode + + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-heob.qdoc b/doc/qtcreator/src/analyze/creator-heob.qdoc index 449d3cc86a..45f2b269ed 100644 --- a/doc/qtcreator/src/analyze/creator-heob.qdoc +++ b/doc/qtcreator/src/analyze/creator-heob.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2020 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,17 +8,15 @@ // ********************************************************************** /*! + \page creator-how-to-use-heob.html \previouspage creator-clang-tools.html - \page creator-heob.html - \nextpage creator-cpu-usage-analyzer.html - \title Detecting Memory Leaks with Heob + \ingroup creator-how-to-analyze - \QC integrates the \l{https://github.com/ssbssa/heob}{Heob} heap observer - for detecting buffer overruns and memory leaks. You must download and - install Heob to run it from \QC. + \title Detect memory leaks with Heob - \image qtcreator-heob-settings.png + On Windows, use the Heob heap observer to detect buffer overruns and memory + leaks. To run Heob on the currently open project: @@ -26,35 +24,48 @@ \li Select \uicontrol Analyze > \uicontrol Heob. + \image qtcreator-heob-settings.png {Heob settings} + \li Select the Heob settings profile to use, or select \uicontrol New to create a new profile. - \li In the \uicontrol {Heob path} field, enter the path to the Heob + \li In \uicontrol {Heob path}, enter the path to the Heob executable. - \li Specify additional settings for running the checks. For more - information about the available options, see - \l{Specifying Heob Settings}. + \li Specify \l{Heob}{settings} for running the checks. \li Select \uicontrol OK to run Heob. \endlist - \QC runs the application, and then it runs Heob in a console window. + \QC runs the application, and then it runs Heob in a terminal. - \image qtcreator-heob.png + \image qtcreator-heob-in-terminal.webp {Heob running in a terminal} Heob raises an access violation on buffer overruns and records stack traces - of the offending instruction and buffer allocation. The results are - displayed when Heob exits normally. + of the offending instruction and buffer allocation. You can see the results + in the \uicontrol Memcheck view after Heob exits normally. + + \image qtcreator-heob-output.png {Results from Heob in the Memcheck view} - \image qtcreator-heob-output.png + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Heob}, {Analyzing Code} +*/ - \section1 Specifying Heob Settings +/*! + \page creator-heob.html + \previouspage creator-reference.html - To specify settings for Heob, select \uicontrol Analyze > \uicontrol Heob. + \ingroup creator-reference-analyzer - In the \uicontrol {Extra arguments} field, enter additional arguments for + \title Heob + + \brief Detect memory leaks with Heob. + + To specify settings for Heob, go to \uicontrol Analyze > \uicontrol Heob. + + \image qtcreator-heob-settings.png {Heob settings} + + In \uicontrol {Extra arguments}, enter additional arguments for running Heob. To list the available arguments in the Heob console, enter \c -H in this field and press \key Enter. @@ -63,19 +74,19 @@ leaks visually in the file and the \c -L1024 option to record leak contents up to 1024 bytes in the file. For example, \c {-oleaks.html -g2 -L1024} - To save the settings profile, select \uicontrol Save. + To save your changes as default settings, select + \inlineimage icons/savefile.png. To remove a customized settings profile, select the profile, and then select \uicontrol Delete. The following sections describe the available options in more detail. - \section2 Recording Results + \section1 Recording Results The results of the checks are displayed in the \uicontrol Memcheck view and - recorded in a file. You can specify the file name in the - \uicontrol {XML output file} field. Heob creates the file in the project - directory. + recorded in a file. Specify the file name in \uicontrol {XML output file}. + Heob creates the file in the project directory. You can use the process identifier (PID) as a variable in the file name. For example, \c leaks-%p.xml. This injects Heob into the child processes, @@ -87,9 +98,9 @@ If you use variables, \QC cannot open the file automatically, but you can open it from the project directory. - \section2 Handling Exceptions + \section1 Handling Exceptions - In the \uicontrol {Handle exceptions} list, select \uicontrol Off to use the + In \uicontrol {Handle exceptions}, select \uicontrol Off to use the standard exception handler and have the debugger automatically attached if the application crashes. This works only if you register \QC is as a post-mortem debugger by selecting \preferences > @@ -105,7 +116,7 @@ crash is displayed. Therefore, this option is mostly useful when using Heob on the console or running it for child processes, as well. - \section2 Raising Exceptions on Errors + \section1 Raising Exceptions on Errors Select the \uicontrol {Raise breakpoint exception on error} check box to display errors when the application runs. @@ -119,9 +130,9 @@ This is mostly useful when used with the \uicontrol {Run with debugger} option, which runs Heob under the debugger. - \section2 Protecting Pages + \section1 Protecting Pages - In the \uicontrol {Page protection} list, select \uicontrol Off to use + In \uicontrol {Page protection}, select \uicontrol Off to use standard memory allocation functions and enable only memory leak detection. Select \uicontrol After to place a protected page at the end of each @@ -135,9 +146,9 @@ useful for \e use-after-free and \e double-free detection. However, the available memory address space can run out fast for 32-bit programs. - \section2 Handling Leak Data + \section1 Handling Leak Data - In the \uicontrol {Leak details} list, determine how to handle the + In \uicontrol {Leak details}, determine how to handle the collected leak data when the process exits. Selecting \uicontrol None means that no leak data is collected. If you activate leak type detection, Heob might need more time to collect the data when the process exits. @@ -163,10 +174,10 @@ block. Select \uicontrol {Detect Leak Types (Show Reachable)} to also record the reachable blocks in the results file. - In the \uicontrol {Minimum leak size} list, select the size of + In \uicontrol {Minimum leak size}, select the size of leaks to detect in bytes. - In the \uicontrol {Control leak recording} list, select \uicontrol Off to + In \uicontrol {Control leak recording}, select \uicontrol Off to record all leaks. You cannot change leak recording while it is running. To start Heob without starting leak recording, select @@ -177,4 +188,7 @@ To start leak recording when Heob starts and still have the option to control the recording, select \uicontrol {On (Start Enabled)}. + + \sa {Detect memory leaks with Heob}, {Analyze}{How To: Analyze}, {Analyzers}, + {Analyzing Code} */ diff --git a/doc/qtcreator/src/analyze/creator-valgrind-overview.qdoc b/doc/qtcreator/src/analyze/creator-valgrind-overview.qdoc deleted file mode 100644 index 61aca06cfd..0000000000 --- a/doc/qtcreator/src/analyze/creator-valgrind-overview.qdoc +++ /dev/null @@ -1,54 +0,0 @@ -// Copyright (C) 2018 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -// ********************************************************************** -// NOTE: the sections are not ordered by their logical order to avoid -// reshuffling the file each time the index order changes (i.e., often). -// Run the fixnavi.pl script to adjust the links to the index order. -// ********************************************************************** - -/*! - \previouspage creator-axivion.html - \page creator-valgrind-overview.html - \nextpage creator-analyzer.html - - \title Using Valgrind Code Analysis Tools - - \QC integrates \l{http://valgrind.org/info/tools.html}{Valgrind code - analysis tools} for detecting memory leaks and - profiling function execution. You must download and install them separately - to use them from \QC. - - You can run the Valgrind tools either \e locally on the development host or - \e remotely on another host. You can use them to analyze both applications - for which you set up a project in \QC and applications for which you do not - have a project. - - Valgrind tools are supported locally only on Linux and \macos. However, - according to Valgrind.org, support on \macos 10.8 and 10.9 is experimental and - mostly broken. You can run the tools on a remote Linux machine or device - from any development host. - - To run the Valgrind tools to analyze an application for which you have a - project, open the project in \QC and select the kit to run the project. The - kit specifies whether the Valgrind tools are run locally or remotely. - - For more information about analyzing applications for which you do not have - a project, see \l{Running Valgrind Tools on External Applications}. - - To set preferences for the Valgrind tools, select \preferences > - \uicontrol Analyzer. You can override the general - settings for each project in the \uicontrol {Run Settings} for the project. - - The following sections describe how to use the Valgrind tools: - - \list - - \li \l{Detecting Memory Leaks with Memcheck} - - \li \l{Profiling Function Execution} - - \endlist - - \sa {Specify Valgrind settings for a project} -*/ diff --git a/doc/qtcreator/src/analyze/creator-valgrind.qdoc b/doc/qtcreator/src/analyze/creator-valgrind.qdoc index 47d4b8c1d6..d044e58119 100644 --- a/doc/qtcreator/src/analyze/creator-valgrind.qdoc +++ b/doc/qtcreator/src/analyze/creator-valgrind.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,92 +8,116 @@ // ********************************************************************** /*! - \previouspage creator-valgrind-overview.html - \page creator-analyzer.html - \nextpage creator-cache-profiler.html + \page creator-how-to-memcheck.html + \previouspage creator-how-tos.html - \title Detecting Memory Leaks with Memcheck + \ingroup creator-how-to-analyze - You can use the Memcheck tool included in the Valgrind tool suite to detect - problems that are related to memory management in applications. You can use + \title Detect memory leaks with Memcheck + + With the Memcheck tool in \l{Valgrind's Tool Suite}, you can detect + problems that are related to memory management in applications. Use the tool together with the GDB debugger. When a problem is detected, the application is interrupted and you can debug it. \note You can install and run Memcheck locally on Linux. You can run - it on a remote host or device from any development machine. On Windows, + it on a remote host or device from any computer. On Windows, you can use the \l{Detecting Memory Leaks with Heob}{Heob} heap observer to receive similar results. After you download and install Valgrind tools, you can use Memcheck from \QC. - To analyze applications: + To detect memory leaks in applications: \list 1 - \li In the \uicontrol Projects mode, select a debug build configuration. + \li Go to the \uicontrol Projects mode, and select a debug build + configuration. - \li Select \uicontrol Debug to open the \uicontrol Debug mode, and then - select \uicontrol Memcheck on the toolbar. + \li In the mode selector, select \uicontrol Debug > \uicontrol Memcheck. - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png "Start button" - button to start the application. + \image qtcreator-valgrind-memcheck.webp {Memcheck view} + + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + to start the application. \li Use the application to analyze it. - \li Select the \inlineimage icons/stop_small.png "Stop button" - button to view the results of the analysis in the - \uicontrol {Analysis} view. + \li Select \inlineimage icons/stop_small.png to view the results of the + analysis in \uicontrol {Memory Issues}. + + \endlist + + \section1 View memory issues + While the application is running, Memcheck does the following: + + \list + \li Checks all reads and writes of memory. + \li Intercepts calls that allocate or free memory or create or + delete memory blocks. \endlist - While the application is running, Memcheck checks all reads and writes of - memory and intercepts calls that allocate or free memory or create or - delete memory blocks. The results are displayed when you stop Memcheck. - Click a line to view where a memory leak - occurred and a stack trace that shows what caused it. + You can see the results when you stop Memcheck. - As an alternative to collecting data, you can select \inlineimage icons/open.png + Select a line to see the place where a memory leak occurred and a stack trace + that shows what caused it. + + As an alternative to collecting data, select \inlineimage icons/open.png to load an external log file in XML format into the \uicontrol Memcheck view. - \image qtcreator-valgrind-memcheck.png "Memcheck view" - Move the mouse on a row to view more information about the function. To move between rows, select \inlineimage icons/prev.png - or \inlineimage icons/next.png - . + or \inlineimage icons/next.png. - To filter the results, select \inlineimage icons/filtericon.png - , and then select the types of issues to display in the view. You + To filter the results, select \inlineimage icons/filtericon.png, and + then select the types of issues to display in the view. You can view and hide definite and possible memory leaks, uninitialized values, invalid calls to \c free(), and external errors. For more information about using Memcheck, see - \l{http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun} - {Interpreting Memcheck's Output} in the Valgrind documentation. + \l{Interpreting Memcheck's Output} in the Valgrind documentation. + + \sa {Analyze}{How To: Analyze}, {Profile function execution}, + {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, {Analyzers}, {Valgrind Callgrind}, + {Valgrind Memcheck}, {Analyzing Code} +*/ + +/*! + \page creator-preferences-memcheck.html + \previouspage creator-reference.html - \section1 Selecting Options for Memory Analysis + \ingroup creator-reference-preferences-analyzer - You can specify analyzer settings either globally for all projects or - separately for each project in the \l{Specifying Run Settings}{run settings} - of the project. + \title Valgrind Memcheck - To specify global settings for Valgrind, select \preferences > - \uicontrol Analyzer. The \uicontrol {Memcheck Memory Analysis Options} - group has Memcheck options. + \brief Set preferences for Valgrind Memcheck. + + Set \l{Valgrind's Tool Suite}{Valgrind} preferences either globally for all + projects or separately for each project in the \l{Specifying Run Settings} + {run settings} of the project. + + To set global preferences for Valgrind, select \preferences > + \uicontrol Analyzer. Set Memcheck preferences in + \uicontrol {Memcheck Memory Analysis Options}. + + \image qtcreator-valgrind-memcheck-options.png {Memory Analysis options} In \uicontrol {Extra Memcheck arguments}, specify additional arguments for launching the executable. + \section1 Setting Stack Trace Length + Stack traces can get quite large and confusing, and therefore, reading them from the bottom up can help. If the stack trace is not big enough or it is too big, select \preferences > \uicontrol Analyzer and define the length of the stack trace in the \uicontrol {Backtrace frame count} field. - \image qtcreator-valgrind-memcheck-options.png "Memory Analysis options" + \section1 Tracking Origins of Uninitialized Memory Memcheck also reports uses of uninitialised values, most commonly with the message \uicontrol {Conditional jump or move depends on uninitialised value(s).} @@ -101,12 +125,14 @@ uninitialized memory} check box is selected by default. You can deselect it to make Memcheck run faster. + \section1 Viewing a Summary + Memcheck searches for memory leaks when the client application finishes. To view the amount of leaks that occurred, select \uicontrol {Summary Only} in the \uicontrol {Check for leaks on finish} field. To also view details of each leak, select \uicontrol Full. - \section2 Showing Reachable and Indirectly Lost Blocks + \section1 Showing Reachable and Indirectly Lost Blocks \e Reachable blocks are blocks that are pointed at by a pointer or chain of pointers and that might have been freed before the application exited. @@ -118,7 +144,7 @@ To have them reported, select the \uicontrol {Show reachable and indirectly lost blocks}. - \section2 Suppressing Errors + \section1 Suppressing Errors Memcheck detects numerous problems in the system libraries, such as the C library, which come pre-installed with your OS. As you cannot easily fix @@ -127,37 +153,40 @@ when the system is built. You can write your own suppression files if parts of your project have - errors you cannot fix and you do not want to be reminded of them. Click + errors you cannot fix and you do not want to be reminded of them. Select \uicontrol Add in the \uicontrol {MemCheck Memory Analysis} dialog to add the suppression files. + For more information about writing suppression files, see - \l{http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress} - {Suppressing Errors} in the Valgrind documentation. + \l{Suppressing Errors} in the Valgrind documentation. + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, {Valgrind Callgrind} */ /*! - \previouspage creator-analyzer.html \page creator-cache-profiler.html - \nextpage creator-running-valgrind-remotely.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-analyze - \title Profiling Function Execution + \title Profile function execution - You can use the Callgrind tool included in the - \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect - problems that are related to executing functions. In addition, you - can load the data files generated by Callgrind into the - \l{https://kcachegrind.github.io/html/Home.html}{KCachegrind} - profile data visualization tool for browsing the performance results. + With the Callgrind tool in \l{Valgrind's Tool Suite}, you can detect problems + that are related to executing functions. Load the data files generated by + Callgrind into the \l{https://kcachegrind.github.io/html/Home.html} + {KCachegrind} profile data visualization tool to browse the performance + results. After you download and install Valgrind tools and KCachegrind, you can use Callgrind and KCachegrind from \QC. \note You can install and run Callgrind and KCachegrind locally on Linux. You can run Callgrind on a remote Linux machine or device from any - development machine. + computer. - \section1 Building Apps for Profiling + \section1 Build apps for profiling Callgrind records the call history of functions that are executed when the application is run. It collects the number of instructions that are @@ -181,28 +210,26 @@ options for GCC are: \c{-g -O2}. It is advisable to use such a setup for Callgrind profiling. - \section1 Collecting Data + \section1 Collect data To analyze applications: \list 1 - \li In the \uicontrol Projects mode, select a release build configuration. + \li Go to the \uicontrol Projects mode, and select a release build + configuration. - \li Select \uicontrol Debug to open the \uicontrol Debug mode, and then - select \uicontrol Callgrind on the toolbar. + \li In the mode selector, select \uicontrol Debug > \uicontrol Callgrind. - \image qtcreator-valgrind-callgrind-toolbar.png "Callgrind view toolbar" + \image qtcreator-valgrind-callgrind-toolbar.png {Callgrind view toolbar} - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png "Start button" - button to start the application. + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + to start the application. \li Use the application to analyze it. - \li Select the \inlineimage icons/stop_small.png "Stop button" - button to view the results of the analysis in the - \uicontrol Functions view. + \li Select \inlineimage icons/stop_small.png to view the results of the + analysis in the \uicontrol Functions view. \endlist @@ -220,7 +247,7 @@ to view the data in KCachegrind. \QC launches KCachegrind and loads the data into it for visualization. - \section1 Viewing Collected Data + \section1 View collected data The results of the analysis are displayed in the \uicontrol Callgrind views. You can detach views and move them around. To revert the changes, select @@ -261,17 +288,31 @@ To remove template parameter lists when displaying function names, select \uicontrol <>. - \section1 Selecting Profiling Options + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, {Valgrind Callgrind}, + {Valgrind Memcheck} +*/ + +/*! + \page creator-preferences-callgrind.html + \previouspage creator-reference.html + + \ingroup creator-reference-preferences-analyzer - You can specify analyzer settings either globally for all projects or - separately for each project in the \l{Specifying Run Settings}{run settings} - of the project. + \title Valgrind Callgrind - To specify global settings for Valgrind, select \preferences > - \uicontrol Analyzer. The \uicontrol {Callgrind Profiling Options} - group has Callgrind options. + \brief Set preferences for Valgrind Callgrind. - \image qtcreator-valgrind-callgrind-options.png "Valgrind options" + Set \l{Valgrind's Tool Suite}{Valgrind} preferences either globally for all + projects or separately for each project in the \l{Specifying Run Settings} + {run settings} of the project. + + To set global preferences for Valgrind, select \preferences > + \uicontrol Analyzer. Set Callgrind preferences in + \uicontrol {Callgrind Profiling Options}. + + \image qtcreator-valgrind-callgrind-options.png {Callgrind Profiling Options} In the \uicontrol {KCachegrind executable} field, enter the path to the KCachegrind executable to launch. @@ -292,7 +333,7 @@ global bus events of the event type \c Ge that are executed, select \uicontrol {Collect global bus events}. - \section2 Enabling Full Cache Simulation + \section1 Enabling Full Cache Simulation By default, only instruction read accesses (Ir) are counted. To fully simulate the cache, select the \uicontrol {Enable cache simulation} check box. @@ -308,7 +349,7 @@ \endlist - \section2 Enabling Branch Prediction Simulation + \section1 Enabling Branch Prediction Simulation To enable the following additional event counters, select the \uicontrol {Enable branch prediction simulation} check box: @@ -323,32 +364,39 @@ \endlist - \sa {Analyzing CPU Usage}, {Detach views} + \sa {Analyzing CPU Usage}, {Detect memory leaks with Memcheck}, + {Detach views}, {Run Valgrind tools on external applications}, + {Specify Valgrind settings for a project}, + {Valgrind Memcheck} */ /*! - \previouspage creator-cache-profiler.html \page creator-running-valgrind-remotely.html - \nextpage creator-clang-tools.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-analyze - \title Running Valgrind Tools on External Applications + \title Run Valgrind tools on external applications - \QC integrates Valgrind code analysis tools for detecting memory - leaks and profiling function execution. + With \l{Valgrind's Tool Suite}, you can detect memory leaks and profile + function execution. To run the Valgrind tools to analyze external applications for which you do not have a \QC project: \list 1 - \li Select \uicontrol Analyze > \uicontrol {Valgrind Memory Analyzer (External + \li Go to \uicontrol Analyze > \uicontrol {Valgrind Memory Analyzer (External Application)} or \uicontrol {Valgrind Function Profiler (External Application)}. - \image qtcreator-valgrind-remote-settings.png "Start Remote Analysis dialog" + \image qtcreator-valgrind-remote-settings.png {Start Remote Analysis dialog} - \li Specify the application to run and analyze, and the \l{glossary-buildandrun-kit}{kit} - to use. + \li Select the application to run and analyze, as well as the + \l{glossary-buildandrun-kit}{kit} to use. \endlist + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Kits}, {Specify Valgrind settings for a project}, {Valgrind Callgrind}, + {Valgrind Memcheck} */ diff --git a/doc/qtcreator/src/android/androiddev.qdoc b/doc/qtcreator/src/android/androiddev.qdoc index c0fe2cedea..ab6ae2d909 100644 --- a/doc/qtcreator/src/android/androiddev.qdoc +++ b/doc/qtcreator/src/android/androiddev.qdoc @@ -3,28 +3,30 @@ /*! \page creator-developing-android.html - \previouspage creator-connecting-mobile.html - \nextpage creator-developing-baremetal.html + \previouspage creator-reference.html - \title Connecting Android Devices + \ingroup creator-reference-devices - You can connect Android devices to the development PC using USB cables to - build, run, debug, and analyze applications from \QC. + \title Developing for Android - To develop for Android, you must install a tool chain for building - applications for Android devices on the development PC. \QC can automatically - download and install the tool chain and create a suitable build and run - \l{glossary-buildandrun-kit}{kit} that has the tool chain and the Qt - version for Android for the device's architecture. + \brief Set up the toolchain for building applications for Android devices. - To enable helpful code editing features for Java, such as code completion, + Install a Qt version targeting Android and the Android SDK and NDK to develop + Qt applications for Android devices. To check the Android version supported + by each Qt version, see the \l {Qt for Android} documentation for the Qt + version. + + To get helpful code editing features for Java, such as code completion, highlighting, function tooltips, and navigating in code, add a \l{Add a Java language server}{Java language server}. \QC integrates the Android Debug Bridge (\c adb) command-line tool for deploying applications to Android devices, running them, and reading their logs. The \c adb tool includes a client and server that run on - the development host and a daemon that runs on the emulator or device. + the computer and a daemon that runs on the Android emulator or device. + + \note \QC only detects a device and connects to it after you + \l{Debug on Android Devices}{enable USB debugging on it}. The following video shows the whole process from installing Qt for Android to debugging an application on an Android device: @@ -33,18 +35,30 @@ \section1 Requirements - To use \QC to develop Qt applications for Android, you need - \l {Qt for Android} and a tool chain that \QC can automatically - download, install, and configure for you. For more information - about the requirements for developing with a particular Qt version, - see the documentation for that Qt version. The links in this manual - lead to the latest released Qt reference documentation. + To use \QC to develop Qt applications for Android, you need: + + \list + \li \l {Qt for Android} + \li \l {Android Development Prerequisites}{Android tools} that \QC can + automatically download, install, and configure for you. + \endlist + + \sa {Android}{How To: Develop for Android} +*/ + +/*! + \page creator-how-to-set-android-preferences.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-android - \section1 Specifying Android Device Settings + \title Set up Android development environment \QC offers to automatically install all the necessary packages and tools and - to set up your development environment by creating debuggers, tool chains, - and kits. You can use \QC to: + to set up your \l{Qt for Android} development environment by creating + debuggers, toolchains, and kits. + + Use \QC to: \list \li Download and extract the Android SDK Command-line Tools. @@ -55,12 +69,12 @@ To set up the development environment for Android: \list 1 - \li Select \preferences > \uicontrol Devices > \uicontrol Android. - \image qtcreator-options-android-main.png {Android preferences} - \li In the \uicontrol {JDK location} field, set the path to the JDK. + \li Go to \preferences > \uicontrol Devices > \uicontrol Android. + \image qtcreator-preferences-android.webp {Android preferences} + \li In \uicontrol {JDK location}, set the path to the JDK. \QC checks the JDK installation and reports errors. - By default, \QC tries to find a supported \l{AdoptOpenJDK} or + By default, \QC tries to find a supported \l{Adoptium OpenJDK} or \l{OpenJDK} installation. If it cannot find one, you must set the path manually. If you have not installed a supported JDK, select \inlineimage icons/online.png @@ -68,46 +82,42 @@ \note Use a 64-bit JDK because the 32-bit one might cause issues with \c cmdline-tools, and some packages might not appear in the list. - \li In the \uicontrol {Android SDK location} field, set the path to the + \li In \uicontrol {Android SDK location}, set the path to the folder to install the \l{Android SDK Command-line Tools}. \li Select \uicontrol {Set Up SDK} to automatically download and extract the Android SDK Command-line Tools to the selected path. - The SDK Manager checks that you have the necessary tools. If you need - more packages or updates, the SDK Manager offers to add or remove + SDK Manager checks that you have the necessary tools. If you need + more packages or updates, SDK Manager offers to add or remove the appropriate packages. Before taking action, it prompts you to accept the changes. In addition, it prompts you to accept Google licenses, as necessary. - \li The \uicontrol {Android NDK list} lists the installed NDK versions. - The SDK Manager installed the locked items. You can modify them only + \li \uicontrol {Android NDK list} lists the installed NDK versions. + SDK Manager installed the locked items. You can modify them only from the \uicontrol {Android SDK Manager} dialog. For more - information, see \l{Managing Android NDK Packages}. - \li Select the \uicontrol {Automatically create kits for Android tool chains} - check box to allow \QC to create the kits for you. \QC displays a + information, see \l{Manage Android NDK Packages}. + \li Select \uicontrol {Automatically create kits for Android tool chains} + to automatically create the necessary kits. \QC displays a warning if it cannot find a suitable Qt version. - \li Optionally, in the \uicontrol {Android OpenSSL Settings} group, set + \li Optionally, in \uicontrol {Android OpenSSL Settings} group, set the path to the prebuilt OpenSSL libraries. - For Qt applications that require OpenSSL support, you can - quickly add the \l {Android OpenSSL support} to your project. - For more information, see \l{Adding External Libraries}. + For Qt applications that require OpenSSL support, add + \l {Android OpenSSL support} to your project, as instructed in + \l{Adding External Libraries}. \li Select \uicontrol {Download OpenSSL} to download the OpenSSL repository to the selected path. If the automatic download fails, the download web page opens for manual download. \endlist - \section2 Manual Setup - - \note Use the latest Android SDK Command-Line Tools. \QC does not support - Android SDK Tools version 25.2.5 or earlier because it cannot fully - integrate them. + \section1 Manual setup - However, if the automatic setup does not meet your needs, you can download + If the automatic setup does not meet your needs, download and install Android SDK Command-line Tools, and then install or update the necessary NDKs, tools, and packages. For more information, see \l{Getting Started with Qt for Android}. - \section2 Viewing Android Tool Chain Settings + \section1 View Android toolchain settings A JSON configuration file defines the Android SDK Command-Line Tools download URL, the essential packages list, and the appropriate NDK for each Qt version. @@ -121,45 +131,73 @@ C:\Users\Username\AppData\Local\QtProject\qtcreator\android\sdk_definitions.json \endcode - For example, the SDK configuration file sets the NDK version 19.2.5345600 - for use with Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1: + For example, the SDK configuration file sets the NDK version 22.1.7171670 + for use with Qt 6.3, Qt 6.2, and Qt 5.15.9 to 5.15.20: \badcode "specific_qt_versions": [ - { - "versions": ["5.12.[0-5]", "5.13.[0-1]"], - "sdk_essential_packages": ["build-tools;28.0.2", "ndk;19.2.5345600"], - "ndk_path": "ndk/19.2.5345600" - } + { "versions": ["6.3", "6.2", "5.15.[9-20]"], + "sdk_essential_packages": ["build-tools;31.0.0", "ndk;22.1.7171670"] + }, ] \endcode You can view the latest version of the configuration file that is up-to-date with the Android SDK and NDK changes, \l{sdk_definitions.json}, in Git. - \section2 Managing Android NDK Packages + \note For Qt 6.5 or later, \QC reads the NDK version that was used for + building Qt from \c modules/Core.json and uses it instead of the version + in \c sdk_definitions.json. + + \sa {Android}{How To: Develop for Android}, + {Developing for Android} +*/ + +/*! + \page creator-how-to-manage-android-ndk.html + \previouspage creator-how-tos.html - To view the installed \l{Android NDK} versions, select \preferences > + \ingroup creator-how-to-android + + \title Manage Android NDK packages + + To view the \l{Android NDK} versions that \QC installed, go to \preferences > \uicontrol Devices > \uicontrol Android. - \image qtcreator-options-android-sdk-tools.png {Android NDK and SDK checks} + \image qtcreator-preferences-android.webp {Android preferences} - The SDK Manager installed the locked items. You can modify them only + SDK Manager installed the locked items. You can modify them only in the \uicontrol {Android SDK Manager} dialog. - For more information, see \l{Managing Android SDK Packages}. + For more information, see \l{Manage Android SDK packages}. + + \section1 Download Android NDKs + + To manually download NDKs, select \inlineimage icons/online.png. - To manually download NDKs, select \inlineimage icons/online.png - . + \section1 Set default NDK To use the selected NDK version for all Qt versions by default, select \uicontrol {Make Default}. + \section1 Add NDK paths + To add custom NDK paths manually to the global list of NDKs, select - \uicontrol Add. This creates custom tool chains and debuggers associated - to that NDK. However, you have to manually create a kit that uses the - custom NDK. For more information, see \l{Add kits}. + \uicontrol Add. This creates custom toolchains and debuggers associated + to that NDK. + + You have to manually create a kit that uses the custom NDK. + + \sa {Add kits}, {Android}{How To: Develop for Android}, + {Developing for Android} +*/ + +/*! + \page creator-how-to-manage-android-sdk.html + \previouspage creator-how-tos.html - \section2 Managing Android SDK Packages + \ingroup creator-how-to-android + + \title Manage Android SDK packages Since Android SDK Tools version 25.3.0, Android has only a command-line tool, \l {sdkmanager}, for SDK package management. To make SDK management @@ -172,66 +210,105 @@ \image qtcreator-android-sdk-manager.webp {Android SDK Manager} - You can show packages for the release channel you select in - \uicontrol {Show Packages} > \uicontrol Channel. Common channel IDs include - \uicontrol Stable, \uicontrol Beta, \uicontrol Dev, and \uicontrol Canary. + \section1 Show SDK packages + + To show packages for a release channel in \uicontrol Package, select the + channel in \uicontrol {Show Packages} > \uicontrol Channel. Common channel + IDs include \uicontrol Stable, \uicontrol Beta, \uicontrol Dev, and + \uicontrol Canary. + To show and update also obsolete packages, select - \uicontrol {Include obsolete}. To filter packages, select - \uicontrol Available, \uicontrol Installed, or \uicontrol All. + \uicontrol {Include obsolete}. + + To filter packages, select \uicontrol Available, \uicontrol Installed, or + \uicontrol All. - To update the installed Android SDK packages, select - \uicontrol {Update Installed}. Select the packages to update, and then - select \uicontrol Apply. + \section1 Update SDK packages - To specify advanced \c sdkmanager settings, select - \uicontrol {Advanced Options} and enter arguments in the - \uicontrol {SDK Manager arguments} field. \uicontrol {Available arguments} - lists the arguments with descriptions. + To update the installed Android SDK packages: + \list 1 + \li Select \uicontrol {Update Installed}. + \li Select the packages to update. + \li Select \uicontrol Apply. + \endlist + + \section1 Set sdkmanager options + + To set advanced \c sdkmanager options: + + \list 1 + \li Select \uicontrol {Advanced Options}. + \li In \uicontrol {SDK Manager arguments}, enter sdkmanager options from + \uicontrol {Available arguments}. \image qtcreator-android-sdk-manager-arguments.png {Android SDK Manager Arguments dialog} + \endlist + + \sa {Android}{How To: Develop for Android}, {Developing for Android} +*/ + +/*! + \page creator-how-to-manage-avd.html + \previouspage creator-how-tos.html - \section1 Managing Android Virtual Devices (AVD) + \ingroup creator-how-to-android - To view the available AVDs, select \preferences > \uicontrol Devices. - You can add more AVDs. + \title Manage AVDs + + To view and add Android Virtual Devices (AVD), go to \preferences > + \uicontrol Devices. \image qtcreator-android-avd-manager.webp {Android device in Devices} - You can see the status of the selected device in \uicontrol {Current state}. + Select an AVD in \uicontrol Device to see its status in + \uicontrol {Current state}. + To update the status information, select \uicontrol Refresh. - To start an AVD, select \uicontrol {Start AVD}. Usually, you don't need to - start AVDs separately because \QC starts them when you - select them in the \l{Build for many platforms}{kit selector} to - \l{Deploying to Android}{deploy applications} to them. + \section1 Start AVDs - To remove an AVD from the list and the kit selector, select - \uicontrol {Erase AVD}. + To start an AVD, select \uicontrol {Start AVD}. Usually, \QC starts an AVD + when you select it in the \l{Build for many platforms}{kit selector} to + \l{Android Deploy Configuration}{deploy applications} to it. + + \section1 Set prefrences for starting AVDs - To specify options for starting an AVD, select \uicontrol {AVD Arguments}. + To set preferences for starting an AVD, select \uicontrol {AVD Arguments}. \image qtcreator-android-avd-arguments.png {Startup options for AVDs} - Specify the options in \uicontrol {Emulator command-line startup options}. + Set the preferences in \uicontrol {Emulator command-line startup options}. For available options, see \l{Start the emulator from the command line}. - \note The Android Emulator has a bug that prevents it from starting on some - systems. If an AVD does not start, you can try starting it manually by - running the following commands: + To start the emulator manually from the terminal, enter: \badcode - cd <ANDROID_SDK>/emulator + cd <ANDROID_SDK_ROOT>/emulator ./emulator -avd <AVD_NAME> \endcode - \section2 Creating a New AVD + \section1 Remove AVDs - To create new virtual devices: + To remove an AVD from the list and the kit selector, select + \uicontrol {Erase AVD}. + + \sa {Android}{How To: Develop for Android}, {Developing for Android} +*/ + +/*! + \page creator-how-to-create-avd.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-android + + \title Create an Android Virtual Device (AVD) + + To create a new Android Virtual Device (AVD): \list 1 - \li Select \preferences > \uicontrol Devices > - \uicontrol Add > \uicontrol {Android Device} to open the - \uicontrol {Create New AVD} dialog. + \li Go to \preferences > \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {Android Device} > + \uicontrol {Start Wizard}. \image qtcreator-android-create-avd.png {Create New AVD dialog} \li Set the name, definition, architecture, target API level, and SD card size of the device. @@ -241,14 +318,21 @@ For more advanced options for creating a new AVD, use the command-line tool \l{avdmanager} or the Android Studio's native AVD Manager UI. - \section1 Debugging on Android Devices + \sa {Android}{How To: Develop for Android}, {Developing for Android} +*/ + +/*! + \page creator-how-to-debug-android.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-android + + \title Debug on Android devices You enable debugging in different ways on different Android devices. - Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}. On - some devices, \uicontrol {Developer Options} is hidden and becomes visible - only when you tap the \uicontrol {Build number} field in \uicontrol Settings - > \uicontrol About several times. For more information, see - \l {Configure on-device developer options}. + Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}. + Tap \uicontrol {Build number} in \uicontrol Settings > \uicontrol About + several times to show \uicontrol {Developer Options}. Select a \l{glossary-build-config}{debug build configuration} to build the application for debugging. @@ -260,4 +344,7 @@ \badcode Ignoring second debugger -accepting and dropping. \endcode + + \sa {Android}{How To: Develop for Android}, {Developing for Android}, + {Configure on-device developer options} */ diff --git a/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc b/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc index 8904f69785..8753e83864 100644 --- a/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc +++ b/doc/qtcreator/src/android/creator-projects-settings-run-android.qdoc @@ -17,7 +17,7 @@ To run and debug an application on an Android device, you must create connections from the development host to the device, as instructed in - \l {Connecting Android Devices}. + \l {Developing for Android}. \section1 am Start Options @@ -66,5 +66,5 @@ \endcode \sa {Activate kits for a project}, {Configure projects for running}, - {Connecting Android Devices} + {Android}{How To: Develop for Android} */ diff --git a/doc/qtcreator/src/android/deploying-android.qdoc b/doc/qtcreator/src/android/deploying-android.qdoc index 2b3441290f..e1b83d5e04 100644 --- a/doc/qtcreator/src/android/deploying-android.qdoc +++ b/doc/qtcreator/src/android/deploying-android.qdoc @@ -2,11 +2,15 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-deployment.html \page creator-deploying-android.html - \nextpage creator-deployment-b2qt.html + \previouspage creator-reference.html - \title Deploying to Android + \ingroup creator-reference-deploy-configurations + + \title Android Deploy Configuration + + \brief Create Application Packages (APK) or Android App Bundles (AAB) to + install and run on devices or to upload to the Google Play store. Android applications are packaged as ZIP files called Application Packages (APK) or Android App Bundles (AAB). You can install and run APK files on a @@ -26,7 +30,7 @@ All Qt versions do not support AABs. Qt 6.3.0 and later support multi-abi builds for applications that you build with CMake. For - more information, see \l{Qt for Android - Building User Projects}. + more information, see \l{Deploying an Application on Android}. \endlist \note Since \QC 4.12, Ministro is not supported. @@ -204,7 +208,8 @@ To add OpenSSL libraries, select \uicontrol {Include prebuilt OpenSSL libraries} in the \uicontrol {Additional Libraries} group. This will add the OpenSSL - include project defined in \l{Specifying Android Device Settings}{device settings} + include project defined in \l{Set up Android development environment} + {device settings} in \uicontrol {Android OpenSSL} group. This can be used for qmake and CMake projects. @@ -492,5 +497,8 @@ \c {android.permission.ACCESS_BACKGROUND_LOCATION} for \l{Qt Positioning}. To add a permission, select it from the list, and then click \uicontrol Add. + + \sa {Build and Run}{How To: Build and Run}, + {Android}{How To: Develop for Android}, {Android Run Settings} */ diff --git a/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc b/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc index a6319a7f2a..af2ffacaae 100644 --- a/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc +++ b/doc/qtcreator/src/appman/creator-appman-how-to-run.qdoc @@ -11,7 +11,7 @@ If you have set up \l{Qt Application Manager}, you can deploy, run, and debug applications on the desktop, remote generic SSH Linux targets, or - \l{Boot2Qt}{Boot2Qt devices}. The applications can be either + \B2Q devices. The applications can be either \e {built-in applications} or \e {third-party applications}. The former are part of the System UI or the base installation, while the latter are dynamically installed, updated, and uninstalled. @@ -118,7 +118,7 @@ \li The path to the controller that installs the application package into the target system. - When you run applications on a Boot2Qt device, you can see the device + When you run applications on a \B2Q device, you can see the device ID here. \row \li \uicontrol {Application ID} @@ -148,7 +148,10 @@ slowness and unresponsive, stuttering user interfaces. You cannot profile an in-process runtime as an individual process. - \sa {Activate kits for a project}, {Connecting Boot2Qt Devices}, - {Connecting Remote Linux Devices}, {Enable and disable plugins}, - {Run on many platforms}, {Debugging}, {Profiling QML Applications} + \sa {Activate kits for a project}, {Enable and disable plugins}, + {\B2Q}{How To: Develop for \B2Q}, + {Remote Linux}{How To: Develop for remote Linux}, + {Run on many platforms}, {Debugging}, {Debuggers}, {Debugger}, + {Developing for \B2Q Devices}, {Developing for Remote Linux Devices}, + {Profiling QML Applications} */ diff --git a/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc b/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc index 96fabb3624..70ded6fc36 100644 --- a/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc +++ b/doc/qtcreator/src/baremetal/creator-baremetal-dev.qdoc @@ -1,24 +1,33 @@ -// Copyright (C) 2020 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-developing-android.html \page creator-developing-baremetal.html - \nextpage creator-developing-b2qt.html + \previouspage creator-reference.html - \title Connecting Bare Metal Devices + \ingroup creator-reference-devices - You can configure build and run kits to use Bare Metal tool chains installed - on the development host to build applications for Bare Metal devices. You - can connect the devices to the development host to run and debug - applications on them from \QC using GDB or a hardware debugger. This enables - you to debug on small devices that are not supported by the generic remote - Linux device plugin. + \title Developing for Bare Metal Devices + + \brief Create kits to use Bare Metal toolchains installed on the computer + to build applications for and run and debug them on connected Bare Metal + devices. + + Run and debug applications on small devices that are not supported + by the remote Linux device plugin by using GDB or a hardware debugger. + + \note Enable the Bare Metal plugin to use it. + + Install Bare Metal toolchains on the computer to build applications for + Bare Metal devices. Connect the devices to the computer to run and debug + applications on them. \note If you use qmake to build the project and the device does not have - Qt libraries, you need a fake Qt installation. + Qt libraries, you need a Qt installation that meets the requirements in + \l{Self-built Qt versions}. In addition, the \c mkspecs directory needs + to be complete enough to parse .pro files. - The following tool chains are supported for building applications: + The following toolchains are supported for building applications: \list \li GCC: Microchip Technology (AVR, AVR32, PIC16, PIC32), @@ -42,227 +51,284 @@ the device preferences. You can specify the commands to execute when connecting using a particular debug server provider. + \section1 Debug Server Providers + The following debug server providers are supported when using GDB: \list - \li \l EBlink - \li \l J-Link - \li \l OpenOCD - \li \l ST-Link + \li \l {Set up EBlink}{EBlink} + \li \l {Set up J-Link}{J-Link} + \li \l {Set up OpenOCD}{OpenOCD} + \li \l {Set up ST-Link}{ST-Link} \endlist ST-Link and J-Link debug server providers can be used together with - the \l {uVision IDE}. - - \note Enable the Bare Metal plugin to use it. - - \section1 Specifying Settings for Debug Server Providers + the \l {Set up the uVision IDE}{uVision IDE}. To create connections to bare metal devices using a debug server provider, - select \preferences > \uicontrol Devices > \uicontrol {Bare Metal} > + go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal} and select \uicontrol Add. The available settings depend on the debug server provider. - \section2 EBlink + \sa {Enable and disable plugins}, {Bare Metal}{How To: Develop for Bare Metal} +*/ + +/*! + \page creator-how-to-eblink.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up EBlink \l{https://github.com/EmBitz/EBlink}{EBlink} is an ARM Cortex-M debug tool that supports squirrel scripting, live variables, and hot-plugging. \image qtcreator-baremetal-eblink.webp {Bare metal device preferences for EBlink} - To specify settings for \EBlink: + To set preferences for \EBlink: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {EBlink} - \li In the \uicontrol {Script file} field, enter the path + \li In \uicontrol {Script file}, enter the path to a device script file. - \li In the \uicontrol {Verbosity level} field, enter the level of + \li In \uicontrol {Verbosity level}, enter the level of verbose logging. - \li Select the \uicontrol {Connect under reset} check box to use - the ST-Link interface. Deselect the check box for hot-plugging. + \li Select \uicontrol {Connect under reset} to use + the ST-Link interface. Clear it for hot-plugging. - \li In the \uicontrol Type field, select the interface type. + \li In \uicontrol Type, select the interface type. - \li In the \uicontrol Speed field, enter the interface speed between + \li In \uicontrol Speed, enter the interface speed between 120 and 8000 kilohertz (kHz). - \li Select the \uicontrol {Disable cache} check box to disable the + \li Select \uicontrol {Disable cache} to disable the \EBlink flash cache. - \li Select the \uicontrol {Auto shutdown} check box to automatically + \li Select \uicontrol {Auto shutdown} to automatically shut down the \EBlink server after disconnecting. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 J-Link + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-jlink.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up J-Link \l{https://www.segger.com/products/debug-probes/j-link/}{J-Link} is a line of debug probes by Segger. - \image qtcreator-baremetal-jlink.webp "Bare metal device preferences for J-Link" + \image qtcreator-baremetal-jlink.webp {Bare metal device preferences for J-Link} - To specify settings for J-Link debug probes: + To set preferences for J-Link debug probes: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {J-Link} - \li In the \uicontrol {Host interface} field, select the connection + \li In \uicontrol {Host interface}, select the connection type, IP or USB, or use the default connection. - \li In the \uicontrol {Target interface} field, select the target - interface type. + \li In \uicontrol {Target interface}, select the target interface type. - \li In the \uicontrol Speed field, enter the interface speed in kHz. + \li In \uicontrol Speed, enter the interface speed in kHz. - \li In the \uicontrol Device field, select the device to connect to. + \li In \uicontrol Device, select the device to connect to. - \li In the \uicontrol {Additional arguments} field, enter - arguments for the commands. + \li In \uicontrol {Additional arguments}, enter arguments for the + commands. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 OpenOCD + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-openocd.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up OpenOCD \l{http://openocd.org}{OpenOCD} (Open On-Chip Debugger) is an on-chip debug solution for targets based on the ARM7 and ARM9 family with Embedded-ICE (JTAG) facility. It enables source level debugging with the GDB compiled for the ARM architecture. - \image qtcreator-baremetal-openocd.webp "Bare metal device preferences for OpenOCD" + \image qtcreator-baremetal-openocd.webp {Bare metal device preferences for OpenOCD} - To specify settings for \OpenOCD: + To set preferences for \OpenOCD: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {OpenOCD} - \li In the \uicontrol {Root scripts directory} field, enter the + \li In \uicontrol {Root scripts directory}, enter the path to the directory that has configuration scripts. - \li In the \uicontrol {Configuration file} field, enter the path + \li In \uicontrol {Configuration file}, enter the path to the device configuration file. - \li In the \uicontrol {Additional arguments} field, enter + \li In \uicontrol {Additional arguments}, enter arguments for the commands. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 St-Link + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-stlink.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up St-Link \l{https://www.st.com/en/development-tools/stm32-programmers.html#products} {ST-LINK Utility} is used for programming STM32 microcontrollers. - \image qtcreator-baremetal-stlink.webp "Bare metal device preferences for St-Link" + \image qtcreator-baremetal-stlink.webp {Bare metal device preferences for St-Link} - To specify settings for St-Link: + To set preferences for St-Link: \list 1 - \include creator-baremetal-settings.qdocinc baremetal-common + \include creator-baremetal-settings.qdocinc {baremetal-common} {St-Link} - \li In the \uicontrol {Verbosity level} field, enter the level of + \li In \uicontrol {Verbosity level}, enter the level of verbose logging. - \li Select the \uicontrol {Extended mode} check box to continue + \li Select \uicontrol {Extended mode} to continue listening for connection requests after the connection is closed. - \li Select the \uicontrol {Reset on connection} check box to + \li Select \uicontrol {Reset on connection} to reset the board when the connection is created. - \li In the \uicontrol Version field, select the transport + \li In \uicontrol Version, select the transport layer type supported by the device. \include creator-baremetal-settings.qdocinc baremetal-init-reset \endlist - \section2 uVision IDE + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-uvision.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Set up the uVision IDE \l{http://www.keil.com/support/man/docs/uv4/uv4_overview.htm}{uVision} is - an IDE for developing applications for embedded devices. Applications can - be debugged by using uVision Simulator or directly on hardware by using + an IDE for developing applications for embedded devices. To debug + applications, use uVision Simulator, or debug directly on hardware by using St-Link and J-Link. - You can view the current state of peripheral registers in the - \uicontrol {Peripheral Registers} view in Debug mode. The view - is hidden by default. + The \uicontrol {Peripheral Registers} view in Debug mode shows the current + state of peripheral registers. The view is hidden by default. - \section3 uVision Simulator + \section1 uVision Simulator - \image qtcreator-baremetal-uvision-simulator.png "Bare metal device preferences for uVision Simulator" + \image qtcreator-baremetal-uvision-simulator.png {Bare metal device preferences for uVision Simulator} - To specify settings for uVision Simulator: + To set preferences for uVision Simulator: \list 1 - \include creator-baremetal-settings.qdocinc uvision-common + \include creator-baremetal-settings.qdocinc {uvision-common} {uVision Simulator} - \li Select the \uicontrol {Limit speed to real-time} check box to limit + \li Select \uicontrol {Limit speed to real-time} to limit the connection speed. \li Select \uicontrol Apply to add the debug server provider. \endlist - \section3 uVision St-Link or JLink Debugger + \section1 uVision St-Link or JLink Debugger - \image qtcreator-baremetal-uvision-st-link.png "Bare metal device preferences for uVision St-Link" + \image qtcreator-baremetal-uvision-st-link.png {Bare metal device preferences for uVision St-Link} - To specify settings for uVision St-Link or JLink Debugger: + To set preferences for uVision St-Link or JLink Debugger: \list 1 - \include creator-baremetal-settings.qdocinc uvision-common + \include creator-baremetal-settings.qdocinc {uvision-common} {uVision St-Link or uVision JLink} - \li In the \uicontrol {Adapter options} field specify the adapter + \li In \uicontrol {Adapter options} specify the adapter interface type and speed in MHz. \li Select \uicontrol Apply to add the debug server provider. \endlist - \section1 Adding Bare Metal Devices + \sa {Bare Metal}{How To: Develop for Bare Metal}, + {Developing for Bare Metal Devices} +*/ + +/*! + \page creator-how-to-add-bare-metal-devices.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-bare-metal + + \title Add Bare Metal devices - \image qtcreator-baremetal-devices.png "Bare Metal device preferences" + Run and debug applications on small devices that are not supported + by the remote Linux device plugin by using GDB or a hardware debugger. To add a bare metal device: \list 1 - \li Select \preferences > \uicontrol Devices - > \uicontrol Add > \uicontrol {Bare Metal Device} > + \li Go to \preferences > \uicontrol Devices. + \image qtcreator-baremetal-devices.png {Bare Metal device preferences} + \li Select \uicontrol Add > \uicontrol {Bare Metal Device} > \uicontrol {Start Wizard}. - \li In the \uicontrol {Debug server provider} field, select a debug + \li In \uicontrol {Debug server provider}, select a debug server provider. \li Select \uicontrol Apply to add the device. \endlist - \section1 Building for and Running on Bare Metal Devices + \section1 Add the device to a kit To add a kit for building applications and running them on bare metal - devices, select \preferences > \uicontrol Kits - > \uicontrol Add. For more information, see \l{Add kits}. + devices, go to \preferences > \uicontrol Kits and select \uicontrol Add. - \image qtcreator-baremetal-kit.png "Kit preferences for Bare Metal" + \image qtcreator-baremetal-kit.png {Kit preferences for Bare Metal} - You can build applications for and run them on bare metal devices - in the same way as for and on the desktop. For more information, see - \l{Build for many platforms} and \l{Run on many platforms}. + Build applications for and run them on bare metal devices + in same way as for and on the desktop. - \sa {Enable and disable plugins} + \sa {Add kits}, {Build for many platforms}, + {Bare Metal}{How To: Develop for Bare Metal}, {Run on many platforms}, + {Developing for Bare Metal Devices} */ diff --git a/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc b/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc index ea35fe9855..a6688da00b 100644 --- a/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc +++ b/doc/qtcreator/src/baremetal/creator-baremetal-settings.qdocinc @@ -1,16 +1,19 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [baremetal-common] - \li In the \uicontrol Name field, enter a name for the connection. - \li In the \uicontrol {Startup mode} field, select the mode to start + \li Go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal}. + \li Select \uicontrol Add. + \li Select \uicontrol {\1}. + \li In \uicontrol Name, enter a name for the connection. + \li In \uicontrol {Startup mode}, select the mode to start the debug server provider in. - \li In the \uicontrol {Peripheral description file} field, specify a path to + \li In \uicontrol {Peripheral description file}, specify a path to a file that describes the peripherals on the device. - \li In the \uicontrol Host field, select the host name and port number + \li In \uicontrol Host, select the host name and port number to connect to the debug server provider. - \li In the \uicontrol {Executable file} field, enter the path to the + \li In \uicontrol {Executable file}, enter the path to the debug server provider executable. //! [baremetal-common] @@ -18,10 +21,10 @@ //! [baremetal-init-reset] - \li In the \uicontrol {Init commands} field, enter the commands - to execute when initializing the connection. - \li In the \uicontrol {Reset commands} field, enter the commands - to execute when resetting the connection. + \li In \uicontrol {Init commands}, enter the commands + to execute when initializing the connection. + \li In \uicontrol {Reset commands}, enter the commands + to execute when resetting the connection. \li Select \uicontrol Apply to add the debug server provider. //! [baremetal-init-reset] @@ -29,14 +32,16 @@ //! [uvision-common] - \li In the \uicontrol Name field, enter a name for the connection. - \li In the \uicontrol Host field, select the host name and port + \li Go to \preferences > \uicontrol Devices > \uicontrol {Bare Metal}. + \li Select \uicontrol Add. + \li Select \uicontrol {\1}. + \li In \uicontrol Name, enter a name for the connection. + \li In \uicontrol Host, select the host name and port number to connect to the debug server provider. - \li In the \uicontrol {Tools file path} field, enter the path to + \li In \uicontrol {Tools file path}, enter the path to the Keil toolset configuration file. - \li In the \uicontrol {Target device} field, select the device to - debug. - \li In the \uicontrol {Target driver} field, select the driver for + \li In \uicontrol {Target device}, select the device to debug. + \li In \uicontrol {Target driver}, select the driver for connecting to the target device. //! [uvision-common] diff --git a/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc b/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc index ac3ffb12a9..538bd7cd9a 100644 --- a/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc +++ b/doc/qtcreator/src/cmake/creator-how-to-debug-cmake-files.qdoc @@ -20,7 +20,7 @@ \list 1 \li In the \uicontrol Edit mode, set breakpoints in a CMake file. - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start CMake Debugging}. \image qtcreator-debugger-cmake.webp {DAP CMake Preset view in the Debug mode} \endlist @@ -28,6 +28,5 @@ When the application stops at a breakpoint, you can examine data in the \uicontrol Debug mode views. - \sa {Debugging},{Examining Data},{Debug Mode Views},{Setting Breakpoints}, - {CMake} + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, {CMake} */ diff --git a/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc b/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc index fc8cdd122c..a0f7b06c25 100644 --- a/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc +++ b/doc/qtcreator/src/cmake/creator-how-to-profile-cmake-code.qdoc @@ -19,5 +19,5 @@ \image qtcreator-cmake-profiler.webp {CMake profiling information in Chrome Trace Format Visualizer} - \sa {CMake}, {Visualizing Chrome Trace Events} + \sa {CMake}, {Chrome Trace Format Visualizer} */ diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc index 6c4b7d8ef0..1cc600123a 100644 --- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc +++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc @@ -49,7 +49,7 @@ \sa {Configure projects for building}, {Configure projects for running}, {Build with CMake}{How To: Build with CMake}, {CMake Build Configuration}, - {Debug CMake project files}, {Deploying to Remote Linux}, {Open projects}, + {Debug CMake project files}, {Remote Linux Deploy Configuration}, {Open projects}, {Use compilation databases} */ diff --git a/doc/qtcreator/src/debugger/creator-debug-views.qdoc b/doc/qtcreator/src/debugger/creator-debug-views.qdoc index 149ac127a8..8880b64218 100644 --- a/doc/qtcreator/src/debugger/creator-debug-views.qdoc +++ b/doc/qtcreator/src/debugger/creator-debug-views.qdoc @@ -6,12 +6,17 @@ \if defined(qtdesignstudio) \previouspage creator-debugging-qml.html \else - \previouspage creator-debug-mode.html + \previouspage creator-reference.html \endif - \nextpage creator-breakpoints-view.html + + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views \title Viewing Call Stack Trace + \brief View the nested function calls leading to the current position as a + call stack trace. + When the application being debugged is interrupted, \QC displays the nested function calls leading to the current position as a call stack trace. This stack trace is built up from call stack frames, each representing a @@ -40,19 +45,27 @@ from the stopped executable and prepends the frames to the C++ frames, should it find any. You can click a frame in the QML stack to open the QML file in the editor. + + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif */ /*! \page creator-breakpoints-view.html - \previouspage creator-stack-view.html \if defined(qtdesignstudio) - \nextpage creator-locals-view.html + \previouspage creator-debugging-qml.html \else - \nextpage creator-threads-view.html + \previouspage creator-reference.html \endif + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views + \title Setting Breakpoints + \brief Set breakpoints to interrupt the application. + You can associate breakpoints with: \list @@ -128,7 +141,27 @@ \image qtcreator-debug-breakpoints.webp {Breakpoints view} - \section1 Adding Breakpoints + \if defined(qtdesignstudio) + For more information, see: + + \generatelist studio-how-to-debug + \else + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif +*/ + +/*! + \page creator-how-to-add-breakpoints.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-how-tos.html + \endif + + \ingroup creator-how-to-debug + \ingroup studio-how-to-debug + + \title Add breakpoints To add breakpoints: @@ -139,7 +172,7 @@ \list \li In the code editor, click the left margin or press \key F9 - (\key F8 on \macos) on a particular line you want the + (\key F8 on \macos) on a particular line where you want the application to stop. \li In the \uicontrol {Breakpoint Preset} view or the @@ -152,13 +185,13 @@ \endlist \endlist - \li In the \uicontrol {Breakpoint type} field, select the location in the + \li In \uicontrol {Breakpoint type}, select the location in the application code where you want the application to stop. \image qtcreator-add-breakpoint.webp {Add Breakpoints} dialog \endlist - Deselect the \uicontrol Enabled check box to make the breakpoint temporarily + Clear \uicontrol Enabled to make the breakpoint temporarily inoperative as if you had deleted it, but keep the information about the breakpoint, so that you can enable it again later. @@ -216,59 +249,37 @@ \endtable \if defined(qtcreator) - \section1 Specifying Breakpoint Settings - - You can specify settings for breakpoints in \preferences > - \uicontrol Debugger. For more information, see \l{Debugger Preferences}. - - \image qtcreator-debugger-general-options.png {General tab in Debugger preferences} - - To use a full absolute path in breakpoints, select the - \uicontrol {Set breakpoints using a full absolute path} check box. - - GDB and CDB enable setting breakpoints on source lines for which no code - was generated. In such situations, the breakpoint is shifted to the next - source code line for which the code was actually generated. To reflect - such temporary changes by moving the breakpoint markers in the source code - editor, select \uicontrol GDB > \uicontrol {Adjust breakpoint locations} - or \uicontrol CDB > \uicontrol {Correct breakpoint location}. - - When using GDB as backend, you can extend the ordinary GDB - breakpoint class by using Python. Select \uicontrol GDB > - \uicontrol {Use pseudo message tracepoints}. - - When using CDB as backend, you can specify that the debugger should break on - specific events, such as C++ exceptions, thread creation or exit, loading or - unloading \l{Viewing Modules}{application modules}, or particular output. - Select the appropriate check boxes in the \uicontrol CDB > - \uicontrol {Break on} group. To disable first-chance break on access - violation exceptions, select the \uicontrol {Ignore first chance access - violations} check box. The second occurrence of an access violation will - break into the debugger. - - You can automatically add breakpoints on some functions to catch error - and warning messages. For more information, see \l{Specifying CDB Settings} - and \l{Specifying GDB Settings}. - - For more information on breakpoints, see - \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints} - {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif +*/ + +/*! + \page creator-how-to-manage-breakpoints.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-how-tos.html \endif - \section1 Moving Breakpoints + \ingroup creator-how-to-debug + \ingroup studio-how-to-debug + + \title Manage breakpoints + + \section1 Move breakpoints To move a breakpoint: \list - \li Drag and drop a breakpoint marker to another line + \li Drag a breakpoint marker to another line in the text editor. \li In the \uicontrol {Breakpoint Preset} view or the \uicontrol Breakpoints view, select \uicontrol {Edit Selected Breakpoints}, and set the - line number in the \uicontrol {Line number} field. + line number in \uicontrol {Line number}. \endlist - \section1 Deleting Breakpoints + \section1 Delete breakpoints To delete breakpoints: @@ -288,9 +299,9 @@ \endlist - \section1 Enabling and Disabling Breakpoints + \section1 Turn breakpoints on and off - To temporarily disable a breakpoint without deleting it and losing associated + To temporarily turn off a breakpoint without deleting it and losing associated data like conditions and commands: \list @@ -316,7 +327,23 @@ Other than data breakpoints retain their enabled or disabled state when the debugged application is restarted. - \section1 Setting Data Breakpoints + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif +*/ + +/*! + \page creator-how-to-set-data-breakpoints.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-how-tos.html + \endif + + \ingroup creator-how-to-debug + \ingroup studio-how-to-debug + + \title Set data breakpoints A \e {data breakpoint} stops the application when data is read or written at the specified address. @@ -328,11 +355,10 @@ \li In the \uicontrol {Breakpoint Preset} or \uicontrol Breakpoints view, select \uicontrol {Add Breakpoint} in the context menu. - \li In the \uicontrol {Breakpoint type} field, select + \li In \uicontrol {Breakpoint type}, select \uicontrol {Break on data access at fixed address}. - \li In the \uicontrol Address field, specify the address of the memory - block. + \li In \uicontrol Address, specify the address of the memory block. \li Select \uicontrol OK. @@ -349,21 +375,25 @@ it manually. \if defined(qtcreator) - \sa {Debug CMake project files} + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} \endif */ /*! \page creator-locals-view.html \if defined(qtdesignstudio) - \previouspage creator-breakpoints-view.html + \previouspage creator-debugging-qml.html \else - \previouspage creator-source-files-view.html + \previouspage creator-reference.html \endif - \nextpage creator-expressions-view.html + + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views \title Local Variables and Function Parameters + \brief Inspect local variables and function parameters. + The \uicontrol {Locals} view consists of the \uicontrol Locals pane and the \uicontrol {Return Value} pane (hidden when empty). @@ -388,18 +418,18 @@ //! [0] \list \li Add and remove expression evaluators - \li Change \l{Changing Value Display format}{value display format} + \li \l{Change value display format} \li Expand and collapse view contents \li Copy view contents or expression values to the clipboard \li Open view contents in an editor \li Open memory editor \li Set data breakpoints - \li Use \l{Using Debugging Helpers}{debugging helpers} + \li Use \l{Debugging Helpers}{debugging helpers} \li Show and hide tooltips in the view when debugging \li Dereference pointers automatically \li Sort members of classes and structs alphabetically \li Use dynamic object type for display - \li Set \l{Debugger Preferences}{debugger preferences} + \li Set debugger preferences \endlist //! [0] \endif @@ -410,19 +440,27 @@ objects will be displayed. Select \uicontrol {Use dynamic object type for display} in the context menu. Keep in mind that choosing the dynamic type might be slower. + + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif */ /*! \page creator-expressions-view.html - \previouspage creator-locals-view.html \if defined(qtdesignstudio) - \nextpage creator-qml-debugging-example.html + \previouspage creator-debugging-qml.html \else - \nextpage creator-registers-view.html + \previouspage creator-reference.html \endif + \ingroup creator-reference-debugger-views + \ingroup studio-debugger-views + \title Evaluating Expressions + \brief Compute values of arithmetic expressions or function calls. + To compute values of arithmetic expressions or function calls, use expression evaluators in the \uicontrol Expressions view. @@ -515,5 +553,7 @@ appears uninitialized, its value is reported as \uicontrol {not in scope}. Not all uninitialized objects, however, can be recognized as such. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} \endif */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc index ccc9e82fd1..964bbaf5e1 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-example.qdoc @@ -95,5 +95,5 @@ (\uicontrol {Step Into}), and \inlineimage icons/debugger_stepout_small.png (\uicontrol {Step Out}). - \sa {Creating a Qt Widget Based Application}, {Debugging} + \sa {Creating a Qt Widget Based Application}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc index 4583460cb4..b3fef5c0e3 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc @@ -3,20 +3,22 @@ /*! \page creator-debugger-preferences.html - \previouspage creator-remote-debugging.html - \nextpage creator-debugging-helpers.html + \previouspage creator-reference.html - \title Debugger Preferences + \ingroup creator-reference-preferences-debugger - To specify settings for managing debugger processes, select \preferences > - \uicontrol Debugger. In the \uicontrol General tab,you can specify settings + \title General + + \brief Customize debug views and map source paths. + + To specify settings for managing debugger processes, go to \preferences > + \uicontrol Debugger. In the \uicontrol General tab, you can specify settings that are common to all debuggers. \image qtcreator-debugger-general-options.png "Debugger General preferences" - You can customize the appearance and behavior of the debug views, - \l{Specifying Breakpoint Settings}{specify settings for breakpoints}, - and map source paths to target paths. + You can customize the appearance and behavior of the debug views and + setting breakpoints, as well as map source paths to target paths. You can view debug output in the \l {Debugger Log} view. However, in some Linux distributions, such as Arch Linux, debug @@ -26,7 +28,39 @@ application, which effectively prevents storing debug output in system logs. - \section1 Mapping Source Paths + \section1 Breakpoints + + To use a full absolute path in breakpoints, select the + \uicontrol {Set breakpoints using a full absolute path} check box. + + GDB and CDB enable setting breakpoints on source lines for which no code + was generated. In such situations, the breakpoint is shifted to the next + source code line for which the code was actually generated. To reflect + such temporary changes by moving the breakpoint markers in the source code + editor, select \uicontrol GDB > \uicontrol {Adjust breakpoint locations} + or \uicontrol CDB > \uicontrol {Correct breakpoint location}. + + When using GDB as backend, you can extend the ordinary GDB + breakpoint class by using Python. Select \uicontrol GDB > + \uicontrol {Use pseudo message tracepoints}. + + When using CDB as backend, you can specify that the debugger should break on + specific events, such as C++ exceptions, thread creation or exit, loading or + unloading \l{Viewing Modules}{application modules}, or particular output. + Select the appropriate check boxes in the \uicontrol CDB > + \uicontrol {Break on} group. To disable first-chance break on access + violation exceptions, select the \uicontrol {Ignore first chance access + violations} check box. The second occurrence of an access violation will + break into the debugger. + + You can automatically add breakpoints on some functions to catch error + and warning messages. For more information, see \l{CDB} and \l{GDB}. + + For more information on breakpoints, see + \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints} + {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation. + + \section1 Source Paths Mapping To enable the debugger to step into the code and display the source code when using a copy of the source tree at a location different from the one @@ -48,52 +82,79 @@ of the source tree on the local machine. \endlist - \section1 Specifying GDB Settings - - To specify settings for managing the GDB process, select \preferences > - \uicontrol Debugger > \uicontrol GDB. - - \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - - To specify a timeout for terminating non-responsive GDB processes, set the - number of seconds to wait in the \uicontrol {GDB timeout} field. The default - value of 20 seconds should be sufficient for most applications, but if - loading big libraries or listing source files takes much longer than - that on slow machines, you should increase the value. - - To compress several steps into one step for less noisy debugging when - stepping into code, select the \uicontrol {Skip known frames when stepping} - check box. For example, the atomic reference counting code is skipped, and - a single \e {Step Into} for a signal emission ends up directly in the slot - connected to it. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - To display a message box as soon as your application receives a signal, such - as SIGSEGV, during debugging, select the \uicontrol {Show a message box when - receiving a signal} check box. +/*! + \page creator-preferences-debugger-gdb.html + \previouspage creator-reference.html - GDB allows setting breakpoints on source lines for which no code was - generated. In such situations, the breakpoint is shifted to the next - source code line for which the code was actually generated. To reflect - such temporary changes by moving the breakpoint markers in the source - code editor, select the \uicontrol {Adjust breakpoint locations} check box. + \ingroup creator-reference-preferences-debugger - To specify whether the dynamic or the static type of objects will be - displayed, select the \uicontrol {Use dynamic object type for display} - check box. Keep in mind that choosing the dynamic type might be slower. + \title GDB - To allow reading the user's default .gdbinit file on debugger startup, - select the \uicontrol {Load .gdbinit file on startup} check box. + \brief Manage the GDB process. - To use the default GDB pretty printers installed in your system - or linked to the libraries your application uses, select the - \uicontrol {Load system GDB pretty printers} check box. + To specify settings for managing the GDB process, go to \preferences > + \uicontrol Debugger > \uicontrol GDB. - By default, GDB shows AT&T style disassembly. To switch to the Intel style, - select the \uicontrol {Use Intel style disassembly} check box. + \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - To have GDB automatically save a copy of its symbol index in a cache - on disk and retrieve it from there when loading the same binary in the - future, select the \uicontrol {Use automatic symbol cache} check box. + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {GDB timeout} + \li The timeout for terminating non-responsive GDB processes in seconds + The default value of 40 seconds should be sufficient for most + applications, but if loading big libraries or listing source files + takes much longer than that on slow machines, increase the value. + \row + \li \uicontrol {Skip known frames when stepping} + \li Compresses several steps into one step for less noisy debugging when + stepping into code. For example, the atomic reference counting code + is skipped, and a single \e {Step Into} for a signal emission ends up + directly in the slot connected to it. + \row + \li \uicontrol {Show a message box when receiving a signal} + \li Shows a message box as soon as your application receives a signal, + such as SIGSEGV, during debugging. + \row + \li \uicontrol {Adjust breakpoint locations} + \li GDB allows setting breakpoints on source lines for which no code was + generated. In such situations, the breakpoint is shifted to the next + source code line for which the code was actually generated. To reflect + such temporary changes by moving the breakpoint markers in the source + code editor, select this checkbox. + \row + \li \uicontrol {Use dynamic object type for display} + \li Whether the dynamic or the static type of objects will be + displayed. Choosing the dynamic type might make debugging slower. + \row + \li \uicontrol {Load .gdbinit file on startup} + \li Reads the user's default .gdbinit file on debugger startup. + \row + \li \uicontrol {Load system GDB pretty printers} + \li Uses the default GDB pretty printers installed on the computer + or linked to the libraries your application uses. + \row + \li \uicontrol {Use Intel style disassembly} + \li Switches from the default AT&T style disassembly to the Intel style. + \row + \li \uicontrol {Use automatic symbol cache} + \li Automatically saves a copy of the GDB symbol index in a cache on disk + and retrieves it from there when loading the same binary in the + future. + \row + \li \uicontrol {Use debug info daemon} + \li Tries to automatically retrieve debug information for system + packages. + \endtable + + \section1 Executing Additional Commands To execute GDB commands after GDB has been started, but before the debugged application is started or attached, and before the debugging helpers are @@ -111,85 +172,134 @@ To execute arbitrary Python scripts, use \c {python execfile('/path/to/script.py')}. - \section2 Extended GDB Settings + \section1 Extended GDB Settings The settings in the \uicontrol Extended group give access to advanced or experimental functions of GDB. Enabling them may negatively impact your debugging experience, so use them with care. - To use asynchronous mode to control the inferior, select the - respective check box. - - To add common paths to locations of debug information, such as - \c {/usr/src/debug}, when starting GDB, select the - \uicontrol {Use common locations for debug information} check box. + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Use asynchronous mode to control the inferior} + \li Execute commands in the background (asynchronous) mode. + GDB immediately opens a command prompt where you can issue + other commands while your program runs. + \row + \li \uicontrol {Use common locations for debug information} + \li Adds common paths to locations of debug information, such as + \c {/usr/src/debug}, when starting GDB. + \row + \li \uicontrol {Stop when qWarning() is called} + \li Adds a breakpoint on each \c qWarning() function. + \row + \li \uicontrol {Stop when qFatal() is called} + \li Adds a breakpoint on each \c qFatal() function. + \row + \li \uicontrol {Stop when abort() is called} + \li Adds a breakpoint on each \c abort() function. + \row + \li \uicontrol {Enable reverse debugging} + \li Enables stepping backwards. This feature is very slow and unstable + on the GDB side. It exhibits unpredictable behavior when steapping + backwards over system calls and is very likely to destroy your + debugging session. + \row + \li\uicontrol {Debug all child processes} + \li Keeps debugging all children after a fork. + \endtable + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - To stop when \c qWarning, \c qFatal, or \c abort is called, select the - respective check box. +/*! + \page creator-preferences-debugger-cdb.html + \previouspage creator-reference.html - To enable stepping backwards, select the \uicontrol {Enable reverse - debugging} check box. This feature is very slow and unstable on the - GDB side. It exhibits unpredictable behavior when going backwards over - system calls and is very likely to destroy your debugging session. + \ingroup creator-reference-preferences-debugger - To keep debugging all children after a fork, select the - \uicontrol {Debug all child processes} check box. + \title CDB - \section1 Specifying CDB Settings + \brief Manage the CDB process. - To specify settings for managing the CDB process, select \preferences > + To specify settings for managing the CDB process, go to \preferences > \uicontrol Debugger > \uicontrol CDB. \image qtcreator-cdb-options.png "CDB preferences" - You can specify additional arguments for starting CDB in the - \uicontrol {Additional arguments} field. - - If a console application does not start up properly in the configured - console and the subsequent attach fails, you can diagnose the issue by - using CDB's native console. Select the \uicontrol {Use CDB console} - check box to override the console set in the Windows system - environment variables. Note that the native console does not - prompt on application exit. - - To automatically add a breakpoint on the \c CrtCbgReport() function, - select the \uicontrol {Stop when CrtCbgReport() is called} check box. - This catches runtime error messages caused by \c assert(), for example. - - In the \uicontrol {Break on} group, specify whether the debugger should - break on C++ exceptions, on thread creation or exit, on loading or - unloading the specified \l{Viewing Modules}{application modules}, or on - the specified output. - - To disable first-chance break on access violation exceptions, select the - \uicontrol {Ignore first chance access violations} check box. - The second occurrence of an access violation will break into the debugger. + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Additional arguments} + \li Additional arguments for starting CDB. + \row + \li \uicontrol {Use CDB console} + \li If a console application does not start up properly in the configured + console and the subsequent attach fails, diagnose the issue by + using CDB's native console. Select this checkbox to override the + console set in the Windows system environment variables. Note that + the native console does not prompt on application exit. + \row + \li \uicontrol {Ignore first chance access violations} + \li Disables first-chance break on access violation exceptions. + The second occurrence of an access violation will break into the + debugger. + \row + \li \uicontrol {Stop when CrtDbgReport() is called} + \li Automatically adds a breakpoint on the \c CrtDbgReport() function to + catch runtime error messages caused by \c assert(), for example. + \row + \li \uicontrol {Correct breakpoint location} + \li CDB enables setting breakpoints in comments or on source lines for + which no code was generated. In such situations, the breakpoint is + shifted to the next source code line for which the code was actually + generated. To reflect such temporary changes by moving the breakpoint + markers in the source code editor, select this checkbox. For more + information, see \l{Setting Breakpoints}. + \row + \li \uicontrol {Use Python dumper} + \li Uses the abstraction layer of Python Dumper classes to create a + description of data items in the \uicontrol Locals and + \uicontrol Expressions views. + For more information, see \l{Debugging Helper Implementation}. + \row + \li \uicontrol {Break on} + \li Whether the debugger should break on C++ exceptions, on thread + creation or exit, on loading or unloading the specified + \l{Viewing Modules}{application modules}, or on the specified output. + \row + \li \uicontrol {Add Exceptions to Issues View} + \li Shows information about first-chance and second-chance exceptions + in \l Issues. + \endtable + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - CDB enables setting breakpoints in comments or on source lines for which - no code was generated. In such situations, the breakpoint is shifted to - the next source code line for which the code was actually generated. To - reflect such temporary changes by moving the breakpoint markers in the - source code editor, select the \uicontrol {Correct breakpoint location} - check box. For more information, see \l{Setting Breakpoints}. +/*! + \page creator-preferences-debugger-cdb-paths.html + \previouspage creator-reference.html - To use the abstraction layer of Python Dumper classes to create a description - of data items in the \uicontrol Locals and \uicontrol Expressions - views, select the \uicontrol {Use Python dumper} check box. - For more information, see \l{Debugging Helper Implementation}. + \ingroup creator-reference-preferences-debugger - To display information about first-chance and second-chance exceptions - in \l Issues, select the check boxes - in the \uicontrol {Add Exceptions to Issues View} group. + \title CDB Paths - \section1 Setting CDB Paths on Windows + \brief Add the Microsoft Symbol Server to the symbol search path of the + debugger. To obtain debugging information for the operating system libraries for debugging Windows applications, add the Microsoft Symbol Server to the symbol search path of the debugger: \list 1 - \li Select \preferences > \uicontrol Debugger > \uicontrol {CDB Paths}. + \li Go to \preferences > \uicontrol Debugger > \uicontrol {CDB Paths}. \image qtcreator-debugger-cdb-paths.png \li In the \uicontrol {Symbol Paths} group, select \uicontrol Insert. \li Select the directory where you want to store the cached information. @@ -204,4 +314,6 @@ To use the Source Server infrastructure for fetching missing source files directly from version control or the web, enter the following string in the \uicontrol {Source Paths} field: \c srv*. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc index 66386d72c0..d2836a9c5f 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc @@ -9,61 +9,22 @@ /*! - \previouspage creator-debugging.html \page creator-debugger-engines.html - \nextpage creator-debugger-operating-modes.html + \previouspage creator-reference.html - \title Setting Up Debugger + \ingroup creator-reference-debugger - The main debugger preferences are associated with the - \l{kits-tab}{kit} you build and run your project with. To - specify the debugger and compiler to use for each kit, select - \preferences > \uicontrol Kits. + \title Supported Native Debuggers - \image qtcreator-kits.png {Kits preferences} - - You need to set up the debugger only if the automatic setup fails because - the native debugger is missing (for example, you must install the CDB - debugger on Windows yourself) or because \QC does not support the installed - version. For example, when your system does not have GDB - installed or the installed version is outdated, and you want to use a locally - installed replacement instead. - - To change the debugger in an automatically detected kit, select - \preferences > \uicontrol Kits > - \uicontrol Clone to create a copy of the kit, and change the - parameters in the cloned kit. Make sure to enable the cloned kit - for your project. - - If the debugger you want to use is not automatically detected, select - \preferences > \uicontrol Kits > - \uicontrol Debuggers > \uicontrol Add to add it. - - \image qtcreator-preferences-kits-debuggers.webp {Debuggers tab in Kits preferences} - - To use the debugging tools for Windows, you must install them. - Optionally, you can set up the Microsoft Symbol Server if you need - symbol information from Microsoft modules that is not found locally. - For more information, see \l{Setting CDB Paths on Windows}. - - To use the Free Software Foundation (FSF) version of GDB on \macos, you - must sign it and modify your kit preferences. - - This section describes the options you have for debugging C++ and Python code - and installing the supported native debuggers. It also - applies to code in other compiled languages such as C, FORTRAN, and Ada. - - For more information about launching the debugger in different modes, see - \l{Debugger Operating Modes}. - - \section1 Supported Native Debugger Versions + \brief Summary of supported debugger versions. \QC supports native debuggers for debugging compiled code. On most supported platforms, you can use the GNU Symbolic Debugger (GDB). - On Microsoft Windows, when using the Microsoft tool chain, you need the + On Microsoft Windows, when using the Microsoft toolchain, you need the Microsoft Console Debugger (CDB). On \macos and Linux, you can use the LLDB - debugger. On all supported platforms, you can use PDB to debug Python source - code. + debugger. + + On all supported platforms, you can use PDB to debug Python source code. \note You need a debugger version built with Python scripting support. @@ -85,7 +46,7 @@ \row \li \macos \li GCC, Clang - \li LLDB, FSF GDB (experimental) + \li LLDB \row \li Windows/\MinGW \li GCC @@ -96,7 +57,12 @@ \li Debugging Tools for Windows/CDB \endtable - \section2 Supported GDB Versions + The debugger plugin automatically selects a suitable native debugger for + each \l{kits-tab}{kit} from the ones found on the computer. The automatic + setup fails if the native debugger is not installed on the computer or + if \QC does not support the installed version. + + \section1 GDB Versions Use GDB 7.5, or later, with the Python scripting extension and Python version 3.5, or later. @@ -104,49 +70,6 @@ For remote debugging using GDB and GDB server, the minimum supported version of GDB server on the target \l{glossary-device}{device} is 7.0. - \section2 Supported CDB Versions - - \QC supports all versions of CDB targeting platforms that Qt supports. - - \section2 Supported LLDB Versions - - The LLDB native debugger has similar functionality to the GDB debugger. LLDB - is the default debugger in Xcode on \macos for C++ on the desktop. - LLDB is typically used with the Clang compiler (even though you can use it - with GCC, too). - - On \macos you can use the LLDB version delivered with Xcode or build from source. - The minimum supported version is LLDB 320.4. You need a LLDB version built - with Python support. - - On Linux, the minimum supported version is LLDB 3.8. - - \section2 GDB Run Modes - - The GDB native debugger used internally by the debugger plugin runs in - different modes to cope with the variety of supported platforms and - environments: - - \list - - \li Plain mode debugs locally started processes that do not need console input. - - \li Terminal mode debugs locally started processes that need a console. - - \li Attach mode debugs local processes started outside \QC. - - \li Core mode debugs core files generated from crashes. - - \li Remote mode interacts with the GDB server running on Linux. - - \endlist - - \section1 Installing Native Debuggers - - The following sections describe installing native debuggers. - - \section2 GDB - On Windows, use the Python-enabled GDB version that is bundled with the Qt package or comes with recent versions of \MinGW. On most Linux distributions, the GDB builds shipped with the system @@ -157,7 +80,9 @@ Builds of GDB shipped with Xcode on \macos are no longer supported. - \section2 Debugging Tools for Windows + \section1 Debugging Tools for Windows + + \QC supports all versions of CDB targeting platforms that Qt supports. To use the CDB debugger, install the \e {Debugging Tools for Windows} when you install \QC either by using \QOI (in \uicontrol Qt @@ -180,12 +105,12 @@ the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}. - \section2 Debugging Tools for \macos + \section1 Debugging Tools for \macos The Qt binary distribution has both debug and release variants of the libraries. However, you have to explicitly tell the runtime linker that you want to use the debug libraries even if - your application is compiled as debug, as release is the default + your application is compiled as \e debug because \e release is the default library. If you use a qmake based project in \QC, you can set a flag in @@ -196,88 +121,32 @@ For more detailed information about debugging on \macos, see: \l{http://developer.apple.com/library/mac/#technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391} {Mac OS X Debugging Magic}. + \section1 LLDB Versions + + The LLDB native debugger has similar functionality to the GDB debugger. LLDB + is the default debugger in Xcode on \macos for C++ on the desktop. + LLDB is typically used with the Clang compiler (even though you can use it + with GCC, too). - \section2 LLDB + On \macos you can use the LLDB version delivered with Xcode or build from source. + The minimum supported version is LLDB 320.4. You need a LLDB version built + with Python support. We recommend using the LLDB version that is delivered with the latest Xcode. - \section2 PDB + On Linux, the minimum supported version is LLDB 3.8. + + \section1 PDB Versions \l{https://docs.python.org/3/library/pdb.html}{PDB} is a source code debugger for Python applications. You can use it to debug projects that have a \l {Creating a Qt for Python Application with Qt Widgets}{.pyproject} configuration file. - You must install Python and set the interpreter to use in \uicontrol Projects - > \uicontrol Run: + Install Python and set the interpreter to use in \uicontrol Projects + > \uicontrol Run. \image qtcreator-run-settings-python.webp {Run settings for a Python project} - Start debugging the \c main.py file. If you encounter problems, check the - active build target in the kit selector. - - \QC does not support mixed-mode debugging, but you can attach GDB to the - Python interpreter to debug the C++ implementation of the corresponding - Python code. For more information, see - \l{https://doc.qt.io/qtforpython-6/tutorials/debugging/qtcreator/qtcreator.html} - {Debugging PySide with Qt Creator (Linux)}. - - \section1 Setting up FSF GDB for \macos - - To use FSF GDB on \macos, you must sign it and add it to the \QC - \l{glossary-buildandrun-kit}{kits}. - - \list 1 - - \li To create a key for signing FSF GDB, select - \uicontrol {Keychain Access} > \uicontrol {Certificate Assistant} > - \uicontrol {Create a Certificate}: - - \list 1 - - \li In the \uicontrol Name field, input \uicontrol fsfgdb to - replace the existing content. - - \li In the \uicontrol {Certificate Type} field, select - \uicontrol {Code Signing}. - - \li Select the \uicontrol {Let me override defaults} check box. - - \li Select \uicontrol Continue, and follow the instructions of the - wizard (use the default settings), until the - \uicontrol {Specify a Location For The Certificate} dialog - opens. - - \li In the \uicontrol Keychain field, select \uicontrol System. - - \li Select \uicontrol {Keychain Access} > \uicontrol System, and - locate the certificate. - - \li Double click the certificate to view certificate information. - - \li In the \uicontrol Trust section, select - \uicontrol {Always Trust} in the - \uicontrol {When using this certificate} field, and then close - the dialog. - - \endlist - - \li To sign the binary, enter the following command in the terminal: - - \code - codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb - \endcode - - \li In \QC, select \uicontrol {\QC} > \uicontrol Preferences > - \uicontrol Kits > \uicontrol Add to - create a kit that uses FSF GDB. - - \li In the \uicontrol Debugger field, specify the path to FSF GDB - (\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for - \c $HOME). - - \li To use the debugger, enable the kit in the \uicontrol {Build Settings} - of the project. - - \endlist + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc index d3441ab063..eee91df904 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc @@ -26,94 +26,202 @@ \li Debug Python source code - PDB. \endlist - The following sections describe how to set up, launch, and interact with the - debugger: + \section1 Setting Up the Debugger - \list + The debugger plugin automatically selects a suitable native debugger for + each \l{kits-tab}{kit} from the ones found on your system. You can select + another kit. To specify the debugger and compiler to use for each kit, go to + \preferences > \uicontrol Kits. - \li \l{Setting Up Debugger} + \image qtcreator-kits.png {Kits preferences} - The debugger plugin automatically selects a suitable - native debugger for each \l{glossary-buildandrun-kit}{kit} from the - ones found on your system. You can edit the kits to override this - choice. + You need to set up the debugger only if the automatic setup fails because + the native debugger is missing (for example, you must install the CDB + debugger on Windows yourself) or because \QC does not support the installed + version. For example, when your system does not have GDB + installed or the installed version is outdated, and you want to use a locally + installed replacement instead. - \li \l{Launching the Debugger} + To change the debugger in an automatically detected kit, go to + \preferences > \uicontrol Kits > + \uicontrol Clone to create a copy of the kit, and change the + parameters in the cloned kit. Make sure to enable the cloned kit + for your project. - To start an application from an open project under the control - of a debugger, select the \inlineimage icons/qtcreator-debug-button.png - (\uicontrol {Start Debugging of Startup Project}) button or press - \key F5. Other, less common start options are available in the - \uicontrol Debug > \uicontrol {Start Debugging} menu. + If the debugger you want to use is not automatically detected, go to + \preferences > \uicontrol Kits > + \uicontrol Debuggers > \uicontrol Add to add it. - \li \l{Debug Mode Views} + \image qtcreator-preferences-kits-debuggers.webp {Debuggers tab in Kits preferences} - Use the views in the \uicontrol Debug mode to inspect the - state of your application while debugging. + To use the debugging tools for Windows, you must install them. + Optionally, you can set up the Microsoft Symbol Server if you need + symbol information from Microsoft modules that is not found locally. - \li \l{Stopping Applications} + For more information, see \l{Supported Native Debuggers} and \l{CDB Paths}. - You can interrupt a running application before it terminates - or to find out why the application does not work correctly. - Set breakpoints to stop the application for examining and changing - variables, setting new breakpoints or removing old ones, and then - continue running the application. + \section1 Launching the Debugger - \li \l{Examining Data} + The debugger plugin can run the native debuggers in various operating modes + depending on where and how you start and run the debugged process. Some of + the modes are only available for a particular operating system or platform: - You can examine variable values and data structures in detail. + \list + \li \e{Start internal} to debug applications developed inside \QC, such as + a Qt Widgets-based application. This is the default start mode for + most projects, including all projects using a desktop Qt version and + plain C++ projects. + \li \e{Start external} to start and debug processes without a proper \QC + project setup, either locally or on a remote machine. + \li \e{Attach} to debug processes already started and running outside + \QC, either locally or on a remote machine. + \li \e{Core} to debug crashed processes on Unix. + \li \e{Post-mortem} to debug crashed processes on Windows. + \endlist - \li \l{Remote Debugging} + In general, \key F5 and the \uicontrol {Start Debugging of Startup Project} + button start the operating mode that fits the context. So, for a C++ + application that uses the \MinGW toolchain targeting desktop Windows, the GDB + engine starts in \e {start internal} mode. For a QML application that uses C++ + plugins, a \e mixed QML/C++ engine starts, with the C++ parts being + handled by GDB and GDB server remote debugging. - You can debug an application that runs on a remote target with the - necessary helper processes also running. + Change the run configuration parameters (such as + \uicontrol {Run in Terminal}) in the run settings of the project, or select + options from the \uicontrol Debug > \uicontrol {Start Debugging} menu to + select other modes of operation. - \li \l{Debugger Preferences} + \section2 GDB Run Modes - Specify preferences for managing debugger processes. You can specify - preferences that are common to all debuggers, or the native debugger - that you use, GDB or CDB. + The GDB native debugger used internally by the debugger plugin runs in + different modes to cope with the variety of supported platforms and + environments: - \li \l{Using Debugging Helpers} + \list + \li \e{Plain mode} debugs locally started processes that do not need + console input. + \li \e{Terminal mode} debugs locally started processes that need a + console. + \li \e{Attach mode} debugs local processes started outside \QC. + \li \e{Core mode} debugs core files generated from crashes. + \li \e{Remote mode} interacts with the GDB server running on Linux. + \endlist - \QC is able to show complex data types in a customized, - user-extensible manner. For this purpose, it takes advantage of - two technologies, collectively referred to as \e {debugging - helpers}. + \section1 Stopping Applications - \li \l{Debugging Qt Quick Projects} + You can interrupt a running application before it terminates + or to find out why the application does not work correctly. + Set breakpoints to stop the application for examining and changing + variables, setting new breakpoints or removing old ones, and then + continue running the application. - When debugging a Qt Quick application, you can inspect the state of - the application while debugging JavaScript functions. You can set - breakpoints, view call stack trace, and examine locals and - expressions. While the application is running, you can inspect QML - objects and user interfaces, as well as execute JavaScript - expressions. + Once the application starts running under the control of the debugger, it + behaves and performs as usual. - \li \l{Debugging a C++ Application} + To interrupt a running C++ application, go to \uicontrol Debug > + \uicontrol Interrupt. The debugger automatically interrupts + the application when it hits a \l {Setting Breakpoints}{breakpoint}. - Illustrates how to debug C++ applications in \QC. + Once the application stops, \QC: - \li \l{Debugging a Qt Quick Application} + \list - Illustrates how to debug Qt Quick applications in \QC. + \li Retrieves data representing the \l{Viewing Call Stack Trace} + {call stack} at the application's current position. - \li \l{Troubleshooting Debugger} + \li Retrieves the contents of \l{Local Variables and Function Parameters} + {local variables}. + + \li Examines \l{Evaluating Expressions}{expressions}. + + \li Updates the \l{Viewing and Editing Register State}{Registers}, + \l{Viewing Modules}{Modules}, and \l{Viewing Disassembled Code} + {Disassembler} views if you are debugging C++ based applications. - If you encounter problems while debugging, check for possible - solutions to them. \endlist - \sa {Debug CMake project files} -*/ + You can examine and change variables, set or remove breakpoints, and then + continue running the application. + + \section1 Examining Data + + When the application stops, you can examine certain data in the debugger. The + availability of data depends on the compiler settings when compiling the + application and the exact location where the application stops. + + Unexpected events are called \e exceptions and the debugger can stop + the application when they occur. Going to the location in the code where + the exception occurred helps you investigate the problem and find ways to + fix it. + + If you have a variable that shows text, but the application does not display + it correctly, for example, your data might be incorrect or the code that sets + the display text might do something wrong. You can step through the code and + examine changes to the variable to find out where the error occurs. + + The following video shows how to examine variable values: + + \youtube EhJ1eV_6RH8 + + \section1 Remote Debugging + + \QC makes remote debugging easy. In general, the remote debugging setup + consist of a probe running on the remote computer and a counterpart running + on the host. The probe is either integrated into the running + process (for example, for QML debugging) or runs a separate process + (for example, when using GDB server on embedded Linux). The host + side typically consists of \QC itself, often with the help of an external + process, such as GDB or CDB. + + While this setup might look daunting, it is mostly invisible to the user of + \QC. To start debugging on a remote target with the necessary helper + processes running, activate the corresponding \l{Activate kits for a project} + {kit} in \uicontrol Projects > \uicontrol {Build & Run}, and then select a + function to start remote debugging in the \uicontrol Debug > + \uicontrol {Start Debugging} menu. + Special use cases, such as attaching to a running process on the target, + might still require manual setup. You can debug an application that runs on + a remote target with the necessary helper processes also running. + + For more information, see \l{Debug remotely with GDB} and + \l{Debug remotely with CDB}. + + \section1 Using Debugging Helpers + + To show complex structures, such as \c QObjects or associative containers, + in a clear and concise manner, \QC uses Python scripts that are called + \l{Debugging Helpers}{debugging helpers}. + + \QC ships with debugging helpers for more than 200 of the most popular Qt + classes, standard C++ containers, and smart pointers, covering the usual + needs of a C++ application developer out-of-the-box. + + You can customize and add debugging helpers. + + \section1 QML and Qt Quick + + When debugging a Qt Quick application, you can inspect the state of + the application while debugging JavaScript functions. You can set + breakpoints, view call stack trace, and examine locals and + expressions. While the application is running, you can inspect QML + objects and user interfaces, as well as execute JavaScript + expressions. + + For more information, see \l{Debugging Qt Quick Projects} and + \l{Debugging a Qt Quick Application}. + + \sa {Debugging a C++ Application}, {Debug}{How To: Debug}, {Debuggers}, + {Debugger} +*/ /*! - \previouspage creator-debugger-engines.html - \page creator-debugger-operating-modes.html - \nextpage creator-debug-mode.html + \page creator-how-to-start-debugging.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug - \title Launching the Debugger + \title Start debugging You can start an application from an open project under the control of a debugger in the following ways: @@ -128,75 +236,46 @@ \endlist \QC checks whether the compiled application is up-to-date, and rebuilds and - deploys it if you set the \uicontrol {Build before deploying} field to - build the whole project or the application to run and select the - \uicontrol {Always deploy before running} check box in \preferences > + deploys it if you set \uicontrol {Build before deploying} to + build the whole project or the application to run and select + \uicontrol {Always deploy before running} in \preferences > \uicontrol {Build & Run} > \uicontrol General. To debug the application - without deploying it, select \uicontrol Debug > \uicontrol {Start Debugging} + without deploying it, go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start Debugging Without Deployment}. The debugger then takes over and starts the application with suitable parameters. + You can specify breakpoints before or after launching the debugger. + For more information, see \l{Setting Breakpoints}. + + \section1 Execute GDB or CDB commands + When using GDB or CDB as debug backend, you can specify additional commands to execute before and after the backend and debugged application are started or attached in \preferences > \uicontrol Debugger > - \uicontrol GDB and \uicontrol CDB. For more information, see - \l{Debugger Preferences}. + \l GDB and \l CDB. To let the debugger read the user's default .gdbinit file when it starts, - select the \uicontrol {Load .gdbinit file on startup} check box in - GDB settings. For more information, see \l{Specifying GDB Settings}. + select \uicontrol {Load .gdbinit file on startup} in GDB settings. \note Starting a C++ application under the control of the debugger can take a long time. Typically, in the range of several seconds to minutes if you use complex features. + \section1 Debug Python projects + For \l {Creating a Qt for Python Application with Qt Widgets}{Python} projects, start debugging the \c main.py file. If you encounter problems, check the active build target in the \l{Build for many platforms}{kit selector}. - \section1 Debugger Operating Modes - - The debugger plugin can run the native debuggers in various operating modes - depending on where and how you start and run the debugged process. Some of - the modes are only available for a particular operating system or platform. - - In general, \key F5 and the \uicontrol {Start Debugging of Startup Project} - button start the operating mode that fits the context. So, for a C++ - application that uses the \MinGW toolchain targeting desktop Windows, the GDB - engine starts in \e {start internal} mode. For a QML application that uses C++ - plugins, a \e mixed QML/C++ engine starts, with the C++ parts being - handled by GDB and GDB server remote debugging. - - Change the run configuration parameters (such as - \uicontrol {Run in Terminal}) in the run settings of the project, or select - options from the \uicontrol Debug > \uicontrol {Start Debugging} menu to - select other modes of operation. - - The debugger can run in the following modes: - - \list - - \li \e{Start internal} to debug applications developed inside \QC, such as - a Qt Widgets-based application. - - \li \e{Start external} to start and debug processes without a proper \QC - project setup, either locally or on a remote machine. - - \li \e{Attach} to debug processes already started and running outside - \QC, either locally or on a remote machine. - - \li \e{Core} to debug crashed processes on Unix. - - \li \e{Post-mortem} to debug crashed processes on Windows. - - \endlist + \QC does not support mixed-mode debugging, but you can attach GDB to the + Python interpreter to debug the C++ implementation of the corresponding + Python code. For more information, see + \l{https://doc.qt.io/qtforpython-6/tutorials/debugging/qtcreator/qtcreator.html} + {Debugging PySide with Qt Creator (Linux)}. - \section2 Start Internal - - Start internal mode is the default start mode for most projects, including - all projects using a desktop Qt version and plain C++ projects. + \section1 Debug console applications If you need a console window to operate your application, for example because it accepts console input from the user, go to \uicontrol Projects > @@ -205,46 +284,49 @@ If a console application does not start up properly in the configured console and the subsequent attach fails, you can diagnose the issue by - using CDB's native console. Select \preferences > + using CDB's native console. Go to \preferences > \uicontrol Debugger > \uicontrol CDB > \uicontrol {Use CDB console} to override the console set in the Windows system environment variables. Note that the native console does not prompt on application exit. - To launch the debugger in start internal mode, click the - \uicontrol {Start Debugging} button for the active project. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ - You can specify breakpoints before or after launching the debugger. - For more information, see \l{Setting Breakpoints}. +/*! + \page creator-how-to-debug-external-apps.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug - \section2 Start External + \title Start and debug an external application - You can debug any executable on your local or on a remote - machine without using a project. You specify a build and run kit that + To debug any executable on your local or on a remote + machine without using a project, specify a build and run kit that identifies the device to debug the application on. - While this mode does not strictly require a project to be open in \QC, - opening it makes setting breakpoints and stepping through the code easier. + While the \e{start external} debugger mode does not strictly require a + project to be open in \QC, opening it makes setting breakpoints and + stepping through the code easier. To start and debug an external application: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start and Debug External Application}. \image qtcreator-debugger-start-external.png - \li In the \uicontrol Kit field, select the build and run kit to + \li In \uicontrol Kit, select the build and run kit to use for building the project. - \li In the \uicontrol {Local executable} field, specify the path to the + \li In \uicontrol {Local executable}, specify the path to the application executable on the local machine. - \li In the \uicontrol {Command line arguments} field, specify command + \li In \uicontrol {Command line arguments}, specify command line arguments to be passed to the executable. - \li In the \uicontrol {Working directory} field, specify the working + \li In \uicontrol {Working directory}, specify the working directory. It defaults to the directory of the build result. - \li Select the \uicontrol{Run in terminal} check box for console - applications. - \li Select the \uicontrol {Break at "main"} check box to stop the - debugger at the main function. - \li Select the \uicontrol {Use target extended-remote to connect} - check box to create the connection in the + \li Select \uicontrol{Run in terminal} for console applications. + \li Select \uicontrol {Break at "main"} to stop the debugger at + the main function. + \li Select \uicontrol {Use target extended-remote to connect} + to create the connection in the \c {target extended-remote mode}. In this mode, when the debugged application exits or you detach from it, the debugger remains connected to the target. You can rerun the application, attach @@ -252,29 +334,33 @@ target. For example, GDB does not exit unless it was invoked using the \c {--once} option, but you can make it exit by using the \c {monitor exit} command. - \li In the \uicontrol {Override SysRoot} field, specify the path to + \li In \uicontrol {Override SysRoot}, specify the path to the \c sysroot to use instead of the default \c sysroot. - \li In the \uicontrol {Debug information} field, specify the location + \li In \uicontrol {Debug information}, specify the location for storing debug information. You cannot use an empty path. - \li In the \uicontrol Recent field, you can select a recent + \li In \uicontrol Recent, you can select a recent configuration to use. \endlist - \section2 Attach + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-attach-debugger-to-running-apps.html + \previouspage creator-how-tos.html - You can attach the debugger to applications that are already running or - instruct the debugger to attach to an application when it starts. + \ingroup creator-how-to-debug - \section3 Attaching to Running Applications + \title Attach the debugger to running applications To attach the debugger to an application already running on your local or on a remote machine: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to Running Application}. \image qtcreator-debugger-attach-to-running.png - \li In the \uicontrol Filter field, enter a string to filter processes + \li In \uicontrol Filter, enter a string to filter processes by their process ID or name. \li Select a process in the list, and then select \uicontrol {Attach to Process} to start debugging. @@ -290,28 +376,46 @@ You can specify breakpoints before or after attaching the debugger to the application. For more information, see \l{Setting Breakpoints}. - \section3 Attaching to Processes when They Start + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-attach-debugger-to-starting-processes.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Attach the debugger to starting processes To instruct the debugger to watch an application process and to attach to it when it starts: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to Unstarted Application}. \image qtcreator-debugger-attach-to-process-not-yet-started.png - \li In the \uicontrol Kit field, select the build and run kit to + \li In \uicontrol Kit, select the build and run kit to use for building the project. - \li In the \uicontrol Executable field, specify the path to the + \li In \uicontrol Executable, specify the path to the application executable. - \li Select the \uicontrol {Reopen dialog when application finishes} - check box to return to this dialog when the application is closed. - \li Select the \uicontrol {Continue on attach} check box to instruct + \li Select \uicontrol {Reopen dialog when application finishes} + to return to this dialog when the application is closed. + \li Select \uicontrol {Continue on attach} to instruct the debugger to keep the application running after attaching to it. \li Select \uicontrol {Start Watching} to wait for the application process to start. \endlist - \section2 Core + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-load-core-files-to-debugger.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Load core files to the debugger Use the core mode to inspect \e {core} files (crash dumps) that are generated from crashed processes on Linux and Unix systems if the system is @@ -327,38 +431,46 @@ To launch the debugger in the core mode: \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Load Core File}. \image qtcreator-debugger-load-core-file.png - \li In the \uicontrol Kit field, select a build and run kit that was + \li In \uicontrol Kit, select a build and run kit that was used for building the binary for which the core file was created. If the core file stems from a binary not built by \QC or a process not initiated by \QC, select a kit that matches the setup used as - closely as possible, in respect to the specified device, tool chain, + closely as possible, in respect to the specified device, toolchain, debugger, and sysroot. - \li In the \uicontrol {Core file} field, specify the core file to - inspect. - \li In the \uicontrol {Executable of symbol file} field, specify + \li In \uicontrol {Core file}, specify the core file to inspect. + \li In \uicontrol {Executable of symbol file}, specify a file that has debug information corresponding to the core file. Typically, this is the executable file or a \c {.debug} file if the debug information is stored separately from the executable. - \li In the \uicontrol {Override start script} field, specify a + \li In \uicontrol {Override start script}, specify a script file to run instead of the default start script. - \li In the \uicontrol {Override SysRoot} field, specify the path to + \li In \uicontrol {Override SysRoot}, specify the path to the \c sysroot to use instead of the default \c sysroot. \endlist Even though using a properly configured project that has the sources of the crashed application is not strictly necessary, it is helpful. - \section2 Post-Mortem + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, {Kits} +*/ + +/*! + \page creator-how-to-debug-post-mortem.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Debug crashed processes on Windows - The post-mortem mode is available only on Windows, if you installed the - debugging tools for Windows. + The \e{post-mortem} debugger operating mode is available only on Windows, + if you installed the debugging tools for Windows. The \QC installation program asks you whether you want to register \QC as a - post-mortem debugger. To change the setting, select + post-mortem debugger. To change the setting, go to \preferences > \uicontrol Debugger > \uicontrol General > \uicontrol {Use \QC for post-mortem debugging}. @@ -366,7 +478,16 @@ crashes on Windows. Click the \uicontrol {Debug in \QC} button in the error message from the Windows operating system. - \section1 Starting the Debugger from the Command Line + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} +*/ + +/*! + \page creator-how-to-start-debugger-from-cli.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Start debugging from the command line You can use the \QC debugger interface from the command line. To attach it to a running process, specify the process ID as a parameter for the @@ -386,35 +507,17 @@ \endlist - For more information, see \l{Command-Line Options}. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Command-Line Options} */ /*! - \page creator-remote-debugging.html - \previouspage creator-debugger-examining-data.html - \nextpage creator-debugger-preferences.html + \page creator-how-to-debug-remotely-gdb.html + \previouspage creator-how-tos.html - \title Remote Debugging + \ingroup creator-how-to-debug - \QC makes remote debugging easy. - In general, the remote debugging setup consist of a probe running on the - remote machine and a counterpart running on the host side. The probe is - either integrated into the running process (e.g. for QML debugging) or runs - a separate process (e.g. when using GDB server on embedded Linux). The host - side typically consists of \QC itself, often with the help of an external - process, such as GDB or CDB. - - While this setup might look daunting, it is mostly invisible to the user of - \QC. To start debugging on a remote target with the necessary helper - processes running, select the corresponding - \l{glossary-buildandrun-kit}{kit} in \uicontrol Projects > - \uicontrol {Build & Run}, and then select a function to start remote - debugging in the \uicontrol Debug > \uicontrol {Start Debugging} menu. - - Special use cases, such as attaching to a running process on the target, - might still require manual setup. - - \section1 Using GDB + \title Debug remotely with GDB When debugging on a target supported by GDB server, a local GDB process talks to a GDB server running on the remote machine that controls the @@ -437,25 +540,24 @@ \list 1 - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to Running Debug Server}. \image qtcreator-debugger-attach-to-running-debug-server.png - \li In the \uicontrol Kit field, select the build and run kit to + \li In \uicontrol Kit, select the build and run kit to use for building the project. - \li In the \uicontrol {Server port} field, enter the name of the remote + \li In \uicontrol {Server port}, enter the name of the remote machine and the port number to use. - \li In the \uicontrol {Local executable} field, specify the path to the + \li In \uicontrol {Local executable}, specify the path to the application executable on the local machine. - \li In the \uicontrol {Command line arguments} field, specify command + \li In \uicontrol {Command line arguments}, specify command line arguments to be passed to the executable. - \li In the \uicontrol {Working directory} field, specify the working + \li In \uicontrol {Working directory}, specify the working directory. It defaults to the directory of the build result. - \li Select the \uicontrol{Run in terminal} check box for console - applications. - \li Select the \uicontrol {Break at "main"} check box to stop the + \li Select \uicontrol{Run in terminal} for console applications. + \li Select \uicontrol {Break at "main"} to stop the debugger at the main function. - \li Select the \uicontrol {Use target extended-remote to connect} - check box to create the connection in the + \li Select \uicontrol {Use target extended-remote to connect} + to create the connection in the \c {target extended-remote mode}. In this mode, when the debugged application exits or you detach from it, the debugger remains connected to the target. You can rerun the application, attach @@ -463,34 +565,41 @@ target. For example, GDB does not exit unless it was invoked using the \c {--once} option, but you can make it exit by using the \c {monitor exit} command. - \li In the \uicontrol {Override SysRoot} field, specify the path to + \li In \uicontrol {Override SysRoot}, specify the path to the \c sysroot to use instead of the default \c sysroot. - \li In the \uicontrol {Init commands} field, enter the commands + \li In \uicontrol {Init commands}, enter the commands to execute immediately after the connection to a target has been established. - \li In the \uicontrol {Reset commands} field, enter the commands + \li In \uicontrol {Reset commands}, enter the commands to execute when resetting the connection to a target. - \li In the \uicontrol {Debug information} field, specify the location + \li In \uicontrol {Debug information}, specify the location for storing debug information. You cannot use an empty path. - \li In the \uicontrol {Override server channel} field, specify a + \li In \uicontrol {Override server channel}, specify a communication channel to use, such as a serial line or custom port. - \li In the \uicontrol Recent field, you can select a recent - configuration to use. + \li In \uicontrol Recent, select a recent configuration to use. \li Select \uicontrol OK to start debugging. \endlist - By default, a non-responsive GDB process is terminated after 20 seconds. - To increase the timeout in the \uicontrol {GDB timeout} field, select - \preferences > \uicontrol Debugger > - \uicontrol GDB. For more information about settings that you can specify - to manage the GDB process, see \l{Specifying GDB Settings}. + By default, a non-responsive GDB process is terminated after 40 seconds. + To increase the timeout in \uicontrol {GDB timeout}, go to \preferences > + \uicontrol Debugger > \uicontrol GDB. For more information about connecting with \c {target extended-remote} mode in GDB, see \l{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html} {Debugging with GDB: Connecting to a Remote Target}. - \section1 Using CDB + \sa {Debug}{How To: Debug}, {GDB}, {Debugging}, + {Debuggers}, {Debugger}, {Kits} +*/ + +/*! + \page creator-how-to-debug-remotely-cdb.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Debug remotely with CDB In remote mode, the local CDB process talks to a CDB process that runs on the remote machine. The process is started with special command-line options @@ -555,23 +664,23 @@ \endlist - To specify settings for managing the CDB process, select \preferences > - \uicontrol Debugger > \uicontrol CDB. For more information, see - \l{Specifying CDB Settings}. + To specify settings for managing the CDB process, go to \preferences > + \uicontrol Debugger > \uicontrol CDB. + + \sa {Debug}{How To: Debug}, {CDB}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-debug-mode.html - \if defined(qtdesignstudio) - \previouspage studio-debugging.html - \else - \previouspage creator-debugger-operating-modes.html - \endif - \nextpage creator-stack-view.html + \previouspage creator-reference.html + + \ingroup creator-reference-debugger-views \title Debug Mode Views + \brief Inspect the state of your application while debugging. + In the \uicontrol Debug mode, you can inspect the state of your application while debugging. @@ -685,7 +794,7 @@ During debugging, the mode shows the views that you usually need to debug C++ or QML applications. To show other views or to hide views, - select \uicontrol Views. + go to \uicontrol Views. You can drag the views in \QC to new positions on the screen. \QC saves the size and position of views as a perspective for future sessions. Select @@ -714,70 +823,17 @@ interrupted. \endlist - For more information, see \l{Debugger Preferences}. -*/ - -/*! - \page creator-debugger-stopping.html - \previouspage creator-disassembler-view.html - \nextpage creator-debugger-examining-data.html - - \title Stopping Applications - - Once the application starts running under the control of the debugger, it - behaves and performs as usual. - - To interrupt a running C++ application, select \uicontrol Debug > - \uicontrol Interrupt. The debugger automatically interrupts - the application when it hits a \l {Setting Breakpoints}{breakpoint}. - - Once the application stops, \QC: - - \list - - \li Retrieves data representing the \l{Viewing Call Stack Trace} - {call stack} at the application's current position. - - \li Retrieves the contents of \l{Local Variables and Function Parameters} - {local variables}. - - \li Examines \l{Evaluating Expressions}{expressions}. - - \li Updates the \l{Viewing and Editing Register State}{Registers}, - \l{Viewing Modules}{Modules}, and \l{Viewing Disassembled Code} - {Disassembler} views if you are debugging C++ based applications. - - \endlist - You can \l{Examining Data}{Examine} and change variables, set or remove - breakpoints, and then continue running the application. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} */ /*! \page creator-debugger-examining-data.html - \previouspage creator-debugger-stopping.html - \nextpage creator-remote-debugging.html - - \title Examining Data - - When the application stops, you can examine certain data in the debugger. The - availability of data depends on the compiler settings when compiling the - application and the exact location where the application stops. - - Unexpected events are called \e exceptions and the debugger can stop - the application when they occur. Going to the location in the code where - the exception occurred helps you investigate the problem and find ways to - fix it. - - If you have a variable that shows text, but the application does not display - it correctly, for example, your data might be incorrect or the code that sets - the display text might do something wrong. You can step through the code and - examine changes to the variable to find out where the error occurs. + \previouspage creator-how-tos.html - The following video shows how to examine variable values: - - \youtube EhJ1eV_6RH8 + \ingroup creator-how-to-debug - \section1 Showing Tooltips for Simple Values + \title Show tooltips for simple values To display the value of a simple variable, hover the mouse pointer over its name in the code editor. @@ -791,11 +847,21 @@ select \uicontrol {Close Editor Tooltips} in the context menu in the \uicontrol Locals or \uicontrol Expressions view. - To disable tooltips for performance reasons, select \preferences > + To disable tooltips for performance reasons, go to \preferences > \uicontrol Debugger > \uicontrol General > \uicontrol {Use tooltips in main editor when debugging}. - \section1 Examining Complex Values in Debug Views + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} +*/ + +/*! + \page creator-how-to-examine-complex-values.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Examine complex values in Debug views \QC displays the raw information from the native debuggers in a clear and concise manner to simplify the debugging process without losing the power @@ -826,7 +892,7 @@ To show complex structures, such as \c QObjects or associative containers, in a clear and concise manner, \QC uses Python scripts that are called - \l{Using Debugging Helpers}{debugging helpers}. + \l{Debugging Helpers}{debugging helpers}. In addition to the generic IDE functionality of the \l {Viewing Call Stack Trace}{Stack}, \uicontrol {Locals}, @@ -839,10 +905,21 @@ classes in a useful way. To change the number of array elements that are - requested when expanding entries, select \preferences > \uicontrol {Debugger} + requested when expanding entries, go to \preferences > \uicontrol {Debugging} > \uicontrol {Locals & Expressions} > \uicontrol {Default array size}. - \section1 Stepping Through Code + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} +*/ + +/*! + \page creator-how-to-step-through-code.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Step through code The following table summarizes the functions that you can use to step through the code and examine the changes in variables. @@ -900,17 +977,17 @@ stopped. \endtable - \section2 Compressing Steps in GDB + \section1 Compress steps in GDB When using GDB as the debugging backend, you can compress several steps into one step for less noisy debugging. For more information, see - \l{Specifying GDB Settings}. + \l{GDB}. The extended GDB settings have the option to step backwards in code, but this option should be used with care, as it is slow and unstable on the - GDB side. For more information, see \l{Specifying GDB Settings}. + GDB side. For more information, see \l{GDB}. - \section2 Stepping into Frameworks in \macos + \section1 Step into Frameworks in \macos In \macos, external libraries are usually built into so-called Frameworks, which may have both release and debug versions of the library. When you @@ -919,7 +996,17 @@ \uicontrol {Use debug versions of Frameworks} option in the project run settings. - \section1 Inspecting Basic Qt Objects + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}, + {Debugger Views} +*/ + +/*! + \page creator-how-to-inspect-basic-qt-objects.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-debug + + \title Inspect basic Qt objects The most powerful feature of the debugger is that the \uicontrol {Locals} and \uicontrol {Expressions} views show the data that belongs to @@ -931,16 +1018,16 @@ displays the contents of a QHash or QMap in an orderly manner. Also, the debugger shows access data for QFileInfo and the \e real contents of QVariant. - \section2 Changing Value Display format + \section1 Change value display format In the \uicontrol {Locals} or the \uicontrol {Expressions} view, select \uicontrol {Change Value Display Format} in the context menu to change the value display format. The available options depend on the type of the - current items, and are provided by the debugging helpers. + current items, and are provided by \l{Debugging Helpers}{debugging helpers}. - To force a plain C-like display of structures, select \preferences > - \uicontrol Debugger > \uicontrol {Locals & Expressions}, and then deselect the - \uicontrol {Use Debugging Helpers} check box. This still uses the + To force a plain C-like display of structures, go to \preferences > + \uicontrol Debugger > \uicontrol {Locals & Expressions}, and then clear + \uicontrol {Use Debugging Helpers}. This still uses the Python scripts, but generates more basic output. To force the plain display for a single object or for all objects of a given type, select \uicontrol {Change Value Display Format} > \uicontrol Raw in the context @@ -961,7 +1048,7 @@ instead of a single line item in the view. For QPixmap, you can see the pixmap being created pixel-by-pixel when stepping through the code. - \section2 Changing Variable Values + \section1 Change variable values You can use the \uicontrol {Locals} and \uicontrol {Expressions} view to change the contents of variables of simple data types, for example, \c int, \c float, @@ -975,11 +1062,11 @@ applies the changes only if the new content fits into the old memory and if the debugger supports changing values. - \section2 Signal-Slot Connections + \section1 Signal-slot connections If an instance of a class is derived from QObject, you can find all other objects connected to this object's slots with Qt's signals and slots - mechanism. Select \preferences > \uicontrol {Debugger} > + mechanism. Go to \preferences > \uicontrol {Debugging} > \uicontrol {Locals & Expressions} > \uicontrol {Use Debugging Helpers}. \image qtcreator-debugging-helper-options.webp {Locals & Expressions preferences} @@ -988,7 +1075,7 @@ in the \e slots subitem. The view shows the objects connected to this slot as children of the slot. Similarly, you can show the children of signals. - \section2 Low-level Data + \section1 Low-level data If you cannot debug Qt objects because their data is corrupted, you can switch off the debugging helpers to make low-level structures visible. @@ -998,7 +1085,7 @@ \uicontrol Debugger > \uicontrol {Locals & Expressions}. \omit - \section2 Creating Snapshots + \section1 Create snapshots A snapshot has the complete state of the debugged application at a time, including the full memory contents. @@ -1015,15 +1102,20 @@ \l{https://sourceware.org/gdb/onlinedocs/gdb/Core-File-Generation.html}. \endomit + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-threads-view.html - \previouspage creator-breakpoints-view.html - \nextpage creator-modules-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Threads + \brief View the threads currently active in a multi-threaded application. + An application can have more than one thread of execution that share one address space, which means that they can examine and change the same variables. However, each thread has its own registers, execution stack, @@ -1042,15 +1134,20 @@ The \l {Viewing Call Stack Trace}{Stack} view adjusts its contents accordingly. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-modules-view.html - \previouspage creator-threads-view.html - \nextpage creator-source-files-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Modules + \brief View information about the modules included in a debugged application. + The \uicontrol Modules view displays information that the debugger plugin has about modules included in the application that is being debugged. @@ -1088,7 +1185,7 @@ \li Show sections in modules - \li Set \l{Debugger Preferences}{debugger preferences} + \li Set \l{Debugger}{debugger preferences} \endlist @@ -1099,21 +1196,26 @@ When using CDB as debug backend, you can specify that the debugger should break when application modules are loaded or unloaded. To enable breaking - for the specified modules, select \preferences > \uicontrol Debugger > + for the specified modules, go to \preferences > \uicontrol Debugger > \uicontrol CDB. \image qtcreator-cdb-options.png {CDB tab in Debugger preferences} - For more information, see \l{Specifying CDB Settings}. + For more information, see \l{CDB}. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-source-files-view.html - \previouspage creator-modules-view.html - \nextpage creator-locals-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Source Files + \brief View source files included in a debugged project. + The \uicontrol {Source Files} view lists all the source files included in the project. If you cannot step into an instruction, you can check whether the source file is actually part of the project, or whether it was compiled @@ -1126,7 +1228,7 @@ \list \li Reload data \li Open the selected file - \li Set \l{Debugger Preferences}{debugger preferences} + \li Set \l{Debugger}{debugger preferences} \endlist By default, the \uicontrol {Source Files} view is hidden. To show it, select @@ -1137,20 +1239,26 @@ To enable the debugger to step into the code and display the source code when using a copy of the source tree at a location different from the one at which the libraries were built, you can map source paths to target - paths in \preferences > \uicontrol Debugger > \uicontrol General: + paths in \preferences > \uicontrol Debugger > \uicontrol General. \image qtcreator-debugger-general-options.png {General tab in Debugger preferences} - For more information, see \l{Mapping Source Paths}. + For more information, see \l{Source Paths Mapping}. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-registers-view.html - \previouspage creator-expressions-view.html - \nextpage creator-peripheral-registers-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing and Editing Register State + \brief View the current state of general-purpose and special-purpose CPU + registers. + \e {Machine code} consists of machine language instructions that make the CPU perform tasks, such as load or store, on units of data in the CPU's registers or memory. @@ -1177,7 +1285,7 @@ \li Open \l {Examining Memory}{Memory Editor} at the selected value. \li Open the \l {Viewing Disassembled Code}{Disassembler} view. \li Display a value in hexadecimal, decimal, octal, or binary format. - \li Set \l{Debugger Preferences}{debugger preferences}. + \li Set \l{Debugger}{debugger preferences}. \endlist By default, the \uicontrol Registers view is hidden. To show it, select it in @@ -1203,15 +1311,21 @@ \li Set a data breakpoint on the selection. \li Jump to the selected address in the current data view or a new one. \endlist + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-peripheral-registers-view.html - \previouspage creator-registers-view.html - \nextpage creator-debugger-log-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Peripheral Registers + \brief View the current state of peripheral devices, such as a mouse, + keyboard, display, printer, or USB drive. + The \uicontrol {Peripheral Registers} view displays the current state of peripheral devices, such as a mouse, keyboard, display, printer, or USB drive. Applications write registers to send information to the device and @@ -1231,28 +1345,33 @@ \list \li View register groups. - \li Set \l{Debugger Preferences}{debugger preferences}. + \li Set \l{Debugger}{debugger preferences}. \endlist By default, the \uicontrol {Peripheral Registers} view is hidden. To show it, select it in \uicontrol Views on the debugger toolbar. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-debugger-log-view.html - \previouspage creator-peripheral-registers-view.html - \nextpage creator-disassembler-view.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Debugger Log + \brief Troubleshoot the debugger. + You can view debug output in the \uicontrol {Debugger Log} view to \l {Debugger Does Not Work}{troubleshoot the debugger}. \image qtcreator-debugger-log-view.webp {Debugger Log view} - If debug output is sent to the system log, select \preferences > - \uicontrol Debugger > \uicontrol General > - \uicontrol {Force logging to console} check box. + If debug output is sent to the system log, go to \preferences > + \uicontrol Debugger > \uicontrol General and select + \uicontrol {Force logging to console}. Right-click the view to select the following actions: @@ -1265,7 +1384,7 @@ \li Log time stamps. \li Reload debugging helpers after \l{Adding Custom Debugging Helpers} {adding custom debugging helpers}. - \li Set \l{Debugger Preferences}{debugger preferences}. + \li Set \l{Debugger}{debugger preferences}. \endlist \section1 Directly Interacting with Native Debuggers @@ -1282,15 +1401,20 @@ handle the task. For example, instead of using the GDB \c print command from the command line, you can evaluate an expression in the \l {Evaluating Expressions}{Expressions} view. + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! \page creator-disassembler-view.html - \previouspage creator-debugger-log-view.html - \nextpage creator-debugger-stopping.html + \previouspage creator-debug-mode.html + + \ingroup creator-reference-debugger-views \title Viewing Disassembled Code + \brief View disassembled code for the current function. + A \e disassembler translates machine language into assembly language for human-readability. @@ -1301,13 +1425,13 @@ \image qtcreator-debugger-disassembler-view.webp {Disassembler view} By default, GDB shows AT&T style disassembly. To switch to the Intel style, - select \preferences > \uicontrol Debugger > + go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Use Intel style disassembly}. To open the \uicontrol Disassembler view: \list - \li Select \uicontrol Debug > \uicontrol {Operate by Instruction} while + \li Go to \uicontrol Debug > \uicontrol {Operate by Instruction} while the debugger is running. \li Select the \inlineimage icons/debugger_singleinstructionmode.png (\uicontrol {Operate by Instruction}) tool button on the debugger @@ -1323,24 +1447,19 @@ \uicontrol {Open Disassembler} and set the disassembler address: \image qcreator-debugger-select-start-address.webp {Select Start Address dialog} + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! - \previouspage creator-debugger-preferences.html \page creator-debugging-helpers.html - \nextpage creator-debugging-qml.html + \previouspage creator-debug-mode.html - \title Using Debugging Helpers + \ingroup creator-reference-debugger - To show complex structures, such as \c QObjects or associative containers, - in a clear and concise manner, \QC uses Python scripts that are called - \e {debugging helpers}. - - \QC ships with debugging helpers for more than 200 of the most popular Qt - classes, standard C++ containers, and smart pointers, covering the usual - needs of a C++ application developer out-of-the-box. + \title Debugging Helpers - \section1 Extending Debugging Helpers + \brief Load, customize, and add debugging helpers. \QC uses Python scripts to translate raw memory contents and type information data from native debugger backends (GDB, LLDB, and CDB are currently supported) @@ -1357,17 +1476,17 @@ least one of the three supported backends is available. To use the default GDB pretty printers installed in your system or linked - to the libraries your application uses, select \preferences > + to the libraries your application uses, go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Load system GDB pretty - printers}. For more information, see \l{Specifying GDB Settings}. + printers}. For more information, see \l{GDB}. \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - \section2 Customizing Built-In Debugging Helpers + \section1 Customizing Built-In Debugging Helpers You can have commands executed after built-in debugging helpers have been loaded and fully initialized. To load additional debugging helpers or - modify existing ones, select \preferences > \uicontrol Debugger > + modify existing ones, go to \preferences > \uicontrol Debugger > \uicontrol {Locals & Expressions}, and enter the commands in the \uicontrol {Debugging Helper Customization} field. @@ -1389,10 +1508,10 @@ \endcode To display a message box as soon as your application receives a signal - during debugging, select \preferences > \uicontrol Debugger > \uicontrol GDB > + during debugging, go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Show a message box when receiving a signal}. - \section2 Adding Custom Debugging Helpers + \section1 Adding Custom Debugging Helpers To add debugging helpers for your own types, no compilation is required, just adding a few lines of Python. The scripts can address multiple versions @@ -1444,7 +1563,7 @@ \uicontrol {Reload Debugging Helpers} from the context menu of the \l {Debugger Log} view. - \section2 Debugging Helper Overview + \section1 Debugging Helper Overview The implementation of a debugging helper typically consists of a single Python function, which needs to be named \c{qdump__NS__Foo}, where @@ -1532,7 +1651,7 @@ d.putArrayData(base, size, typeobj) \endcode - \section2 Debugging Helper Implementation + \section1 Debugging Helper Implementation A debugging helper creates a description of the displayed data item in a format that is similar to GDB/MI and JSON. @@ -1586,7 +1705,7 @@ members specified in \c qtcreator\share\qtcreator\debugger\dumper.py. - \section3 Dumper Class + \section2 Dumper Class The \c Dumper class has generic bookkeeping, low-level, and convenience functions: @@ -1752,7 +1871,7 @@ \endlist - \section3 Dumper.Type Class + \section2 Dumper.Type Class The \c{Dumper.Type} class describes the type of a piece of data, typically a C++ class or struct, a pointer to a struct, or a primitive type, such as @@ -1807,7 +1926,7 @@ \endlist - \section3 Dumper.Field Class + \section2 Dumper.Field Class The \c{Dumper.Field} class describes a base class or a data member of a type object: @@ -1830,7 +1949,7 @@ \endlist - \section3 Dumper.Value Class + \section2 Dumper.Value Class The \c{Dumper.Value} class describes a piece of data, such as instances of C++ classes or primitive data types. It can also be used to describe @@ -1892,7 +2011,7 @@ \endlist - \section3 Children and SubItem Class + \section2 Children and SubItem Class The attempt to create child items might lead to errors if data is uninitialized or corrupted. To gracefully recover in such situations, use @@ -1931,16 +2050,21 @@ d.putSubItem("key", key) d.putSubItem("value", value) \endcode + + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ /*! - \previouspage creator-qml-debugging-example.html \page creator-troubleshooting-debugging.html - \nextpage creator-analyze-mode.html + \previouspage creator-reference.html + + \ingroup creator-reference-debugger \title Troubleshooting Debugger + \brief Solve problems that you might encounter while debugging. + This section lists some typical problems that you might encounter while debugging and solutions to them. @@ -1984,9 +2108,9 @@ \l {Run on many platforms}{build and run kit selector} picked a runnable target and you can run the application. - \li Make sure the debugger is \l{Setting Up Debugger}{set up properly}. + \li Make sure the debugger is \l{Supported Native Debuggers}{set up properly}. - \li In the \uicontrol Debug mode, select \uicontrol View > + \li In the \uicontrol Debug mode, go to \uicontrol View > \uicontrol Views > \uicontrol {Debugger Log} to open the \l {Debugger Log} view. Browse the contents of the pane on the right hand side to find out what went wrong. Always attach the @@ -2026,7 +2150,7 @@ When using GDB as backend, you can automatically save a copy of its symbol index in a cache on disk and retrieve it from there - when loading the same binary in the future. Select \preferences > + when loading the same binary in the future. Go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Use automatic symbol cache}. \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} @@ -2082,4 +2206,5 @@ calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment. + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc b/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc index 614219ce63..e7141a99f2 100644 --- a/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc +++ b/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2018 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -33,7 +33,7 @@ \if defined(qtdesignstudio) \note In this tutorial, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \endif @@ -47,13 +47,13 @@ border on the line where the \c startNewGame() function is called (1). - \image qtquick-example-setting-breakpoint1.png + \image qtquick-example-setting-breakpoint1.webp {Breakpoint in the code editor} The red circle indicates that a breakpoint is now set on that line number. - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > - \uicontrol {Start Debugging of Startup Project} or press + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > + \uicontrol {Start Debugging of Startup Project}, or press \key{F5}. \li Once the Same Game application starts, select \uicontrol {Puzzle} @@ -63,26 +63,26 @@ \li When the debugger hits the breakpoint, it interrupts the application. \QC displays the nested function calls leading to the - current position as a call stack trace (1). + current position as a call stack trace. - \image qtquick-example-setting-breakpoint2.png + \image qtquick-example-setting-breakpoint2.webp {Debugger view} - \li Click the \inlineimage icons/debugger_stepinto_small.png - (\uicontrol {Step Into}) button on the toolbar or press \key F11 to step + \li Select \inlineimage icons/debugger_stepinto_small.png + (\uicontrol {Step Into}) on the toolbar or press \key F11 to step into the code in the stack. The samegame.js file opens in the code editor at the function that starts a new game. - \image qtquick-example-stack.png + \image qtquick-example-stack.webp {Stack view} \li Examine the local variables in the \uicontrol Locals view. Step through the code to see how the information changes in the view. \li Add a breakpoint at the end of the \c {startNewGame()} function, and - click \inlineimage icons/qtcreator-debugging-continue.png + select \inlineimage icons/qtcreator-debugging-continue.png (\uicontrol Continue) to hit the breakpoint. - \image qtquick-example-setting-breakpoint3.png + \image qtquick-example-setting-breakpoint3.webp {Second breakpoint in the Breakpoints view} \li To execute JavaScript commands in the current context, open the \uicontrol {QML Debugger Console}. @@ -97,11 +97,11 @@ \image qtquick-example-qml-inspector.png - \li Select \uicontrol Debug > \uicontrol {Show Application on Top} to + \li Go to \uicontrol Debug > \uicontrol {Show Application on Top} to keep the application visible while you interact with the debugger. - \li Select \uicontrol Debug > \uicontrol Select to activate selection - mode and then click the \uicontrol Menu button to move into the + \li Go to \uicontrol Debug > \uicontrol Select to activate selection + mode, and then select \uicontrol Menu to move into the \uicontrol menuButton component in the \uicontrol Locals view and the code editor. diff --git a/doc/qtcreator/src/debugger/qtquick-debugging.qdoc b/doc/qtcreator/src/debugger/qtquick-debugging.qdoc index 325e53bc3f..1d4f41f789 100644 --- a/doc/qtcreator/src/debugger/qtquick-debugging.qdoc +++ b/doc/qtcreator/src/debugger/qtquick-debugging.qdoc @@ -13,15 +13,17 @@ \previouspage studio-debugging.html \nextpage creator-stack-view.html \else - \previouspage creator-debugging-helpers.html - \nextpage creator-debugging-example.html + \previouspage creator-reference.html \endif + \ingroup creator-reference-debugger + \ingroup studio-debugger + \title Debugging Qt Quick Projects - \if defined(qtcreator) - \note You need Qt 5.0 or later to debug Qt Quick projects. - \endif + \brief Debug JavaScript functions, execute JavaScript expressions to get + information about the state of the UI, and inspect QML properties and + JavaScript variables, as well as change their values temporarily at runtime. For an example of how to debug Qt Quick Projects, see \l{Debugging a Qt Quick Application}. @@ -29,7 +31,7 @@ \if defined(qtdesignstudio) \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \endif \section1 Setting Up QML Debugging @@ -56,8 +58,9 @@ \list 1 \li To create a build configuration that supports QML debugging, - select \uicontrol {Projects} > \uicontrol {Build} > - \uicontrol {QML debugging and profiling} > \uicontrol Enable. + go to \uicontrol {Projects} > \uicontrol {Build}. + + \li In \uicontrol {QML debugging and profiling}, select \uicontrol Enable. \image qtcreator-build-settings-cmake-configure.webp {Build settings for a CMake project} @@ -79,7 +82,7 @@ rebuild the project. \li To debug applications on \l{glossary-device}{devices}, check that - Qt 5.0, or later, libraries are installed on the device and + Qt libraries are installed on the device and \l{Run on many platforms}{select the corresponding kit for the device} before you start debugging. @@ -179,7 +182,7 @@ \note Setting breakpoints is only possible if the application is started with block mode. - \li Select \uicontrol Debug > \uicontrol {Start Debugging} > + \li Go to \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Attach to QML Port}. Choose the kit configured for the device where the application to @@ -225,7 +228,7 @@ \li Select the item in the code editor. - \li Select \uicontrol Debug > \uicontrol Select to activate selection + \li Go to \uicontrol Debug > \uicontrol Select to activate selection mode and then click an item in the running application. \endlist @@ -243,12 +246,6 @@ application to jump to their definitions in the code. The properties of the selected item are displayed in the \uicontrol {Locals} view. - \if defined(qtcreator) - The \uicontrol Select tool will be enabled either if your application is - using Qt 5.7 or later, or if your application is using an earlier version - of Qt and is based on the \c QQuickView class. - \endif - You can also view the item hierarchy in the running application: Double-click an item in the running application to cycle through the item @@ -282,4 +279,8 @@ When you change property values in the \uicontrol {QML Debugger Console} or in the \uicontrol Locals or \uicontrol Expression view, they are immediately updated in the running application, but not in the source code. + + \if defined(qtcreator) + \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} + \endif */ diff --git a/doc/qtcreator/src/docker/creator-docker.qdoc b/doc/qtcreator/src/docker/creator-docker.qdoc index 15f147d475..4f1167b359 100644 --- a/doc/qtcreator/src/docker/creator-docker.qdoc +++ b/doc/qtcreator/src/docker/creator-docker.qdoc @@ -3,12 +3,13 @@ /*! \page creator-adding-docker-devices.html - \previouspage creator-developing-b2qt.html - \nextpage creator-developing-ios.html + \previouspage creator-how-tos.html - \title Adding Docker Devices + \ingroup creator-how-to-docker - Create Docker devices from \l{ https://docs.docker.com/get-started/overview/} + \title Add Docker devices + + Create Docker devices from \l{https://docs.docker.com/get-started/overview/} {Docker images} and use them to build, run, and debug applications. A Docker container operates like a virtual machine but uses less system resources at the cost of being less flexible. @@ -16,37 +17,78 @@ While Linux, \macos, and Windows hosts are supported in principle, Linux is the recommended platform. - To build, run, and debug applications on Docker devices, you must install and + To build, run, and debug applications on Docker devices, install and configure \c docker-cli on the development host. \QC automatically detects \l{kits-tab}{build and run kit} items, such \l{Add debuggers} {debuggers} and \l{Add Qt versions}{Qt versions}, in the Docker container and creates kits for the devices. - You can use CMake or qmake to build applications in the Docker container. + You are advised to use CMake to build applications in the Docker container. + + \note Enable the Docker plugin to use it. To pull images from Docker hub or other registries, use the \l{https://docs.docker.com/engine/reference/commandline/pull/}{docker pull} command. - \section1 Adding Docker Images as Devices + \section1 Add Docker images as devices To add a Docker image as a device: \list 1 - \li Select \preferences > \uicontrol Devices - > \uicontrol Docker and enter the path to the Docker CLI in - the \uicontrol Command field. - \image qtcreator-preferences-devices-docker.webp "Docker tab in Devices preferences" - \li Select \uicontrol Devices > \uicontrol Add > - \uicontrol {Docker Device} > \uicontrol {Start Wizard} - to search for images in your local Docker installation. - \li Select the Docker image to use, and then select \uicontrol OK. + \li Go to \preferences > \uicontrol Devices > \uicontrol Docker. + \li In \uicontrol Command, enter the path to the Docker CLI. + \image qtcreator-preferences-devices-docker.webp {Docker tab in Devices preferences} + \li Go to \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {Docker Device} > + \uicontrol {Start Wizard} to search for images in your + local Docker installation. + \li Select a Docker image, and then select \uicontrol OK. \li In \uicontrol Devices, check and change Docker device preferences. - \image qtcreator-preferences-devices-docker-device.png "Docker device preferences" + \image qtcreator-preferences-devices-docker-device.png {Docker device preferences} \li Select \uicontrol Apply to save your changes. \endlist - The following table summarizes the options you can set. + \section2 Select Docker images + + The \uicontrol {Docker Image Selection} dialog displays a list of Docker + images in your local Docker installation. You can sort the images according + to the repository name or tag or the image ID or size. + + \image qtcreator-docker-image-selection.webp {Docker Image Selection dialog} + + Select \uicontrol {Show unnamed images} to show images that are not tagged. + + Double-click an image to select it. + + \section1 Edit Docker device kits + + Go to \preferences > \uicontrol Kits to check + that the automatically generated kits point to the appropriate kit items. + + \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker}, + {Manage Kits}{How To: Manage Kits} +*/ + +/*! + \page creator-preferences-docker.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-docker + + \title Set preferences for Docker devices + + \note Enable the Docker plugin to use it. + + To set preferences for Docker devices: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li In \uicontrol Device, select a Docker device. + \image qtcreator-preferences-devices-docker-device.png {Docker device preferences} + \endlist + + The following table summarizes the preferences you can set. \table \header @@ -59,7 +101,7 @@ on Windows. \row \li \uicontrol {Do not modify entry point} - \li Stops \QC from modifying the \l {Modifying Entry Points}{entry point} + \li Stops \QC from modifying the \l {Modify entry points}{entry point} of the image. Make sure that the entry point starts a shell. \row \li \uicontrol {Enable flags needed for LLDB} @@ -69,33 +111,18 @@ \endcode \row \li \uicontrol {Clangd executable} - \li The path to a remote Clangd executable to use for a remote code - model. + \li The path to a remote Clangd executable for a remote code model. \row \li \uicontrol {Paths to mount} - \li Host directories to \l{Specifying Paths to Mount}{mount} into the + \li Host directories to \l{Specify paths to mount}{mount} into the container, such as the project directory. \row \li \uicontrol {Search locations} - \li Where to \l{Auto-detecting Kit Items}{automatically detect} kit + \li Where to \l{Auto-detect kit items}{automatically detect} kit items. \endtable - The following sections describe the Docker device preferences in more detail. - - \section2 Selecting Docker Images - - The \uicontrol {Docker Image Selection} dialog displays a list of Docker - images in your local Docker installation. You can sort the images according - to the repository name or tag or the image ID or size. - - \image qtcreator-docker-image-selection.webp "Docker Image Selection dialog" - - Select \uicontrol {Show unnamed images} to show images that are not tagged. - - Double-click an image to select it. - - \section2 Modifying Entry Points + \section1 Modify entry points The entry point of a Docker container is specified in the container settings and started as the main process when starting the container. The entry point @@ -107,9 +134,9 @@ \uicontrol {Do not modify entry point}. However, if the entry point you specify is not a shell, \QC cannot start the container. - \section2 Specifying Paths to Mount + \section1 Specify paths to mount - You can either copy your project files into the Docker container or specify + Copy your project files into the Docker container or specify paths to them in \uicontrol {Paths to mount}. Shared mounts are restricted to locations in the host system that can end up in the same absolute location in the Docker container. On Windows, network mounts cannot be used as shared @@ -120,7 +147,7 @@ \uicontrol {Delete Line} to delete the selected path or \uicontrol Clear to delete all paths. - \section2 Auto-detecting Kit Items + \section1 Auto-detect kit items Select \uicontrol {Auto-detect Kit Items} to find kit items and create kits for the Docker device. You can search for kit items in the device's PATH or @@ -143,20 +170,32 @@ \uicontrol {List Auto-Detected Kit Items}. To remove them, select \uicontrol {Remove Auto-Detected Kit Items}. - \section1 Editing Docker Device Kits + \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker}, + {Manage Kits}{How To: Manage Kits} +*/ + +/*! + \page creator-how-to-build-run-docker.html + \previouspage creator-how-tos.html - Select \preferences > \uicontrol Kits to check - that the automatically generated kits point to the appropriate kit items. + \ingroup creator-how-to-docker + + \title Build for and run on Docker devices - To specify build settings: + \note Enable the Docker plugin to use it. + + To specify build settings for Docker images: \list 1 \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} to enable - the kit that you specified above. + \li Go to \uicontrol Projects > \uicontrol {Build & Run}, and + activate the kit for Docker devices. \endlist Select \uicontrol Run to specify run settings. Usually, you can use the default settings. + + \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker}, + {Manage Kits}{How To: Manage Kits} */ diff --git a/doc/qtcreator/src/editors/creator-code-syntax.qdoc b/doc/qtcreator/src/editors/creator-code-syntax.qdoc index f20ecadb8e..f59ba0fd94 100644 --- a/doc/qtcreator/src/editors/creator-code-syntax.qdoc +++ b/doc/qtcreator/src/editors/creator-code-syntax.qdoc @@ -9,7 +9,7 @@ \previouspage creator-how-tos.html \endif - \ingroup creator-how-to-edit + \ingroup creator-how-to-analyze \ingroup studio-how-to-code \title Check code syntax @@ -66,12 +66,9 @@ \section1 Set line annotation positions - To specify the position of the line annotations when looking at them in the - code editor, select \uicontrol {Annotation Settings} in the tooltip popup. - To specify the position where the annotations are displayed, go to \preferences > \uicontrol {Text Editor} > - \uicontrol Display > \uicontrol {Line annotations}, and then select + \uicontrol Display > \uicontrol {Line Annotations}, and then select whether to display the annotations directly next to the code, aligned to the right of the code, or in the right margin. Showing annotations between lines can be useful if there is usually not enough space to @@ -82,17 +79,11 @@ If you hide the annotations, you can move the mouse pointer over an icon to view them. - \if defined(qtcreator) - \section1 Inspect QML and JavaScript - - To inspect QML and JavaScript properties, methods, and enums, move the - cursor over them and go to \uicontrol Tools > \uicontrol {QML/JS} > - \uicontrol {Inspect API for Element Under Cursor}. + \sa {JavaScript and QML Checks} - \sa {Clangd} + \if defined(qtcreator) + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} \endif - - \sa {JavaScript and QML Checks} */ /*! @@ -760,24 +751,25 @@ \section1 Resetting the Code Model - If you change the build and run kit when you have QML files open in the code - editor, the code model might become corrupt. The following error message - indicates that this might have happened: \e{Using Qt Quick 1 code model - instead of Qt Quick 2}. + If you see the following error messages after you add a new QML module, + try building the project and then resetting the code model: + + \list + \li QML module not found. + \li Unknown Component (M300). + \endlist - To see the error message, move the mouse pointer over code that + To see an error message, move the mouse pointer over code that \QC underlines in the code editor or when you open a QML file in \QDS. To reset the code model, select \uicontrol Tools > \uicontrol {QML/JS} > \uicontrol {Reset Code Model}. + \sa {Check code syntax}, {Using QML Modules with Plugins} + \if defined(qtcreator) - If this does not help, try changing the QML emulation layer to the one that - was built with the same Qt version as the one selected in the build and run - kit. + \sa {Analyzing Code} \endif - - \sa {Check code syntax} */ /*! diff --git a/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc b/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc index f07a79e986..d8bba6edf6 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-clang-codemodel.qdoc @@ -124,54 +124,83 @@ The document outline in the \l{Outline} view is backed by clangd's document symbol support, which makes the results more reliable than before. - \sa {Code Model}, {Clangd}, {Specify clangd settings}, - {Speficy Clang tools settings}, {Use compilation databases} + \sa {Configure C++ code model}, {Specify clangd settings}, + {Specify Clang tools settings}, {Use compilation databases}, + {Code Model}, {Clangd} */ /*! - \page creator-preferences-cpp-code-model.html - \previouspage creator-reference.html - - \ingroup creator-reference-preferences-cpp + \page creator-how-to-cpp-code-model.html + \previouspage creator-how-tos.html - \title Code Model + \ingroup creator-how-to-configure-editors + \ingroup creator-how-to-projects-configure - \brief Sets global preferences for the code model. + \title Configure C++ code model - The Clang code model offers services such as code completion, syntactic and + The code model offers services such as code completion, syntactic and semantic highlighting, and diagnostics. - To configure the Clang code model globally: + To configure the C++ code model for a project: \list 1 + \li Go to \uicontrol Projects > \uicontrol {Project Settings} > + \uicontrol {C++ Code Model}. + \image qtcreator-projects-cpp-code-model.webp {C++ Code Model settings} + \li Clear \uicontrol {Use global settings}. + \li Set \uicontrol {C++ Code Model} settings for the project. + \endlist - \li Select \preferences > \uicontrol C++ > - \uicontrol {Code Model}. + \sa {Code Model} +*/ - \image qtcreator-preferences-code-model.webp {C++ Code Model preferences} +/*! + \page creator-preferences-cpp-code-model.html + \previouspage creator-reference.html + + \ingroup creator-reference-preferences-cpp - \li To instruct the code model to interpret ambiguous header files as C - language files if you develop mainly using C, select the - \uicontrol {Interpret ambiguous headers as C headers} check box. + \title Code Model - \li To process precompiled headers, deselect the - \uicontrol {Ignore precompiled headers} check box. + \brief Sets global preferences for the code model. - \li To use the built-in preprocessor to show the - pre-processed source file in the editor, select - \uicontrol {Use built-in preprocessor to show pre-processed files}. + The code model offers services such as code completion, syntactic and + semantic highlighting, and diagnostics. + To configure the C++ code model globally, go to \preferences > + \uicontrol C++ > \uicontrol {Code Model}. + + \image qtcreator-preferences-code-model.webp {C++ Code Model preferences} + + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Interpret ambiguous headers as C headers} + \li Instructs the code model to interpret ambiguous header files as C + language files. Select this checkbox if you develop mainly using C. + \row + \li \uicontrol {Ignore precompiled headers} + \li Clear this checkbox to process precompiled headers. + \row + \li \uicontrol {Use built-in preprocessor to show pre-processed files} + \li Uses the built-in preprocessor to show the + pre-processed source file in the editor. + \row + \li \uicontrol {Do not index files greater than} \li To avoid out-of-memory crashes caused by indexing huge source files that are typically auto-generated by scripts or code, the size of - files to index is limited to 5MB by default. To adjust the limit, - edit the value for the \uicontrol {Do not index files greater than} - check box. To index all files, deselect the check box. + files to index is limited to 5MB by default. - \li To ignore files that match wildcard patterns, select the - \uicontrol {Ignore files} check box and enter each wildcard pattern - on a separate line in the field. - - \endlist + To index all files, clear the checkbox. + \row + \li \uicontrol {Ignore files} + \li To ignore files that match wildcard patterns, enter each wildcard + pattern on a separate line in the field. + \endtable \section1 Inspect preprocessed C++ code @@ -186,7 +215,8 @@ this action also expands all \c {"#include <foo.h>"} statements to their actual contents. - \sa {Specify clangd settings}, {Clang Code Model}, {Clangd} + \sa {Configure C++ code model}, {Specify clangd settings}, + {Clang Code Model}, {Clangd} */ /*! diff --git a/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc b/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc index 0e8bba269a..9bbfe729d9 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-coding-edit-mode.qdoc @@ -111,7 +111,7 @@ \row \li \inlineimage icons/live-preview.png \li Preview changes to QML code live in your application. - \li \l {Previewing on Desktop} + \li \l {Preview a QML file on desktop} \row \li \inlineimage icons/debugger_singleinstructionmode.png \li Run Clang-Tidy or Clazy to analyze the currently open file. @@ -184,7 +184,8 @@ \title Move between files - The editor toolbar shows the file that is currently open (1) in the editor. + The editor toolbar shows the name of the file that is currently open (1) in + the editor. \image qtcreator-editor-open-files.webp {Current file shown on Edit mode toolbar} @@ -416,18 +417,18 @@ \image qtcreator-options-texteditor-behavior-file-encodings.png {File encoding preferences} - Qt 5 and Qt 6 require UTF-8 encoded source files, and therefore the default + Qt requires UTF-8 encoded source files, and therefore the default encoding is set to \uicontrol UTF-8. - Detecting the correct encoding is tricky, so \QC will not try to do so. - Instead, it displays the following error message when you try to edit a file - that is not UTF-8 encoded: \uicontrol {Error: Could not decode "filename" with + + If you try to edit a file that is not UTF-8 encoded, you see the following + error message: \uicontrol {Error: Could not decode "filename" with "UTF-8"-encoding. Editing not possible.} To resolve the issue, use a file conversion tool to convert the file - encoding to UTF-8 when developing Qt 5 applications. Otherwise, conversion - of string constants to QString might not work as expected. + encoding to UTF-8. Otherwise, conversion of string constants to + QString might not work as expected. - If you develop only Qt 4 applications or other than Qt applications, you + If you do not develop Qt applications, you can set other encoding options as the default encoding. Select the \uicontrol System option to use the file encoding used by your system. diff --git a/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc b/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc index 8c01b9cfef..27a632955c 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc @@ -62,7 +62,8 @@ \section1 Adding Language Servers - \QC adds a Python language server by default. + \QC adds a \l{Configure Python language servers}{Python language server} by + default. Also, it offers to install language servers for JSON and YAML files when you open them in the editor if it can find the @@ -71,18 +72,22 @@ \image qtcreator-language-server-json.webp {Prompt to install JSON language server} - Add a Java language server for \l{Connecting Android Devices} - {Android development}. For other languages, add generic stdIO language - servers. + \l{Add a Java language server} for \l{Developing for Android} + {Android development}. For other languages, + \l{Add generic language servers}{add generic stdIO language servers}. To add language servers, go to \preferences > \uicontrol {Language Client} and select \uicontrol Add. \image qtcreator-language-client-options-java.png {Java language server preferences} - To enable a language server, select the check box next to the language + To enable a language server, select the checkbox next to the language server name and set server preferences. + To turn on \l{Turn on \QMLLS}{\QMLLS}, go to + \preferences > \uicontrol {Qt Quick} > \uicontrol {QML/JS Editing} and + select \uicontrol {Enable \QMLLS}. + To remove language servers from the list, select \uicontrol Delete. \section1 Supported Locator Filters @@ -218,23 +223,23 @@ \ingroup creator-how-to-lsp - \title Turn on QML Language Server + \title Turn on \QMLLS - Since Qt 6.4, the QML language server offers code completion and + Since Qt 6.4, \QMLLS offers code completion and issues warnings for QML. To use it, go to \preferences > \uicontrol {Qt Quick} > \uicontrol {QML/JS Editing} and select - \uicontrol {Enable QML Language Server}. + \uicontrol {Enable \QMLLS}. - By default, enabling the QML language server will only enable warning messages + By default, enabling \QMLLS will only enable warning messages and code completion, while advanced features such as renaming and finding usages will be handled by the embedded code model. - To disable the embedded code model and use the QML language server for everything, - select \uicontrol {Use QML Language Server advanced features}. + To disable the embedded code model and use \QMLLS for everything, + select \uicontrol {Use \QMLLS advanced features}. - Also, \QC tries to use the QML language server shipped with - the Qt version in your current kit. To override that behavior and always use the - QML language server of the highest registered Qt version, select - \uicontrol {Use QML Language Server from latest Qt version}. + Also, \QC tries to use \QMLLS shipped with + the Qt version in your current kit. To override that behavior and always use + \QMLLS of the highest registered Qt version, select + \uicontrol {Use \QMLLS from latest Qt version}. \image qtcreator-qml-js-editing.webp {QML/JS Editing preferences} diff --git a/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc b/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc index eab661647f..d739bd3445 100644 --- a/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc +++ b/doc/qtcreator/src/editors/creator-only/creator-locator.qdoc @@ -261,6 +261,16 @@ \endlist + \section1 Hiding Long Paths + + To hide the common part of absolute paths in the locator: + + \list 1 + \li Go to \preferences > \uicontrol Environment > \uicontrol Locator. + \li Select \uicontrol {Show Paths in Relation to Active Project} to + show relative paths. + \endlist + \sa {Navigate with locator}, {Search}{How To: Search}, {Perform calculations}, {Locator} */ diff --git a/doc/qtcreator/src/external-resources/external-resources-qds.qdoc b/doc/qtcreator/src/external-resources/external-resources-qds.qdoc index d5b7fcf1bd..2a340b9ea9 100644 --- a/doc/qtcreator/src/external-resources/external-resources-qds.qdoc +++ b/doc/qtcreator/src/external-resources/external-resources-qds.qdoc @@ -69,3 +69,39 @@ \externalpage https://www.qt.io/download \title Try Qt */ +/*! + \externalpage https://doc.qt.io/qt-5/custom-material-reference.html + \title Qt Quick 3D Custom Material Reference +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-arealight.html + \title AreaLight +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-shaderinfo.html + \title ShaderInfo +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-bufferblit.html + \title BufferBlit +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-cullmode.html + \title CullMode +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-depthinput.html + \title DepthInput +*/ +/*! + \externalpage https://doc.qt.io/qt-5/qml-qtquick3d-renderstate.html + \title RenderState +*/ +/*! + \externalpage https://doc.qt.io/qt/i18n-source-translation.html#mark-strings-for-translation + \title Mark Strings for Translation +*/ +/*! + \externalpage https://doc.qt.io/qt/linguist-id-based-i18n.html + \title Text ID based translations +*/ diff --git a/doc/qtcreator/src/external-resources/external-resources.qdoc b/doc/qtcreator/src/external-resources/external-resources.qdoc index 3eceb28e56..05cba5ba53 100644 --- a/doc/qtcreator/src/external-resources/external-resources.qdoc +++ b/doc/qtcreator/src/external-resources/external-resources.qdoc @@ -2,6 +2,26 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! + \externalpage https://www.perforce.com/manuals/cmdref/Content/CmdRef/P4CONFIG.html + \title Perforce: P4CONFIG +*/ +/*! + \externalpage https://doc.qt.io/qt-6/qtdesigner-manual.html + \title Qt Widgets Designer Manual +*/ +/*! + \externalpage https://doc.qt.io/qt-6/designer-using-custom-widgets.html + \title Using Custom Widgets with Qt Widgets Designer +*/ +/*! + \externalpage https://doc.qt.io/Boot2Qt/index.html + \title \B2Q: Documentation +*/ +/*! + \externalpage https://doc.qt.io/Boot2Qt/b2qt-requirements-x11.html#setting-up-usb-access-to-embedded-devices + \title \B2Q: Setting Up USB Access to Embedded Devices +*/ +/*! \externalpage https://doc.qt.io/qt/qtqml-index.html \title Qt Qml */ @@ -18,6 +38,10 @@ \title \QMCU - Supported Target Platforms */ /*! + \externalpage https://doc.qt.io/QtForMCUs/qtul-prerequisites.html + \title \QMCU - Prerequisites +*/ +/*! \externalpage https://doc.qt.io/QtForMCUs/qtul-getting-started-renesas.html \title Getting Started on Renesas */ @@ -30,12 +54,16 @@ \title Getting Started on NXP */ /*! + \externalpage https://doc.qt.io/QtForMCUs/qtul-getting-started-on-infineon.html + \title Getting Started on Infineon +*/ +/*! \externalpage https://doc.qt.io/QtForMCUs/qtul-getting-started-windows.html \title Getting Started on Windows */ /*! - \externalpage https://adoptopenjdk.net/ - \title AdoptOpenJDK + \externalpage https://adoptium.net/ + \title Adoptium OpenJDK */ /*! \externalpage http://openjdk.java.net @@ -185,3 +213,19 @@ \externalpage https://doc-snapshots.qt.io/applicationmanager-dev/cmake-qt6-am-create-installable-package.html \title qt6_am_create_installable_package */ +/*! + \externalpage https://valgrind.org/info/tools.html + \title Valgrind's Tool Suite +*/ +/*! + \externalpage https://valgrind.org/docs/manual/quick-start.html#quick-start.interpret + \title Interpreting Memcheck's Output +*/ +/*! + \externalpage https://valgrind.org/docs/manual/manual-core.html#manual-core.suppress + \title Suppressing Errors +*/ +/*! + \externalpage https://www.openssh.com/ + \title OpenSSH +*/ diff --git a/doc/qtcreator/src/howto/creator-external-tools.qdoc b/doc/qtcreator/src/howto/creator-external-tools.qdoc index 13927f3d67..fa58a1e80a 100644 --- a/doc/qtcreator/src/howto/creator-external-tools.qdoc +++ b/doc/qtcreator/src/howto/creator-external-tools.qdoc @@ -77,7 +77,7 @@ {build environment} or \l {Specify the run environment} {run environment} of the active project. Select the build or run environment if the system environment does not have the necessary - PATH settings to find the tool chain, for example. + PATH settings to find the toolchain, for example. \else \li In the \uicontrol {Base environment} field, use the default settings. \endif @@ -209,6 +209,10 @@ \uicontrol External > \uicontrol {Qt Quick} > \uicontrol {QML Runtime}. \sa {Use external tools} + + \if defined(qtcreator) + \sa {Design UIs}{How To: Design UIs}, {UI Design} + \endif */ /*! diff --git a/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc b/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc index c5cf673347..17d660c4d6 100644 --- a/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc +++ b/doc/qtcreator/src/howto/creator-how-to-view-images.qdoc @@ -43,6 +43,10 @@ Select \uicontrol {Set as Default} to use the current settings for the background and outline modes and fitting images to screen as default values for the image viewer. + + \if defined(qtcreator) + \sa {Design UIs}{How To: Design UIs}, {UI Design} + \endif */ /*! @@ -67,4 +71,8 @@ You can then use QIcon::addPixmap() to add the pixmaps to icons in different modes and states. + + \if defined(qtcreator) + \sa {Design UIs}{How To: Design UIs}, {UI Design} + \endif */ diff --git a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc index f05c16181a..f6006e8ede 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc @@ -359,10 +359,6 @@ found by the code based test frameworks and are registered as test with the build system. - If a test takes more than a minute to execute, the default timeout might - stop the test execution. To increase the timeout, go to \preferences > - \uicontrol {Testing} > \uicontrol General. - \section1 Select tests to run The \uicontrol Tests view shows all the tests found for the currently active @@ -501,7 +497,7 @@ the current project. \row \li \uicontrol {Timeout} - \li The maximum time in seconds to execute a test case. + \li Set a maximum time in seconds to execute a test case. \row \li \uicontrol {Reset Cached Choices} \li Sometimes, \QC cannot deduce which executable or run configuration to @@ -751,7 +747,7 @@ \li Re-run tests, as determined by \uicontrol {Repetition mode}. Set the maximum number of times for repeating a test in \uicontrol {Count}. \row - \li \uicontrol {Run in parallel} + \li \uicontrol {Run in Parallel} \li Run the tests in parallel using the specified number of \uicontrol {Jobs}. In \uicontrol {Test load}, limit the parallel execution. CTest will not start a new test if it would cause the @@ -853,8 +849,7 @@ \section1 Blacklisting Tests - Since Qt 5.4, you can add a BLACKLIST file for tests. It is mainly used - internally by the Qt CI system. + A BLACKLIST file for tests is mainly used internally by the Qt CI system. \table \header diff --git a/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc b/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc index fbc885df05..a0e9129c6b 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-cli.qdoc @@ -93,7 +93,7 @@ \row \li -installsettingspath <path> \li Override the default path from where user-independent settings are read - (for example written by the installer). + (for example, those written by the installer). \row \li -temporarycleansettings, -tcs @@ -104,6 +104,10 @@ \li -language <locale> \li Set the UI language. + Use a lowercase, two-letter + \l {https://www.iso.org/iso-639-language-codes.html} + {ISO 639 language code}, such as \e de, \e en, or \e fr. + \row \li -test <plugin>[,testfunction[:testdata]] ... \li For \QC plugin developers: run the plugin's tests using a diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc index 8bfb773a40..81bc78e307 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-how-to-find-settings-files.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -7,9 +7,9 @@ \ingroup creator-how-to-use - \title Find settings files + \title Reset \QC settings - \QC creates the following files and directories: + To reset all \QC settings, remove the settings files that it creates: \list \li QtCreator.db @@ -29,4 +29,32 @@ \li On Windows, look in \c {%appdata%\QtProject} and \c {%localappdata%\QtProject}. \endlist + + To check whether the settings are causing a problem before resetting them, + start \QC from the command line with options. + + \section1 Override the default settings path + + To override the default path where user settings are stored, enter: + + \badcode + qtcreator -settingspath <path> + \endcode + + To override the default path from where user-independent settings are read + (for example, those written by the installer), enter: + + \badcode + qtcreator -installsettingspath <path> + \endcode + + \section1 Start \QC with temporary clean settings + + To use clean settings that are deleted when you quit \QC, enter: + + \badcode + qtcreator -tcs + \endcode + + \sa {Run Qt Creator from the command line} */ diff --git a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc index 1b545943e3..baf079c08f 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-how-tos.qdoc @@ -80,6 +80,75 @@ \generatelist creator-how-to-design + \section1 Develop for Devices + + Install the toolchain for building applications for the targeted + embedded or mobile platform on the computer, and use \QOI to + install Qt libraries that are built for the platform. Then add a + kit with the toolchain and the Qt version for the device's architecture. + When possible, \QOI creates suitable kits for you. Connect the devices + to the computer to run, debug, and analyze applications on them. + + \section2 Android + + Install \l {Qt for Android} and Android tools, and connect Android devices to + the computer. + + \generatelist creator-how-to-android + + \section2 Bare Metal + + Run and debug applications on small Linux devices that are not supported + by the remote Linux device plugin by using GDB or a hardware debugger. + + \generatelist creator-how-to-bare-metal + + \section2 \B2Q + + Run, debug, and analyze applications on \l{\B2Q: Documentation}{\B2Q} + devices. + + \generatelist creator-how-to-b2qt + + \section2 Docker + + Create \e {Docker devices} from \e {Docker images} and use them to build, + run, and debug applications. + + \generatelist creator-how-to-docker + + \section2 iOS + + Install \l {Qt for iOS} and Xcode, and connect iOS devices to the computer. + + \generatelist creator-how-to-ios + + \section2 MCUs + + Install \l {Qt for MCUs}, and connect microcontrollers to the computer. + + \generatelist creator-how-to-mcu + + \section2 QNX Neutrino + + Install \l {Qt for QNX}, and connect QNX Neutrino devices to the computer. + + \generatelist creator-how-to-qnx + + \section2 Remote Linux + + Add kits for toolchains for building applications for generic Linux + devices, and connect the devices to the computer. + + \generatelist creator-how-to-remote-linux + + \section2 WebAssembly + + Install \l{Qt for WebAssembly} to build applications for the web and run them + in a web browser. + + \generatelist creator-how-to-webassembly + \section1 Edit Code The code editor offers useful features for editing C++ and QML code, such @@ -115,7 +184,7 @@ \QC groups build and run specific settings as kits to make cross-platform development easier. Each kit consists of a set of values that define one - environment, such as a device, tool chain, Qt version, and debugger command + environment, such as a device, toolchain, Qt version, and debugger command to use. \generatelist creator-how-to-manage-kits @@ -423,6 +492,12 @@ \uicontrol {Find References to Symbol Under Cursor}. \endlist + \section1 Inspect QML and JavaScript + + To inspect QML and JavaScript properties, methods, and enums, place the + cursor over them and go to \uicontrol Tools > \uicontrol {QML/JS} > + \uicontrol {Inspect API for Element Under Cursor}. + \section1 Move between QML and C++ To move to the C++ implementation of a QML type in the code editor, place the @@ -433,7 +508,8 @@ \li Go to \uicontrol {Follow Symbol Under Cursor} in the context menu. \endlist - \sa {Edit Code}{How To: Edit Code}, {Edit Mode}, {Navigate with locator} + \sa {Edit Code}{How To: Edit Code}, {Clangd}, {Edit Mode}, + {Navigate with locator} */ /*! diff --git a/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc b/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc index 4284085e72..9aaf0506f2 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-squish.qdoc @@ -2,82 +2,66 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-autotest.html - \page creator-squish.html - \nextpage creator-advanced.html + \page creator-how-to-connect-squish-server.html + \previouspage creator-how-tos.html - \title Using Squish + \ingroup creator-how-to-test - \l{https://www.qt.io/product/quality-assurance/squish}{Squish} is an automated GUI - testing framework for testing Android, iOS, Java, \macos, Qt, Tk, Windows, and - XView applications, as well as HTML-based web applications running in - browsers, such as Apple Safari, Mozilla Firefox, Google Chrome, and - Microsoft Internet Explorer and Edge. + \title Connect to Squish Server - The experimental Squish plugin integrates Squish into \QC. You can: - - \list - \li Open existing Squish test suites. - \li Create new test suites and test cases. - \li Record test cases (in a very limited way compared to what you can do - inside the Squish IDE). - \li Use Squish Runner and Server to run test suites or cases and view - the results in the \uicontrol Squish \l{View output}{output}. - \li Set breakpoints before running tests to stop at certain locations and - inspect the local variables, similarly to when debugging a test. - \endlist - - When running test suites or cases, the Squish Runner instructs the Squish - Server to start the application under test (AUT). The server can be running - on multiple machines, and the AUT can be located on a different path on each - of them. Therefore, you must either map AUTs to their corresponding paths or - specify AUT paths to search from in the server settings. - - In addition, you can test an already running application by attaching to it. - This enables you to test your application using a Squish Server running on - another machine. However, you can have only one server attached to your - application at a time. Also, the attached application is not closed when the - test case is completed. - - To use the plugin, you must download and install Squish, create a connection - to the Squish Server, and specify AUTs to run. - - \note Enable the Squish plugin to use it. - - \section1 Specifying a Squish Server - - To specify a Squish Server to run: + To create a connection to Squish Server: \list 1 \li Select \preferences > \uicontrol Squish. - \image qtcreator-squish-preferences.png "Squish general preferences" - \li In the \uicontrol {Squish path} field, specify the path to the Squish + \image qtcreator-squish-preferences.png {Squish general preferences} + \li In \uicontrol {Squish path}, specify the path to the Squish installation directory. - \li In the \uicontrol {License path} field, specify the path to your + \li In \uicontrol {License path}, specify the path to your Squish license file if it is not located in your home folder. For example, if you have a global installation with several users, where the license key is installed in the global folder. - \li Select the \uicontrol {Local server} check box to use a locally - installed \c {squishserver.exe}. To use a server running in another - machine, deselect the check box and specify the server address in the - \uicontrol {Server host} field and the port number in the - \uicontrol {Server port} field. If no port is specified, \QC starts + \li Select \uicontrol {Local server} to use a locally + installed \c {squishserver.exe}. To use a server running on another + computer, clear the checkbox and specify the server address in the + \uicontrol {Server host} and the port number in the + \uicontrol {Server port}. If no port is specified, \QC starts \c squishserver in a way that enables it to automatically select an open port. - \li Select the \uicontrol {Verbose log} check box to include additional + \li Select \uicontrol {Verbose log} to include additional logging levels in the log output. - \li Select the \uicontrol {Minimize IDE} check box to automatically + \li Select \uicontrol {Minimize IDE} to automatically minimize \QC when running or recording test cases. \endlist - \section1 Specifying AUTs + \sa {Create Squish test suites}, {Enable and disable plugins}, + {Manage Squish test suites and cases}, {Select Squish AUTs}, {Squish} +*/ + +/*! + \page creator-how-to-select-squish-auts.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-test + + \title Select Squish AUTs - To specify applications to test using Squish, select \uicontrol {Tools} > + To select applications to test using Squish, go to \uicontrol {Tools} > \uicontrol {Squish} > \uicontrol {Server Settings}. - \image qtcreator-squish-server-settings.png "Squish Server Settings" + \image qtcreator-squish-server-settings.png {Squish Server Settings} + + When running test suites or cases, the Squish Runner instructs the Squish + Server to start the application under test (AUT). The server can be running + on multiple computers, and the AUT can be located on a different path on each + of them. Therefore, you must either map AUTs to their corresponding paths or + specify AUT paths to search from in the server settings. + + To test an already running application using a Squish Server running on + another computer, attach to the application. You can attach only one server + to your application at a time. The attached application is not closed when + the test case is completed. - \section2 Mapping AUTs + \section1 Map AUTs To specify the path to an AUT to run, select \uicontrol {Mapped AUTs} > \uicontrol Add and locate the AUT. @@ -88,13 +72,13 @@ Mapping AUTs prevents the server from accidentally executing the wrong AUT if two different executables have the same name, as the server executes the - first matching AUT it finds in the \uicontrol {AUT Paths} list. + first matching AUT it finds in \uicontrol {AUT Paths}. To change the path to the selected AUT, select \uicontrol {Edit}. To remove the mapping to the selected AUT, select \uicontrol {Remove}. - \section2 Specifying AUT Paths + \section1 Specify AUT paths To specify a path to search AUTs from, select \uicontrol {AUT Paths} > \uicontrol Add. @@ -107,32 +91,60 @@ To remove the selected AUT path, select \uicontrol {Remove}. - \section2 Adding Attachable AUTs + \section1 Add attachable AUTs To specify the path to a running AUT, select \uicontrol {Attachable AUTs} > \uicontrol Add. In the \uicontrol {Add Attachable AUT} dialog, specify a connection to a running application to register an attachable AUT. - \image qtcreator-squish-server-settings-add-attachable-aut.png "Add Attachable AUT dialog" + \image qtcreator-squish-server-settings-add-attachable-aut.png {Add Attachable AUT dialog} To change the connection to the selected AUT, select \uicontrol {Edit}. To remove the connection to the selected AUT, select \uicontrol {Remove}. - \section1 Managing Test Suites and Cases + \section1 Specify settings for running tests - You can manage Squish test suites and cases in the \uicontrol Squish - \l {Show and hide sidebars}{view}. + To specify settings for running tests: - \image qtcreator-squish-view.png "Squish sidebar view" + \list + \li In \uicontrol {Maximum startup time}, set the maximum time + to wait for the AUT to start before throwing an error. + \li In \uicontrol {Maximum response time}, set the maximum time + to wait for the AUT to respond before throwing an error. + \li In \uicontrol {Maximum post-mortem wait time}, set the + maximum time to wait after the main AUT has exited. This is useful + for AUTs invoked through launcher applications, such as shell scripts + or batch files. + \li Select \uicontrol {Animate mouse cursor} to animate + the mouse cursor when playing back a test. + \endlist + + \sa {Connect to Squish Server}, {Create Squish test suites}, + {Enable and disable plugins}, {Manage Squish test suites and cases}, + {Squish} +*/ + +/*! + \page creator-how-to-manage-squish-test-suites.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-test + + \title Manage Squish test suites and cases + + Manage Squish test suites and cases in the \uicontrol Squish + \l {Show and hide sidebars}{sidebar view}. + + \image qtcreator-squish-view.png {Squish sidebar view} To show existing test suites in \uicontrol {Test Suites}, select \uicontrol {Open Squish Suites} in the context menu. - \image qtcreator-squish-view-open-squish-suites.png "Open Squish Test Suites dialog" + \image qtcreator-squish-view-open-squish-suites.png {Open Squish Test Suites dialog} - You can open the \uicontrol {Squish Test Suite} wizard for creating a new - test suite by selecting \uicontrol {Create New Test Suite} in the context + To open the \uicontrol {Squish Test Suite} wizard for creating a new + test suite, select \uicontrol {Create New Test Suite} in the context menu. To add a test case to a test suite, select it and then select @@ -148,73 +160,40 @@ Double-click a test suite in \uicontrol {Test Suites} to open the \c {suite.conf} configuration file for editing. - \section2 Creating Test Suites - - To create a new test suite: - - \list 1 - \li Select \uicontrol File > \uicontrol {New Project} - > \uicontrol {Squish} > \uicontrol {Squish Test Suite} > - \uicontrol Choose. - \image qtcreator-squish-create-test-suite.png "Create Squish Test Suite wizard" - \li On the \uicontrol {Location} page, in \uicontrol {Test Suite Name}, - enter a name for the test suite. - \image qtcreator-squish-create-test-suite-location.png "Location page" - \li In \uicontrol {Test Suite folder's parent folder}, enter the path to - the folder to create the test suite folder, and then select - \uicontrol Next. - \li On the \uicontrol Setup page, select the GUI toolkit used by the AUT, - and then select \uicontrol Next. - \image qtcreator-squish-create-test-suite-setup.png "Setup page" - Currently, only desktop GUI toolkits are supported. - \li On the \uicontrol {Script Language} page, select the scripting - language to use for the test suite's test script, and then select - \uicontrol Next. - \image qtcreator-squish-create-test-suite-language.png "Languages page" - \li On the \uicontrol {AUT} page, select the AUT to test, and then select - \uicontrol Next. - \image qtcreator-squish-create-test-suite-aut.png "AUT page" - \li On the \uicontrol {Summary} page review the test suite settings, and - then select \uicontrol Finish to create the test suite. - \endlist - - The test suite is listed in \uicontrol {Test Suites} in the \uicontrol Squish - sidebar view. - - \section2 Recording Test Cases + \section1 Record test cases Squish records tests using the scripting language that you specified for the test suite. Recordings are made into existing test cases. In \uicontrol {Test Suites}, select the \inlineimage icons/recordfill.png - (\uicontrol {Record Test Case}) button next to the test case name. The AUT - that you selected for the test suite is displayed and you can start recording - the test case. + (\uicontrol {Record Test Case}) button next to the test case name. The + application under test (AUT) that you selected for the test suite is + displayed and you can start recording the test case. - \image qtcreator-squish-control-bar-record-test-case.png "Squish control bar for recording test cases" + \image qtcreator-squish-control-bar-record-test-case.png {Squish control bar for recording test cases} When you are done, select the \inlineimage icons/stop_small.png (\uicontrol {Stop}) button in the \uicontrol {Control Bar}. - You can edit recorded test scripts or copy parts of them into manually + Edit recorded test scripts or copy parts of them into manually created test scripts. - \image qtcreator-squish-test-script-edit.png "A test script open in the editor" + \image qtcreator-squish-test-script-edit.png {A test script open in the editor} - \section2 Running Test Suites + \section1 Run test suites - You can run a recorded test case to have Squish repeat all the actions that + Run a recorded test case to have Squish repeat all the actions that you applied when recording the test, but without the pauses that humans are prone to but which computers don't need. To run a test case, select the \inlineimage icons/run_small.png (\uicontrol {Run}) button next to the test case in \uicontrol {Test Suites}. - \image qtcreator-squish-control-bar-run-test-case.png "Squish control bar for running test cases" + \image qtcreator-squish-control-bar-run-test-case.png {Squish control bar for running test cases} While the test is running, you can view test results as well as interrupt and stop tests in the \uicontrol {Control Bar}. - \section2 Mapping Symbolic Names + \section1 Map symbolic names When Squish records a test, it uses \e {symbolic names} to identify the UI elements. Symbolic names are stored in an object map that can be either @@ -237,7 +216,7 @@ (\uicontrol {Object Map}) button next to the test suite in \uicontrol {Test Suites}. - \image qtcreator-squish-symbolic-names.png "Symbolic Names view" + \image qtcreator-squish-symbolic-names.png {Symbolic Names view} You can filter the symbolic names in the \uicontrol {Symbolic Names} view. To edit a symbolic name or the names or values of its properties, @@ -253,49 +232,87 @@ property, select \inlineimage icons/jumpto.png . - \section2 Inspecting Local Variables + \section1 Inspect local variables If you set breakpoints in the test code before running the test, the test execution is automatically interrupted when a breakpoint is hit. You can inspect the contents of local variables in the \uicontrol {Squish Locals} view. - \image qtcreator-squish-locals.png "Squish Locals view" + \image qtcreator-squish-locals.png {Squish Locals view} Use the \uicontrol {Step Into}, \uicontrol {Step Over}, and \uicontrol {Step Out} buttons in the \uicontrol Squish debugging view to step through the code. - \image qtcreator-squish-debugging-view.png "Squish debugging view" + \image qtcreator-squish-debugging-view.png {Squish debugging view} - \section2 Specifying Settings for Running Tests + \sa {Connect to Squish Server}, {Create Squish test suites}, + {Enable and disable plugins}, {Select Squish AUTs}, {Squish} +*/ - To specify settings for running tests, select \uicontrol Tools > - \uicontrol Squish > \uicontrol {Server Settings}: +/*! + \page creator-how-to-create-squish-test-suites.html + \previouspage creator-how-tos.html - \list - \li In the \uicontrol {Maximum startup time} field, set the maximum time - to wait for the AUT to start before throwing an error. - \li In the \uicontrol {Maximum response time} field, set the maximum time - to wait for the AUT to respond before throwing an error. - \li In the \uicontrol {Maximum post-mortem wait time} field, set the - maximum time to wait after the main AUT has exited. This is useful - for AUTs invoked through launcher applications, such as shell scripts - or batch files. - \li Select the \uicontrol {Animate mouse cursor} check box to animate - the mouse cursor when playing back a test. + \ingroup creator-how-to-test + + \title Create Squish test suites + + To create a new test suite: + + \list 1 + \li Go to \uicontrol File > \uicontrol {New Project}. + \li Select \uicontrol {Squish} > \uicontrol {Squish Test Suite} > + \uicontrol Choose. + \image qtcreator-squish-create-test-suite.png {Create Squish Test Suite wizard} + \li On the \uicontrol {Location} page, in \uicontrol {Test Suite Name}, + enter a name for the test suite. + \image qtcreator-squish-create-test-suite-location.png {Location page} + \li In \uicontrol {Test Suite folder's parent folder}, enter the path to + the folder to create the test suite folder, and then select + \uicontrol Next. + \li On the \uicontrol Setup page, select the GUI toolkit used by the + application under test (AUT), and then select \uicontrol Next. + \image qtcreator-squish-create-test-suite-setup.png {Setup page} + Currently, only desktop GUI toolkits are supported. + \li On the \uicontrol {Script Language} page, select the scripting + language to use for the test suite's test scripts, and then select + \uicontrol Next. + \image qtcreator-squish-create-test-suite-language.png {Languages page} + \li On the \uicontrol {AUT} page, select the AUT to test, and then select + \uicontrol Next. + \image qtcreator-squish-create-test-suite-aut.png {AUT page} + \li On the \uicontrol {Summary} page, review the test suite settings, and + then select \uicontrol Finish to create the test suite. \endlist - \section1 Viewing Test Results + The test suite is listed in \uicontrol {Test Suites} in the \uicontrol Squish + sidebar view. + + \sa {Connect to Squish Server}, {Manage Squish test suites and cases}, {Enable and disable plugins}, + {Select Squish AUTs}, {Squish} +*/ + +/*! + \page creator-reference-squish-output.html + \previouspage creator-reference.html + + \ingroup creator-reference-output-views + + \title Squish + + \brief View Squish test, runner, and server logs. Squish uses compare, verify, and exception functions to record the results of - tests applied to a running AUT in the test log as \e {passes} or \e {fails}. - In addition, any kind of test results can be recorded in the test log. + tests applied to a running application under test (AUT) in the test log as + \e {passes} or \e {fails}. In addition, any kind of test results can be + recorded in the test log. - You can view the test log in the \uicontrol Squish output, + To view the test log, go to the \uicontrol Squish output, \uicontrol {Test Results} tab. - \image qtcreator-squish-output-test-results.png "Test Results output" + \image qtcreator-squish-output-test-results.png {Test Results output} The \uicontrol Result column displays the time when each test run started and finished, log information and warnings, and test result status: @@ -314,12 +331,14 @@ the type of the operation that was performed: comparison, verification, or exception. - \section1 Viewing Squish Runner and Server Logs + \section1 View Squish runner and server logs - You can view the Squish Runner and Server logs in the \uicontrol Squish + To view the Squish Runner and Server logs, go to the \uicontrol Squish output, \uicontrol {Runner/Server Log} tab. - \image qtcreator-squish-output-runner-server-log.png "Runner and Server Log output" + \image qtcreator-squish-output-runner-server-log.png {Runner and Server Log output} - \sa {Enable and disable plugins} + \sa {Connect to Squish Server}, {Create Squish test suites}, + {Enable and disable plugins}, {Manage Squish test suites and cases}, + {Select Squish AUTs}, {View output} */ diff --git a/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc b/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc index beadc0eb86..967031f69b 100644 --- a/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc +++ b/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc @@ -18,14 +18,6 @@ \section1 General Questions - - \b {How do I reset all \QC settings?} - - Remove the settings files created by \QC. - - For more information about where the files are located on each supported - platform, see \l {Find settings files}. - \b {\QC comes with \MinGW, should I use this version with Qt?} Use the version that was built against the Qt version. @@ -41,15 +33,6 @@ This is especially relevant for the \macos where \c {/usr/local/bin} might not be in the path when \QC is started. - \b {How do I change the interface language for \QC?} - - \QC has been localized into several languages. If the system - language is one of the supported languages, it is automatically selected. - To change the language, select \preferences > - \uicontrol Environment and select a language in the \uicontrol Language - field. Select \uicontrol {Restart Now} to restart \QC and have the change - take effect. - \b {Has a reported issue been addressed?} You can look up any issue in the @@ -138,14 +121,10 @@ \b {The Qt API Reference Documentation is missing and context help does not find topics. What can I do?} - \QC comes fully integrated with Qt documentation and examples using - the Qt Help plugin. The integrated Qt Reference Documentation is available - for Qt 4.4 and later. \QC and other Qt deliverables have - documentation as .qch files. All the documentation is accessible in the - \uicontrol Help mode. + Install a Qt version and Qt documentation with \QOI. - To view the documentation that is available and to add documentation, - select \preferences > \uicontrol Help > + To view the installed documentation (.qch files) and to add documentation, + go to \preferences > \uicontrol Help > \uicontrol Documentation. For more information, see \l{Add external documentation}. @@ -164,12 +143,12 @@ You must use Python version 2.6 or 2.7. - For more information on setting up debugger, see \l{Setting Up Debugger}. + For more information, see \l{Supported Native Debuggers}. \b {How do I generate a core file in \QC?} To trigger the GDB command that generates a core file while debugging, - select \uicontrol View > \uicontrol Views > \l {Debugger Log}. + go to \uicontrol View > \uicontrol Views > \l {Debugger Log}. In the \uicontrol Command field, type \c gcore and press \key Enter. The core file is created in the current working directory. You can specify another location for the file, including a relative or absolute path, as an diff --git a/doc/qtcreator/src/howto/creator-only/qtcreator-how-to-change-ui-language.qdoc b/doc/qtcreator/src/howto/creator-only/qtcreator-how-to-change-ui-language.qdoc new file mode 100644 index 0000000000..913b1b6fa9 --- /dev/null +++ b/doc/qtcreator/src/howto/creator-only/qtcreator-how-to-change-ui-language.qdoc @@ -0,0 +1,38 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-how-to-change-ui-language.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-ui + + \title Change the UI language + + \QC has been localized into several languages. If the system + language is one of the supported languages, it is automatically selected. + + To change the language: + + \list 1 + \li Go to \preferences > \uicontrol Environment. + \li In \uicontrol Language, select a language. + \li Select \uicontrol OK. + \li Select \uicontrol {Restart Now} to restart \QC and have the change + take effect. + \endlist + + \section1 Set the language from the command line + + To set the UI language when you start \QC from the command line, enter: + + \badcode + qtcreator -language <locale> + \endcode + + Use a lowercase, two-letter + \l {https://www.iso.org/iso-639-language-codes.html} + {ISO 639 language code}, such as \e de, \e en, or \e fr. + + \sa {Run Qt Creator from the command line} +*/ diff --git a/doc/qtcreator/src/howto/creator-sessions.qdoc b/doc/qtcreator/src/howto/creator-sessions.qdoc index 318502e54c..0f455cbc0f 100644 --- a/doc/qtcreator/src/howto/creator-sessions.qdoc +++ b/doc/qtcreator/src/howto/creator-sessions.qdoc @@ -60,7 +60,7 @@ To manage sessions, select \uicontrol File > \uicontrol Sessions > \uicontrol Manage. - \image qtcreator-session-manager.png + \image qtcreator-session-manager.png {Session Manager} To save a session under a new name, select \uicontrol Clone. @@ -97,7 +97,7 @@ \key Ctrl+Alt+<number>, where \e <number> is the number of the session to open (available for the first nine sessions). - \image qtcreator-welcome-session.png + \image qtcreator-welcome-session.webp {Sessions in the Welcome mode} To view more information about a session, select the down arrow icon that appears when you move the mouse cursor over the session name. Select actions diff --git a/doc/qtcreator/src/ios/creator-ios-dev.qdoc b/doc/qtcreator/src/ios/creator-ios-dev.qdoc index d1e15e58b5..f02397f149 100644 --- a/doc/qtcreator/src/ios/creator-ios-dev.qdoc +++ b/doc/qtcreator/src/ios/creator-ios-dev.qdoc @@ -2,23 +2,22 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-adding-docker-devices.html \page creator-developing-ios.html - \nextpage creator-developing-mcu.html + \previouspage creator-reference.html - \title Connecting iOS Devices + \ingroup creator-reference-devices - You can connect iOS devices to your local machine with a USB cable to - run applications built for them from \QC. + \title Developing for iOS - To be able to use \QC on \macos, you must install Xcode, and therefore, - you already have the tool chain for building applications for iOS. \QC - automatically detects the tool chain and creates the necessary - \l{glossary-buildandrun-kit}{kits} to build applications for and run them on + \brief Connect iOS devices to your local machine with a USB cable to + run applications on them. + + After you install Xcode, \QC automatically detects the toolchain and creates + the necessary \l{Kits}{kits} to build applications for and run them on configured iOS devices. - You only need Qt libraries that are built for iOS. You can install them as - part of Qt 5.2, or later. + You only need Qt libraries that are built for iOS. You can install Qt for iOS + with \QOI. \section1 iOS 17 Devices @@ -29,7 +28,36 @@ physical devices with iOS 17 or later because of limitations of the Apple tool for accessing these devices. - \section1 Configuring Devices + \section1 Specifying Supported iOS Versions + + You can build applications for the latest iOS version and deploy them to + previous versions. For the most part, this works automatically. However, + you must take care when you manually set your own target version. If you set + it to a value higher than what Qt requires and supply your own \c Info.plist + file, you must add an \c LSMinimumSystemVersion entry to the \c Info.plist + that matches the value of \l{CMake: CMAKE_OSX_DEPLOYMENT_TARGET} + {CMAKE_OSX_DEPLOYMENT_TARGET} (when using CMake), + \l QMAKE_IOS_DEPLOYMENT_TARGET (when using qmake), or + \l{https://doc.qt.io/qbs/qml-qbsmodules-cpp.html#minimumIosVersion-prop} + {cpp.minimumIosVersion} (when using Qbs) because iOS (and the App Store) + will use the \c LSMinimumSystemVersion value as the authoritative one. + + If you specify a deployment target value lower than what Qt requires, your + application will almost certainly crash somewhere in the Qt libraries when + run on an older version than Qt supports. Therefore, make sure that the + actual build system code reflects the minimum iOS version that is actually + required. + + \sa {iOS}{How To: Develop for iOS}, {Expressing Supported iOS Versions} +*/ + +/*! + \page creator-how-to-connect-ios-devices.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-ios + + \title Connect iOS devices The connections between \QC and an iOS device are protected by using a certificate that you receive from Apple when you @@ -40,26 +68,27 @@ The first time you connect the device to your local machine, you are asked to enable developer mode on the device. The next time you connect the device, \QC detects it automatically. To disable automatic connections to a device that - you do not use for development, select \uicontrol Preferences > - \uicontrol iOS, and deselect the \uicontrol {Ask about devices not in - developer mode} check box. + you do not use for development, go to preferences > \uicontrol iOS + and clear \uicontrol {Ask about devices not in developer mode}. \note The process of configuring devices and the UI varies slightly depending on the Xcode version that you use. We recommend that you use the latest available Xcode version. + \section1 Create a connection to an iOS device + To configure connections between \QC and an iOS device: \list 1 - \li Make sure that you have Xcode and Qt for iOS installed. + \li Check that you installed Xcode and \l{Qt for iOS}. \li Connect the device to your local machine with a USB cable. \li Start Xcode to configure the device. - For example, in Xcode version 15, select \uicontrol Window > - \uicontrol Devices and Simulators > \uicontrol Devices > + For example, in Xcode version 15, go to \uicontrol Window > + \uicontrol Devices and Simulators > \uicontrol Devices, and select \uicontrol + to add the connected device. \li To specify build settings: @@ -69,7 +98,7 @@ \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} to select + \li Go to \uicontrol Projects > \uicontrol {Build & Run} to select the kit for building applications for and running them on iOS. \image qtcreator-ios-add-kit.png "Build & Run Settings" @@ -81,7 +110,7 @@ \image qtcreator-build-settings-ios.png "iOS build settings" - \li Select the \uicontrol {Automatically manage signing} check box + \li Select \uicontrol {Automatically manage signing} to automatically select the provisioning profile and signing certificate on your local machine that matches the entitlements and the bundle identifier of the iOS device. @@ -101,46 +130,33 @@ \endlist \note If you cannot deploy applications because a provisioning profile is - missing, check that provisioning profiles are listed in Xcode by selecting + missing, check that provisioning profiles are listed in Xcode by going to \uicontrol Xcode > \uicontrol Preferences > \uicontrol Accounts. For more information about how to acquire and install a provisioning profile, see Apple documentation. - \section1 Viewing Device Connection Status + \section1 View device connection status When you connect an iOS device to your local machine with USB, \QC automatically detects the device if you have configured it by using Xcode. - To view information about the connected device, select \uicontrol Preferences > + To view information about the connected device, go to \uicontrol Preferences > \uicontrol Devices. - \image qtcreator-ios-device-configurations.png "Devices dialog" + \image qtcreator-ios-device-configurations.png {Devices dialog} If the current device state is \uicontrol Connected, (the traffic light icon is orange), you need to configure the device using Xcode. - \section1 Specifying Supported iOS Versions - - You can build applications for the latest iOS version and deploy them to - previous versions. For the most part, this works automatically. However, - you must take care when you manually set your own target version. If you set - it to a value higher than what Qt requires and supply your own \c Info.plist - file, you must add an \c LSMinimumSystemVersion entry to the \c Info.plist - that matches the value of \l{CMake: CMAKE_OSX_DEPLOYMENT_TARGET} - {CMAKE_OSX_DEPLOYMENT_TARGET} (when using CMake), - \l QMAKE_IOS_DEPLOYMENT_TARGET (when using qmake), or - \l{https://doc.qt.io/qbs/qml-qbsmodules-cpp.html#minimumIosVersion-prop} - {cpp.minimumIosVersion} (when using Qbs) because iOS (and the App Store) - will use the \c LSMinimumSystemVersion value as the authoritative one. + \sa {iOS}{How To: Develop for iOS}, {Developing for iOS} +*/ - If you specify a deployment target value lower than what Qt requires, your - application will almost certainly crash somewhere in the Qt libraries when - run on an older version than Qt supports. Therefore, make sure that the - actual build system code reflects the minimum iOS version that is actually - required. +/*! + \page creator-how-to-test-on-ios-simulator.html + \previouspage creator-how-tos.html - For more information, see \l{Expressing Supported iOS Versions}. + \ingroup creator-how-to-ios - \section1 Testing on Simulator + \title Test on iOS Simulator If you do not have an iOS device or you do not want to create an account, you can test applications on @@ -149,48 +165,19 @@ simulates a predefined set of hardware devices and software versions. You can change the simulated hardware and software version in the run - settings for the project. Select \uicontrol Projects > \uicontrol Run, and then select + settings for the project. Go to \uicontrol Projects > \uicontrol Run, and then select the device to simulate in the \uicontrol {Device type} field. \image qtcreator-ios-simulator-deploy.png - The simulator is started automatically when you run the application. - To start the simulator manually, select \uicontrol Preferences > - \uicontrol Devices > \uicontrol iOS > \uicontrol Start. - - To take screenshots of the simulator, select \uicontrol Preferences > - \uicontrol Devices > \uicontrol iOS > \uicontrol Screenshot. The screenshots - are stored in the directory specified in the - \uicontrol {Screenshot directory} field. - - \section2 Managing Simulators - - The available simulators are listed in \uicontrol Preferences > - \uicontrol Devices > \uicontrol iOS. - - \image qtcreator-ios-preferences.png - - To create a new simulator instance: - - \list - - \li Select \uicontrol Create. - - \li In the \uicontrol {Device type} field, select the device type from - a list of devices supported by the Xcode version set as current on - your local machine. - - \li In the \uicontrol {OS version} field, select an OS version from a - list of OS versions supported by the selected device and the current - Xcode version. - - \endlist - - To rename the selected simulator, select \uicontrol Rename. - - To reset the contents and settings of the selected simulators, select - \uicontrol Reset. + The simulator starts automatically when you run the application. + To start the simulator manually, either start the Simulator application + directly with Spotlight, or go to \uicontrol Xcode > \uicontrol {Open Developer Tool} + in Xcode. - To delete the selected simulator, select \uicontrol Delete. + Manage the available simulator devices + \l{https://developer.apple.com/documentation/xcode/running-your-app-in-simulator-or-on-a-device/#Configure-the-list-of-simulated-devices} + {in Xcode}. + \sa {iOS}{How To: Develop for iOS}, {Developing for iOS} */ diff --git a/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc b/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc index 3f7499b5b5..04dceb4916 100644 --- a/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc +++ b/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc @@ -1,144 +1,79 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page creator-developing-b2qt.html - \previouspage creator-developing-baremetal.html - \nextpage creator-adding-docker-devices.html + \previouspage creator-reference.html - \title Connecting Boot2Qt Devices + \ingroup creator-reference-devices - You can connect \l{Boot2Qt} devices to the development PC to run, debug, - and analyze applications built for them from \QC. For this, you need the - appropriate \l{http://qt.io/licensing/}{Qt license}. + \title Developing for \B2Q Devices - If you have a tool chain for building applications for Boot2Qt devices - installed on the development PC, you can add it to \QC. You can then - select a \l{glossary-buildandrun-kit}{kit} with the \uicontrol Boot2Qt - device type to build applications for and run them on the devices. + \brief Connect \B2Q devices to the computer to run, + debug, and analyze applications built for them from \QC. - To be able to run and debug applications on Boot2Qt devices, - you must add devices and select them in the \QC - \l{kits-tab}{kit}. + The \l{\B2Q: Documentation}{\B2Q} stack runs on a variety of hardware. + \l{http://qt.io/licensing/}{Qt license} holders can customize the contents of + the stack and take it into production hardware. - \section1 Enabling the Boot2Qt Plugin + \note Enable the \B2Q plugin to use it. - To enable the Boot2Qt plugin: - - \list 1 - \li Select \uicontrol Help > \uicontrol {About Plugins} > - \uicontrol {Device Support} > \uicontrol Boot2Qt to - enable the plugin. - \li Select \uicontrol {Restart Now} to restart \QC and load the plugin. - \endlist - - \section1 Adding Boot2Qt Devices - - If \QC does not automatically detect a device you connected with USB, select - \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol Add > \uicontrol {Boot2Qt Device} to create - either a network connection or a USB connection to it. + If you have a toolchain for building applications for \B2Q devices + installed on the computer, add it to a \l{Kits}{kit} with the + \uicontrol \B2Q device type to build applications for and run them on + the devices. \image qtcreator-boot2qt-device-configurations.webp {Devices tab in Preferences} - To add a device without using a wizard, select \uicontrol {Boot2Qt Device} in - the pull-down menu of the \uicontrol Add button. - - \note On Ubuntu Linux, the development user account must have access to the - plugged-in devices. To grant them access to the device via USB, create a new - \c udev rule, as described in - \l{https://doc.qt.io/Boot2Qt/b2qt-requirements-x11.html#setting-up-usb-access-to-embedded-devices} - {Boot2Qt: Setting Up USB Access to Embedded Devices}. - - You can edit the settings later in \preferences > - \uicontrol Devices > \uicontrol Devices. + \include linuxdev.qdoc openssh - To reboot the selected device, select \uicontrol {Reboot Device}. - - To restore the default application to the device, select - \uicontrol {Restore Default App}. - - \section2 Protecting Connections - - You can protect the connections between \QC and a device by using an - \l{https://www.openssh.com/}{OpenSSH} connection. OpenSSH is a - connectivity tool for remote login using the SSH protocol. The OpenSSH - suite is not delivered with \QC, so you must download it and install it - on the development PC. Then, you must configure the paths to the tools in - \QC. For more information, see \l {Configuring SSH Connections}. - - You need either a password or an SSH public and private key pair for - authentication. If you do not have an SSH key, you can use the \c ssh-keygen - tool to create it in \QC. For more information, see \l {Generating SSH Keys}. - - \QC does not store passwords. If you use password authentication, you may - need to enter the password upon every connection to the device, or if - caching is enabled, at every \QC restart. If you frequently run into the - timeout, consider using key-based authentication. On \macos and Linux, you - can also select \preferences > \uicontrol Devices > \uicontrol SSH - and increase the time (in minutes) to use the same SSH connection in the - \uicontrol {Connection sharing timeout} field. Windows does not support - shared connections. + \sa {\B2Q}{How To: Develop for \B2Q}, + {Manage Kits}{How To: Manage Kits}, {Run in Qt Application Manager}, + {\B2Q Deploy Configuration}, {\B2Q Run Settings}, + {\B2Q: Documentation} +*/ - \image qtcreator-ssh-options.png {SSH preferences} +/*! + \page creator-how-to-connect-b2qt.html + \previouspage creator-how-tos.html - \section1 Flashing Boot2Qt Devices + \ingroup creator-how-to-b2qt - To flash the Boot2Qt image to an SD card with Flashing Wizard, select - \uicontrol Tools > \uicontrol {Flash Boot to Qt Device} and follow the - instructions of the wizard. + \title Connect \B2Q devices - \image qtcreator-boot2qt-flashing-wizard.png {Boot2Qt Flashing Wizard} + Create connections between \l{\B2Q: Documentation}{\B2Q} devices and + \QC to run, debug, and analyze applications on them. - \section1 Configuring Connections + \note Enable the \B2Q plugin to use it. - To configure connections between \QC and a Boot2Qt device and to - specify build and run settings for the device: + To configure connections between \QC and a \B2Q device: \list 1 \li Check that you can reach the IP address of the device, or use USB to connect it. - \li Select \preferences > \uicontrol Kits > \uicontrol {Qt Versions} > - \uicontrol Add to add the Qt version for Boot2Qt. - \li Select \preferences > \uicontrol Kits > - \uicontrol Compilers > \uicontrol Add to add the compiler for - building the applications. - \li Select \uicontrol Tools > \uicontrol {Flash Boot to Qt Device} - to flash the Boot2Qt image to an SD card with Flashing Wizard. - \li To deploy applications and run them remotely on devices, specify - parameters for connecting to the devices over the network (\QC - automatically detects devices connected with USB): - \list 1 - \li Select \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol Add > \uicontrol Boot2Qt. - \image qtcreator-devices-boot2qt.png {Boot2Qt Network Device Setup wizard} - \li In the \uicontrol {Device name} field, enter a name for - the connection. - \li In the \uicontrol {Device address} field, enter the host - name or IP address of the device. This value will be - available in the \c %{Device:HostAddress} variable. - \li Click \uicontrol {Finish} to test the connection and - add the device. - - You can edit the connection parameters in the - \uicontrol Devices tab. The wizard does not show - parameters that have sensible default values. One of - these is the SSH port number, which is available in - the variable \c %{Device:SshPort}. - - To add a device without using the wizard, select - \uicontrol {Boot2Qt Device} in the pull-down menu of the - \uicontrol Add button. - \endlist - \li Select \preferences > \uicontrol Kits > - \uicontrol Add to add a kit for building applications for the - device. Select the Qt version, compiler, and device that you - added above, and choose \uicontrol Boot2Qt as the device type. + \li Go to \preferences > \uicontrol Kits > \uicontrol {Qt Versions}. + \li Select \uicontrol Add to add the Qt version for \B2Q. + \li Go to \preferences > \uicontrol Kits > \uicontrol Compilers. + \li Select \uicontrol Add to add the compiler for building the + applications. + \li Go to \uicontrol Tools > \uicontrol {Flash \B2Q} + to flash the \B2Q image to an SD card with \B2Q Flashing Wizard. + \image qtcreator-boot2qt-flashing-wizard.png {\B2Q Flashing Wizard} + \li Follow the instructions of the wizard to flash the image to the SD + card. + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select \uicontrol Add to add a \B2Q device. + + \QC automatically detects devices connected with USB. + \li Go to \preferences > \uicontrol Kits. + \li Select \uicontrol Add to add a kit for building for the device. + \li Select the Qt version, compiler, and device that you added above. + \li In \uicontrol {Run device type}, select \uicontrol {Boot2Qt Device}. \li To specify build settings: \list 1 \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} to enable + \li Go to \uicontrol Projects > \uicontrol {Build & Run} to activate the kit that you specified above. \endlist \li Select \uicontrol Run to specify run settings. Usually, you can use @@ -146,7 +81,66 @@ When you run the project, \QC deploys the application as specified by the deploy steps. By default, \QC copies the - application files to the device. For more information, see - \l{Boot2Qt Run Settings}. + application files to the device. + \endlist + + \sa {Configure SSH connections}, {Generate SSH keys}, + {Enable and disable plugins}, {\B2Q}{How To: Develop for \B2Q}, + {Manage Kits}{How To: Manage Kits}, {\B2Q Deploy Configuration}, + {\B2Q Run Settings}, {Developing for \B2Q Devices} +*/ + +/*! + \page creator-how-to-add-b2qt.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-b2qt + + \title Add \B2Q devices + + \note Enable the \B2Q plugin to use it. + + If \QC does not automatically detect a \B2Q device you connect with USB, + check that you followed the instructions in the \l{\B2Q: Documentation} + {Quick Start Guide} for the device. + + If that does not help, but you can reach the IP address of the device, + create a network connection to it: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \image qtcreator-boot2qt-device-configurations.webp {Devices tab in Preferences} + \li Select \uicontrol Add > \uicontrol {Boot2Qt Device} to create + a network connection to the device. + \image qtcreator-devices-boot2qt.png {Boot to Qt Network Device Setup wizard} + \li In \uicontrol {Device name}, enter a name for the connection. + \li In \uicontrol {Device address}, enter the host + name or IP address of the device. This value becomes the value of the + \c %{Device:HostAddress} variable. + \li Select \uicontrol {Finish} to test the connection and add the device. \endlist + + The wizard does not show parameters that have sensible default values, such + as the SSH port number. It is available in the variable \c %{Device:SshPort}. + + To add a device without using a wizard, select \uicontrol {Boot2Qt Device} in + the pull-down menu of the \uicontrol Add button. + + \note On Ubuntu Linux, the development user account must have access to the + plugged-in devices. To grant them access to the device via USB, create a new + \c udev rule, as described in + \l{\B2Q: Setting Up USB Access to Embedded Devices}. + + \section1 Reboot devices + + To reboot the selected device, select \uicontrol {Reboot Device}. + + \section1 Restore default applications + + To restore the default application to the device, select + \uicontrol {Restore Default App}. + + \sa {Enable and disable plugins}, {\B2Q}{How To: Develop for \B2Q}, + {Developing for \B2Q Devices}, + {\B2Q: Setting Up USB Access to Embedded Devices} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc index 73301bb173..298865d794 100644 --- a/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc @@ -1,25 +1,32 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page creator-deployment-b2qt.html - \previouspage creator-deploying-android.html - \nextpage creator-deployment-qnx.html + \previouspage creator-reference.html - \title Deploying to Boot2Qt + \ingroup creator-reference-deploy-configurations - You can specify settings for deploying applications to \l{Boot2Qt} devices - in the project configuration file and in \uicontrol Projects > - \uicontrol {Run Settings} > \uicontrol Deployment. + \title \B2Q Deploy Configuration - \image qtcreator-boot2qt-deployment-steps.png "Boot2Qt deployment steps" + \brief Copy application files to \B2Q devices. + + Specify settings for deploying applications to \l{\B2Q: Documentation} + {\B2Q} devices in the project configuration file and in \uicontrol Projects + > \uicontrol {Run Settings} > \uicontrol Deployment. + + \image qtcreator-boot2qt-deployment-steps.png {Boot to Qt deployment steps} The deployment process is described in more detail in - \l{Deploying to Remote Linux}. + \l{Remote Linux Deploy Configuration}. \section1 Launching Applications on Boot - In addition, to have your application launch on boot, select + To have your application launch on boot, select \uicontrol {Add Deploy Step} > \uicontrol {Change default application} > \uicontrol {Set this application to start by default}. + + \sa {Build and Run}{How To: Build and Run}, + {\B2Q}{How To: Develop for \B2Q}, {\B2Q Run Settings}, + {Developing for \B2Q Devices} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc index 38c6823fa3..87c54e26fa 100644 --- a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -9,14 +9,18 @@ /*! \page creator-deployment-embedded-linux.html - \previouspage creator-deployment-qnx.html - \nextpage creator-connecting-mobile.html + \previouspage creator-reference.html - \title Deploying to Remote Linux + \ingroup creator-reference-deploy-configurations - You can specify settings for deploying applications to generic remote - Linux devices in the project configuration file and in the - \uicontrol Projects mode, in \uicontrol {Run Settings}. + \title Remote Linux Deploy Configuration + + \brief Copy application files to generic remote Linux devices or create a + tarball. + + Specify settings for deploying applications to generic remote + Linux devices in the project configuration file and in \uicontrol Projects > + \uicontrol {Run Settings} > \uicontrol Deployment. \image qtcreator-embedded-linux-deployment-details.png "Deploy to remote Linux devices" @@ -107,4 +111,7 @@ The \uicontrol {Deploy tarball via SFTP upload} step specifies that \QC uploads the tarball to the device and extracts it. + + \sa {Build and Run}{How To: Build and Run}, + {Remote Linux}{How To: Develop for remote Linux}, {Remote Linux Run Settings} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-embedded-platforms.qdoc b/doc/qtcreator/src/linux-mobile/creator-embedded-platforms.qdoc deleted file mode 100644 index 39ff44f112..0000000000 --- a/doc/qtcreator/src/linux-mobile/creator-embedded-platforms.qdoc +++ /dev/null @@ -1,117 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \page creator-embedded-platforms.html - \previouspage creator-reference.html - - \ingroup creator-reference-platforms - - \title Embedded Platforms - - \brief Embedded platforms that you can develop applications for. - - You can develop applications for the following embedded platforms: - - \list - \li \l {Bare Metal} - \li \l {Boot2Qt} - \li \l {Remote Linux} - \li \l {Microcontroller Units (MCU)} - \li \l QNX - \endlist - - You must install the tool chain for building applications for the targeted - embedded platform on the development PC and use \QMT to - install Qt libraries that are built for the platform. You can then add a - \l{glossary-buildandrun-kit}{kit} with the tool chain and the Qt version - for the device's architecture. When possible, \QMT creates - suitable kits for you. - - You can connect embedded devices to the development PC to run, debug, and - analyze applications built for them from \QC. - - \section1 Bare Metal - - You can run and debug applications on small devices that are not supported - by the remote Linux device plugin by using GDB or a hardware - debugger. - - For more information about developing applications for Bare Metal devices, - see \l{Connecting Bare Metal Devices}. - - \section1 Boot2Qt - - The Boot2Qt stack runs on a variety of hardware. License holders can use - tools to customize the contents of the stack and to take it into - production hardware. - - You need either Windows 10 64-bit or later or Ubuntu Linux 64-bit 20.04 LTS - or later to install and use Boot2Qt. - - The following topics have more information about developing applications - for Boot2Qt devices: - - \list - \li \l{https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html} - {Boot2Qt: Supported Target Devices and Development Hosts} - \li \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guides} - \li \l{Connecting Boot2Qt Devices} - \li \l{Boot2Qt Run Settings} - \li \l{Deploying to Boot2Qt} - \li \l{Run in Qt Application Manager} - \endlist - - \section1 Remote Linux - - You must have a tool chain for building applications for embedded Linux - devices installed on the development PC. - - The following topics have more information about developing applications - for remote Linux devices: - - \list - \li \l{Adding Docker Devices} - \li \l{Connecting Remote Linux Devices} - \li \l{Deploying to Remote Linux} - \li \l{Remote Linux Run Settings} - \li \l{Run on remote Linux devices} - \li \l{Run in Qt Application Manager} - \endlist - - \section1 Microcontroller Units (MCU) - - You need the GNU Arm Embedded GCC compiler, libraries, and other GNU tools - necessary for bare metal software development on devices based on the Arm - Cortex-M processors. - - The following topics have more information about developing applications - for MCUs: - - \list - \li \l{Connecting MCUs} - \li \l{Running Applications on MCUs} - \li \l{https://doc.qt.io/QtForMCUs/index.html}{\QMCU} - \endlist - - \section1 QNX - - The QNX Neutrino RTOS has more command-line tools - and services, as described in \l {Qt for QNX}. - - \note In Qt 6, \QC support for QNX is considered experimental. - - The following topics have more information about developing applications - for QNX devices: - - \list - \li \l{Connecting QNX Devices} - \li \l{Deploying to QNX Neutrino} - \li \l{QNX Run Settings} - \li \l{Run on QNX devices} - \li \l{Qt for QNX} - \endlist - - \sa {Supported Platforms} -*/ diff --git a/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc index b78dcd5ca2..d39f924f04 100644 --- a/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-projects-how-to-run-generic-linux.qdoc @@ -5,7 +5,7 @@ \page creator-how-to-run-on-remote-linux.html \previouspage creator-how-tos.html - \ingroup creator-how-to-run + \ingroup creator-how-to-remote-linux \title Run on remote Linux devices @@ -19,7 +19,7 @@ \endlist - \QC uses the compiler from the kit (tool chain) to build the application. + \QC uses the compiler from the kit (toolchain) to build the application. \QC copies the application files to the connected device and runs the application. The application views are @@ -34,6 +34,6 @@ Debugging works transparently if GDB server is installed on the device and it is compatible with the GDB on the host. - \sa {Connecting Remote Linux Devices}, {Run on many platforms}, {Compilers}, + \sa {Remote Linux}{How To: Develop for remote Linux}, {Run on many platforms}, {Compilers}, {Embedded Platforms}, {kit-preferences}{Kits} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc index 1391cfcfd4..a8d3093cfb 100644 --- a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-b2qt.qdoc @@ -1,30 +1,30 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \page creator-run-settings-boot2qt.html + \page creator-run-settings-\B2Q.html \previouspage creator-reference.html \ingroup creator-reference-run-configurations - \title Boot2Qt Run Settings + \title \B2Q Run Settings - \brief Settings for running applications on Boot2Qt devices. + \brief Settings for running applications on \B2Q devices. Specify settings for running applications on the \l {kits-tab}{Run device} that you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Run > \uicontrol {Run Settings}. - To run and debug an application on a \l Boot2Qt device (commercial only), you - must create connections from the development host to the device and add the - device configurations to kits. Select \uicontrol {Manage Kits} to add devices - to kits. For more information, see - \l{http://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guide}. + To run and debug an application on a \l{\B2Q: Documentation}{\B2Q} device + (commercial only), create connections from the development host to the device + and add the device configurations to kits. + + Select \uicontrol {Manage Kits} to add devices to kits. The run settings display the path to the executable file on the development host and on the device. - \sa {Activate kits for a project}, {Configure projects for running}, {kits-tab}{Kits}, - {Deploying to Boot2Qt} + \sa {\B2Q}{How To: Develop for \B2Q}, {Manage Kits}{How To: Manage Kits}, + {Configure projects for running}, {kits-tab}{Kits}, + {\B2Q Deploy Configuration} */ diff --git a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc index 4e2a08e132..adc27d6a93 100644 --- a/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc +++ b/doc/qtcreator/src/linux-mobile/creator-projects-settings-run-linux.qdoc @@ -19,7 +19,7 @@ connections from the development host to the device and add the device configurations to kits. Select \uicontrol {Manage Kits} to add devices to kits. For more information, see - \l {Connecting Remote Linux Devices}. + \l {Remote Linux}{How To: Develop for remote Linux}. When you run the application, \QC copies the files to the connected device. @@ -38,5 +38,5 @@ running X11 client on a local display. \sa {Activate kits for a project}, {Configure projects for running}, {kits-tab}{Kits}, - {Connecting Remote Linux Devices} + {Remote Linux}{How To: Develop for remote Linux} */ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdoc new file mode 100644 index 0000000000..9af4de44ed --- /dev/null +++ b/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdoc @@ -0,0 +1,82 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-how-to-configure-ssh.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Configure SSH connections + + To protect the connections between \QC and a device, install the \l{OpenSSH} + suite, which includes the \c ssh, \c sftp, and \c ssh-keygen tools on the + computer. + + SSH connections are established via an OpenSSH client running in master + mode, if possible. By default, multiple sessions are shared over a single SSH + onnection. Establishing a connection once and then re-using it for subsequent + run and deploy procedures reduces connection setup overhead particularly + with embedded devices. Because connection sharing is not supported on + Windows, a new SSH connection is created for each deploy or run procedure. + + To set the paths to the directories where the tools are installed: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol SSH. + \image qtcreator-ssh-options.png "SSH preferences" + \li Clear \uicontrol {Enable connection sharing} to + create a new SSH connection for each deploy and run procedure. This + option is grayed on Windows, where connection sharing is not + supported. + \li In \uicontrol {Connection sharing timeout}, specify the + timeout for reusing the SSH connection in minutes. + \li In \uicontrol {Path to ssh executable}, enter the path + to the directory where the OpenSSH executable is installed. + \li In \uicontrol {Path to sftp executable}, enter the path + to the directory where the SFTP executable is installed. + \li In \uicontrol {Path to ssh-askpass executable}, enter the + path to the directory where the ssh-askpass executable is installed. + Usually, you can use the default path that points to the + implementation of the tool delivered with \QC, qtc-askpass. + \li In \uicontrol {Path to ssh-keygen executable}, enter the + path to the directory where the ssh-keygen executable is installed. + \endlist + + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Developing for Remote Linux Devices} +*/ + +/*! + \page creator-how-to-generate-ssh-keys.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Generate SSH keys + + To protect the connections between \QC and a device, use \l{OpenSSH}. + + If you do not have an SSH public and private key pair, you can generate it + in \QC. The connection wizard can create the key pair for you, or you can + create it separately. + + You can specify key length and the key algorithm, RSA or ECDSA. + If you only use the keys to protect connections to the emulator or + device, you can use the default values. + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices + \li Select \uicontrol {Create New}. + \image qtcreator-ssh-key-configuration.png {SSH Key Configuration dialog} + \li In \uicontrol {Private key file}, select the location to save + the private key. + \uicontrol {Public key file} displays the location to save the + corresponding public key. + \li Select \uicontrol {Generate And Save Key Pair} to generate and save the + keys at the specified locations. + \endlist + + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Developing for remote Linux devices} +*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdocinc b/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdocinc deleted file mode 100644 index f3582f2373..0000000000 --- a/doc/qtcreator/src/linux-mobile/linuxdev-keys.qdocinc +++ /dev/null @@ -1,80 +0,0 @@ -// Copyright (C) 2019 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - -//! [configuring ssh] - \section2 Configuring SSH Connections - - SSH connections are established via an OpenSSH client running in master - mode, if possible. Connection sharing is enabled by default to allow - sharing multiple sessions over a single SSH connection. This way, a - connection is only established once and then re-used by subsequent run - and deploy procedures, saving connection setup overhead particularly - with embedded devices. Because connection sharing is not supported on - Windows, a new SSH connection is created for each deploy or run procedure. - - To create SSH connections, you must install the \l{https://www.openssh.com/} - {OpenSSH} suite, which includes the ssh, sftp, and ssh-keygen tools on the - development PC. - - To tell \QC where it can find the tools, specify the paths to the - directories where the tools are installed in \preferences > - \uicontrol Devices > \uicontrol SSH: - - \image qtcreator-ssh-options.png "SSH preferences" - - \list - \li Deselect the \uicontrol {Enable connection sharing} check box to - create a new SSH connection for each deploy and run procedure. This - option is grayed on Windows, where connection sharing is not - supported. - \li In the \uicontrol {Connection sharing timeout} field, specify the - timeout for reusing the SSH connection in minutes. - \li In the \uicontrol {Path to ssh executable} field, enter the path - to the directory where the OpenSSH executable is installed. - \li In the \uicontrol {Path to sftp executable} field, enter the path - to the directory where the SFTP executable is installed. - \li In the \uicontrol {Path to ssh-askpass executable} field, enter the - path to the directory where the ssh-askpass executable is installed. - Usually, you can use the default path that points to the - implementation of the tool delivered with \QC, qtc-askpass. - \li In the \uicontrol {Path to ssh-keygen executable} field, enter the - path to the directory where the ssh-keygen executable is installed. - \endlist - -//! [configuring ssh] - - -//! [generating ssh keys] - - \section2 Generating SSH Keys - - If you do not have an SSH public and private key pair, you can generate it - in \QC. The connection wizard can create the key pair for you, or you can - create it separately. - - You can specify key length and the key algorithm, RSA or ECDSA. - If you only use the keys to protect connections to the emulator or - device, you can use the default values. - - \list 1 - - \li Select \preferences > \uicontrol Devices - > \uicontrol Devices > \uicontrol {Create New}. - - \image qtcreator-ssh-key-configuration.png "SSH Key Configuration dialog" - - \li In the \uicontrol {Private key file} field, select the location to save - the private key. - - The \uicontrol {Public key file} field displays the location to save the - corresponding public key. - - \li Select \uicontrol {Generate And Save Key Pair} to generate and save the - keys at the specified locations. - - \endlist - -//! [generating ssh keys] -*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdoc new file mode 100644 index 0000000000..db73410dca --- /dev/null +++ b/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdoc @@ -0,0 +1,26 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-how-to-manage-device-processes.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Manage device processes + + To view and end processes running on embedded platforms: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select an embedded device. + \image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices} + \li Select \uicontrol {Show Running Processes}. + \li Filter the processes by name or ID. + \li To update the process list, select \uicontrol {Update List}. + \li To end a process, select it in the list, and then select + \uicontrol {Kill Process}. + \endlist + + \sa {Develop for Devices}{How To: Develop for Devices}, {Devices} +*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdocinc b/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdocinc deleted file mode 100644 index 1c9c2d0a4a..0000000000 --- a/doc/qtcreator/src/linux-mobile/linuxdev-processes.qdocinc +++ /dev/null @@ -1,22 +0,0 @@ -// Copyright (C) 2019 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -//! [managing device processes] - - \section2 Managing Device Processes - - You can view processes running on devices and kill them. Select - \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol {Show Running Processes}. - - You can filter the processes by name or ID in the - \uicontrol {List of Processes} dialog. - - To update the process list, select \uicontrol {Update List}. - - To kill a process, select it in the list, and then select \uicontrol {Kill - Process}. - -//! [managing device processes] -*/ diff --git a/doc/qtcreator/src/linux-mobile/linuxdev.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev.qdoc index 401fdbd8c1..e0ec120b85 100644 --- a/doc/qtcreator/src/linux-mobile/linuxdev.qdoc +++ b/doc/qtcreator/src/linux-mobile/linuxdev.qdoc @@ -1,122 +1,99 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page creator-developing-generic-linux.html - \previouspage creator-developing-qnx.html - \nextpage creator-setup-webassembly.html + \previouspage creator-reference.html - \title Connecting Remote Linux Devices + \ingroup creator-reference-devices - You can connect generic Linux devices to the development PC to run, + \title Developing for Remote Linux Devices + + \brief Connect generic Linux devices to the computer to run, debug, and analyze applications built for them from \QC. - If you have a tool chain for building applications for embedded Linux - devices installed on the development PC, you can add - it to \QC. You can then select a \l{glossary-buildandrun-kit}{kit} + If you have a toolchain for building applications for embedded Linux + devices installed on the computer, add it to a \l{Kits}{kit} with the device type \uicontrol {Remote Linux Device} to build applications for and run them on the devices. - To be able to run and debug applications on remote Linux devices, - you must add devices and select them in the \QC \l{glossary-buildandrun-kit} - {kit}. + Use a wizard to connect remote Linux devices to the computer. You can edit + the settings later in \preferences > \uicontrol Devices > \uicontrol Devices. - You use a wizard to create the connections. You can edit the settings later - in \preferences > \uicontrol Devices > - \uicontrol Devices. + \image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices} - \image qtcreator-preferences-devices-remote-linux.webp "Remote Linux Device in the Devices tab" + //! [openssh] + \section1 Protecting Device Connections - You can protect the connections between \QC and a device by using an - \l{https://www.openssh.com/}{OpenSSH} connection. OpenSSH is a - connectivity tool for remote login using the SSH protocol. The OpenSSH - suite is not delivered with \QC, so you must download it and install it - on the development PC. Then, you must configure the paths to the tools in - \QC. For more information, see \l {Configuring SSH Connections}. + To protect the connections between \QC and a device, use \l{OpenSSH} for + remote login over the SSH protocol. The OpenSSH suite is not delivered with + \QC, so download it and install it on the computer. Then, configure the paths + to the tools in \QC. You need either a password or an SSH public and private key pair for - authentication. If you do not have an SSH key, you can use the ssh-keygen - tool to create it in \QC. For more information, see \l {Generating SSH Keys}. + authentication. If you do not have an SSH key, use the \c ssh-keygen + tool to create it in \QC. \note \QC does not store passwords, so if you use password authentication, you may need to enter the password on every connection to the device, or, if caching is enabled, at every \QC restart. - To configure connections between \QC and a remote Linux device and to - specify build and run settings for the device: - - \list 1 + If you frequently run into the timeout, consider using key-based + authentication. Create an SSH key in \QC with the \c ssh-keygen tool. - \li Make sure that your device can be reached via an IP address. + On \macos and Linux, go to \preferences > \uicontrol Devices > \uicontrol SSH + and increase the time (in minutes) for sharing an SSH connection in the + \uicontrol {Connection sharing timeout} field. Windows does not support + shared connections. - \li Select \preferences > \uicontrol Kits > - \uicontrol {Qt Versions} > \uicontrol Add to add the Qt version - for embedded Linux. + \image qtcreator-ssh-options.png {SSH preferences} + //! [openssh] - \li Select \preferences > \uicontrol Kits > - \uicontrol Compilers > \uicontrol Add to add the compiler for - building the applications. + \sa {Add Docker devices}, {Remote Linux}{How To: Develop for remote Linux}, + {Run in Qt Application Manager}, {Remote Linux Deploy Configuration}, + {Remote Linux Run Settings} +*/ - \li To deploy applications and run them remotely on devices, specify - parameters for accessing the devices: +/*! + \page creator-how-to-connect-remote-linux.html + \previouspage creator-how-tos.html - \list a + \ingroup creator-how-to-remote-linux - \li Select \preferences > - \uicontrol Devices > \uicontrol Devices > \uicontrol Add > - \uicontrol {Remote Linux Device} - > \uicontrol {Start Wizard}. + \title Connect remote Linux devices - \image qtcreator-preferences-devices-remote-linux-connection.webp "Connection Data wizard" + Create connections between generic Linux devices and \QC to run, debug, and + analyze applications on them. - \li In \uicontrol {The name to identify this configuration}, - enter a name for the connection. + To configure connections between \QC and a remote Linux device: - \li In \uicontrol {The device's host name or IP address}, - enter the host name or IP address of the device. - This value will be available in the variable \c %{Device:HostAddress}. + \list 1 - \li In \uicontrol {The device's SSH port number}, enter the port - number to use for SSH connections. This value will be - available in the variable \c %{Device:SshPort}. - \li In \uicontrol {The username to log into the device}, - enter the username to log into the device and run the - application as. - This value will be available in the variable \c %{Device:UserName}. + \li Make sure that your device can be reached via an IP address. - \li Select \uicontrol {Next} to open the - \uicontrol {Key Deployment} dialog. + \li Go to \preferences > \uicontrol Kits > \uicontrol {Qt Versions}. - \image qtcreator-preferences-devices-remote-linux-key-deployment.webp "Key Deployment dialog" + \li Select \uicontrol Add to add the Qt version for embedded Linux. - \li In \uicontrol {Private key file}, select a private key file - to use for authentication. This value will be available in - the variable \c %{Device:PrivateKeyFile}. + \li Go to \preferences > \uicontrol Kits > \uicontrol Compilers. - \li If you do not have a public-private key pair, select - \uicontrol {Create New Key Pair}. For more information, - see \l{Generating SSH Keys}. + \li Select \uicontrol Add to add the compiler for building the + applications. - \li Select \uicontrol {Deploy Public Key} to copy the public - key to the device. + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. - \li Select \uicontrol {Next} to create the connection. + \li Select \uicontrol Add to add a remote Linux device. - \endlist + \li Go to \preferences > \uicontrol Kits. - All of these parameters can be edited later, as well as additional ones that the - wizard does not show because there are sensible default values. + \li Select \uicontrol Add to add a kit for building for the device. - To add a device without using the wizard, select - \uicontrol {Add Remote Linux Device} in the pull-down - menu of the \uicontrol Add button. + \li Select the Qt version, compiler, and device that you added above. - \li Select \preferences > \uicontrol Kits > - \uicontrol Add to add a kit for building for the device. Select the - Qt version, compiler, and device that you added above, and select - \uicontrol {Remote Linux Device} in \uicontrol {Run device type}. + \li In \uicontrol {Run device type}, select + \uicontrol {Remote Linux Device}. - To build on the remote device, select \uicontrol {Remote Linux Device} + \li To build on the remote device, select \uicontrol {Remote Linux Device} also in \uicontrol {Build device}. \li To specify build settings: @@ -134,13 +111,33 @@ \li Select \uicontrol Run to specify run settings. Usually, you can use the default settings. - When you run the project, \QC deploys the application as specified by the - deploy steps. By default, \QC copies the application files to the device. - For more information, see \l{Deploying to Remote Linux}. + When you run the project, \QC deploys the application as specified by + the deploy steps. \endlist - \include linux-mobile/linuxdev-keys.qdocinc configuring ssh - \include linux-mobile/linuxdev-keys.qdocinc generating ssh keys - \include linux-mobile/linuxdev-processes.qdocinc managing device processes + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Manage Kits}{How To: Manage Kits}, {Developing for Remote Linux Devices}, + {Remote Linux Deploy Configuration}, {Remote Linux Run Settings} +*/ + +/*! + \page creator-how-to-add-remote-linux.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-remote-linux + + \title Add remote Linux devices + + Create connections between generic Linux devices and \QC to run, debug, and + analyze applications on them. + + \image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices} + \caption Remote Linux Device preferences + + \include qtcreator-add-linux-device.qdocinc {add linux device} {Remote Linux Device} + + \sa {Remote Linux}{How To: Develop for remote Linux}, + {Developing for Remote Linux Devices}, + {Remote Linux Deploy Configuration} */ diff --git a/doc/qtcreator/src/linux-mobile/qtcreator-add-linux-device.qdocinc b/doc/qtcreator/src/linux-mobile/qtcreator-add-linux-device.qdocinc new file mode 100644 index 0000000000..28fb464833 --- /dev/null +++ b/doc/qtcreator/src/linux-mobile/qtcreator-add-linux-device.qdocinc @@ -0,0 +1,47 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [add linux device] + + \section1 Use a wizard to add a device + + To use a wizard to add \uicontrol {\1}: + + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {\1} > \uicontrol {Start Wizard}. + \image qtcreator-preferences-devices-remote-linux-connection.webp {Connection Data wizard} + \li In \uicontrol {The name to identify this configuration}, + enter a name for the connection. + \li In \uicontrol {The device's host name or IP address}, + enter the host name or IP address of the device. + This becomes the value of the \c %{Device:HostAddress} variable. + \li In \uicontrol {The device's SSH port number}, enter the port + number for SSH connections. This becomes the value of the + \c %{Device:SshPort} variable. + \li In \uicontrol {The username to log into the device}, enter the + username to log into the device and run the application. This + becomes the value of the \c %{Device:UserName} variable. + \li Select \uicontrol {Next} to open the \uicontrol {Key Deployment} + dialog. + \image qtcreator-preferences-devices-remote-linux-key-deployment.webp {Key Deployment dialog} + \li In \uicontrol {Private key file}, select a private key file + for authentication. This becomes the value of the + \c %{Device:PrivateKeyFile} variable. + \li If you don't have a public-private key pair, select + \uicontrol {Create New Key Pair}. For more information, + see \l{Generate SSH keys}. + \li Select \uicontrol {Deploy Public Key} to copy the public + key to the device. + \li Select \uicontrol {Next} to create the connection. + \endlist + + To change device preferences, go to \preferences > \uicontrol Devices > + \uicontrol Devices and select a device in \uicontrol Device. + + \section1 Manually add a device + + To add a device without using the wizard, select \uicontrol {\1} in the + pull-down menu of the \uicontrol Add button. + +//! [add linux device] diff --git a/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc b/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc index 65fba314e2..19ba26bdca 100644 --- a/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc +++ b/doc/qtcreator/src/mcu/creator-mcu-dev.qdoc @@ -1,31 +1,29 @@ -// Copyright (C) 2020 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-developing-ios.html \page creator-developing-mcu.html - \nextpage creator-developing-qnx.html + \previouspage creator-reference.html - \title Connecting MCUs + \ingroup creator-reference-devices - \QMCU enables you to use subsets of QML and Qt Quick Controls - to create user interfaces for devices that are powered by microcontroller - units (MCU). It includes a new graphics rendering engine that has a low - memory footprint and is optimized for MCUs and other resource-constrained - devices. + \title Developing for MCUs - You can connect MCU boards to a development host to build applications for - them using the GNU Arm Embedded GCC compiler, libraries, and other GNU tools - necessary for bare metal software development on devices based on the Arm - Cortex-M processors. You can deploy the applications on MCUs to run and - debug them using \QC. + \brief Connect MCU devices to the computer to run and debug applications on + them. - The toolchains are available for cross-compilation on Microsoft Windows, - Linux, and macOS. However, the Qt for \QMCU SDK is currently only available - for Windows and Linux. + \note Enable the McuSupport plugin to develop for MCUs. - For a list of \QMCU reference implementations, see the - \l{\QMCU - Supported Target Platforms}{\QMCU} documentation. + Use subsets of QML and Qt Quick Controls to create user interfaces for + devices that are powered by microcontroller units (MCU). \QMCU has a + new graphics rendering engine with a low memory footprint and optimization + for MCUs and other resource-constrained devices. + + Connect MCU boards to a computer to build applications for them. Deploy the + applications on MCUs to run and debug them. + + For a list of \QMCU reference implementations, see + \l{\QMCU - Supported Target Platforms}. \section1 Requirements @@ -33,52 +31,98 @@ \list \li \QMCU SDK (only available for Windows and Linux) - \li \l{https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm} - {GNU ARM Embedded Toolchain} + \li \l {\QMCU - Prerequisites}{Suitable toolchain} \endlist + The toolchains are available for cross-compilation on Microsoft Windows, + Linux, and macOS. However, the Qt for \QMCU SDK is currently only available + for Windows and Linux. + The hardware-specific requirements vary depending on the hardware platform you are developing for. For more information see: \list \li \l{Getting Started on NXP} \li \l{Getting Started on STM} \li \l{Getting Started on Renesas} + \li \l{Getting Started on Infineon} \endlist - \section1 Setting Up the Development Environment + \section1 \QMCU SDKs + + While you can use the latest \QC version to develop with any \QMCU SDK, the + following combinations have been tested to work well. + + \table + \header + \li \QC version + \li \QMCU SDK version + \row + \li 12.0.2 or later + \li 2.7 or later + \row + \li 11.0.3 + \li 2.6 + \row + \li 10.0.2 + \li 2.5 + \row + \li 10.0.0 + \li 2.4 + \row + \li 9.0.0 + \li 2.3 + \row + \li 7.0.0 up to 8.0.2 + \li 2.0 up to 2.2 + \row + \li 6.0.x + \li 1.3 up to 2.2 + \row + \li 4.12.4 up to 5.0.3 + \li 1.3 up to 1.9 + \row + \li 4.12.2 or 4.12.3 + \li 1.2 + \row + \li 4.12.0 or 4.12.1 + \li 1.1 + \row + \li 4.11.x + \li 1.0 + \endtable - You must download and install the required software and create connections - between \QC and MCUs. The following subsections guide you through the - setup process. + \sa {Enable and disable plugins}, {MCUs}{How To: Develop for MCUs}, + {Developing for MCUs}, {\QMCU} +*/ - \section2 MCU Plugin +/*! + \page creator-how-to-create-mcu-kits.html + \previouspage creator-how-tos.html - To be able to develop applications for MCUs, you need the MCU plugin. - This plugin is enabled automatically by \QOI when you - install \QMCU. + \ingroup creator-how-to-mcu - \section2 Specifying MCU Settings + \title Connect MCU devices - To configure a connection between \QC and your MCU board, select - \preferences > \uicontrol Devices > \uicontrol MCU: + \note Enable the McuSupport plugin to develop for MCUs. - \image qtcreator-mcu-options.png "MCU preferences" + To configure a connection between \QC and your MCU board: \list 1 - \li In the \uicontrol {\QMCU SDK} field, specify the path - to the directory where you installed \QMCU SDK. - \li In the \uicontrol {Targets supported by the \QMCU SDK} - field, select your MCU board. - \li In the \uicontrol Requirements section, ensure that the - platform-specific requirements are met. This varies depending - on the target chosen: + \li Go to \preferences > \uicontrol Devices > \uicontrol MCU. + \li In \uicontrol {\QMCU SDK}, specify the path to the directory where + you installed \QMCU SDK. + \image qtcreator-preferences-mcu.webp {MCU preferences} + \li In \uicontrol {Targets supported by the \QMCU SDK}, select your MCU + board. + \li In \uicontrol Requirements, check that the platform-specific + requirements are met. This depends on the target: \list \li For STM32 targets: \list \li The \uicontrol {GNU ARM Embedded Toolchain} or \uicontrol {IAR ARM Compiler} path. \li The \uicontrol {STM32CubeProgrammer} install path. - \li The \uicontrol {MCU SDK} for the chosen target. + \li The \uicontrol {Board SDK} for the chosen target. \li The \uicontrol {FreeRTOS Sources} for the chosen target. \endlist \li For NXP targets: @@ -86,7 +130,7 @@ \li The \uicontrol {GNU ARM Embedded Toolchain} or \uicontrol {IAR ARM Compiler} path. \li The \uicontrol {MCUXpresso IDE} install path. - \li The \uicontrol {MCU SDK} for the chosen target. + \li The \uicontrol {Board SDK} for the chosen target. \li The \uicontrol {FreeRTOS Sources} for the chosen target. \endlist \li For Renesas targets: @@ -94,74 +138,103 @@ \li The \uicontrol {Green Hills Compiler} path. \li The \uicontrol {Renesas Graphics Library} path. \endlist + \li For Infineon targets: + \list + \li The \uicontrol {Green Hills Compiler for ARM} path. + \li The \uicontrol {Graphics Driver for Traveo II Cluster Series} + path. + \li The \uicontrol {Infineon Auto Flash Utility} path. + \endlist \endlist - \li Select the + \li Select \uicontrol {Automatically create kits for all available targets on start} - option to create kits automatically the next time Qt Creator is - started. - \note You could also use \uicontrol {Create Kit} to manually - create kits for the chosen target. - \li Select \uicontrol Apply to save the settings. + to create kits automatically the next time \QC starts. + \note Select \uicontrol {Create Kit} to manually create kits for the + target. + \li Select \uicontrol Apply to save the preferences. \endlist - \note When updating to other versions of the \QMCU SDK, \QC will - ask you if you want to replace the existing kits, or create new ones - alongside. This can also be done manually, for each individual target, - via \uicontrol {Update Kit} and \uicontrol {Create Kit}, respectively. - - \section2 Adding MCU Devices - - \note This optional step is not necessary if you have already - set up the MCU SDK as outlined in \l{Specifying MCU Settings}. + \section1 Add MCU devices \QC automatically adds a default MCU device when you select \uicontrol Apply in the \uicontrol MCU tab after configuring the - MCU tool chain. + MCU toolchain. - \image qtcreator-mcu-device.png "MCU devices" + \image qtcreator-mcu-device.png {MCU devices} To add MCU devices, select \preferences > \uicontrol Devices > \uicontrol Add > \uicontrol {MCU Device} > \uicontrol {Start Wizard}: \list 1 - \li In the \uicontrol Name field, give the device a name. - \li In the \uicontrol Type field, select the board type. + \li In \uicontrol Name, give the device a name. + \li In \uicontrol Type, select the board type. \li Select \uicontrol Apply to add the device. \endlist - \section2 Managing MCU Kits + \sa {Enable and disable plugins}, {MCUs}{How To: Develop for MCUs}, + {Developing for MCUs} +*/ + + +/*! + \page creator-how-to-manage-mcu-kits.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-mcu - \QC automatically adds kits for all the available targets, if the + \title Manage MCU Kits + + \note Enable the McuSupport plugin to develop for MCUs. + + \QC automatically adds kits for all the available MCU targets if you select \uicontrol {Automatically create kits for all available targets on start} - option is enabled under the \uicontrol MCU settings tab. You can also - create kits for individual targets manually, as outlined - in \l{Specifying MCU Settings}. + in \preferences > \uicontrol Devices > \uicontrol MCU. + + \image qtcreator-preferences-kits-mcu.webp {MCU kit} - \image qtcreator-mcu-kit.png "MCU kits" + \note When you update the \QMCU SDK, \QC asks you whether you want to replace + the existing kits or create additional kits. To do this manually for each + target, select \uicontrol {Update Kit} or \uicontrol {Create Kit}. - You can edit and/or remove individual kits in \preferences > \uicontrol Kits. + To add new kits, go to \preferences > \uicontrol Devices > \uicontrol MCU, + and select \uicontrol {Create Kit}. This adds the paths to the kit's toolkits + and SDKs, and keeps them synchronized when you select \uicontrol Apply or + \uicontrol OK. - However, for adding new kits you should use the \uicontrol {Create Kit} - button in the {\QMCU} settings tab. This method adds the paths to - the kit's toolkits and SDKs, and keeps them synchronized when selecting - \uicontrol Apply or \uicontrol OK. + \section1 Change or remove MCU kits + + To change or remove individual kits, go to \preferences > \uicontrol Kits. The \uicontrol {MCU dependencies} field displays paths to 3rd party software required for MCU development with the current kit. - \section1 Running Applications on MCUs + \sa {Enable and disable plugins}, {MCUs}{How To: Develop for MCUs}, + {Developing for MCUs} +*/ + +/*! + \page creator-how-to-run-on-mcu-devices.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-mcu - You can use a wizard to set up a project for developing an application that - you can run on MCUs. The project uses a subset of QML and Qt Quick Controls + \title Create MCU projects + + \note Enable the McuSupport plugin to develop for MCUs. + + Create a project for developing an application that you can run on MCUs. + The project imports a subset of QML and Qt Quick Controls types that are supported by \QMCU. For more information about developing - applications for MCUs, see the \QMCU documentation. + applications for MCUs, see \l {Qt for MCUs}. To create an application and run it on a MCU board: \list 1 - \li Select \uicontrol File > \uicontrol {New Project} > - \uicontrol {Application (\QMCU)} > - \uicontrol {MCU Support Application} > \uicontrol Choose. + \li Go to \uicontrol File > \uicontrol {New Project}. + \image qtcreator-mcu-new-project.webp {New Project dialog} + \li Select \uicontrol {QmlProject Application (\QMCU)} > + \uicontrol {Qt for MCUs Empty Application} or + \uicontrol {Qt for MCUs Example Application} > \uicontrol Choose. \li Follow the instructions of the wizard to create the project. \li Select \uicontrol Projects > \uicontrol {Build & Run}, and then select the kit for building the application and running it on the @@ -170,37 +243,7 @@ Usually, you can use the default settings. \endlist - \section1 Supported \QMCU SDKs - - \note The \QMCU SDK 2.3 requires \QC 9.0.0, or later. - - The following table lists the \QC versions you can use to develop - applications with particular \QMCU SDK versions. - - \table - \header - \li \QC version - \li \QMCU SDK version - \row - \li 9.0.0 or later - \li 2.0 or later - \row - \li 7.0.0 up to 8.0.2 - \li 2.0 up to 2.2 - \row - \li 6.0.x - \li 1.3 up to 2.2 - \row - \li 4.12.4 up to 5.0.3 - \li 1.3 up to 1.9 - \row - \li 4.12.2 or 4.12.3 - \li 1.2 - \row - \li 4.12.0 or 4.12.1 - \li 1.1 - \row - \li 4.11.x - \li 1.0 - \endtable + \sa {Configure projects for running}, {Enable and disable plugins}, + {MCUs}{How To: Develop for MCUs}, {Use project wizards}, + {Developing for MCUs} */ diff --git a/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc b/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc index 1a1c04edfe..b2ea02c128 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-configuring.qdoc @@ -22,10 +22,10 @@ Qt versions and compilers by adding the paths to them and by creating \l{glossary-buildandrun-kit}{kits} that use them. - To make \QC behave more like your favorite code editor or IDE, you can - change the settings for keyboard shortcuts, color schemes, generic - highlighting, code snippets, and version control systems. In addition, - you can enable and disable \QC features by managing plugins. + To make \QC behave more like your favorite code editor or IDE, + change the preferences for keyboard shortcuts, color schemes, generic + highlighting, code snippets, and version control systems. Manage plugins + to turn on and off \QC features. The following sections summarize the options that you have and point you to detailed information to help you specify any required settings and to make @@ -33,8 +33,8 @@ \section1 Checking Build and Run Settings - \QC is an integrated development environment (IDE) that you can use to - develop Qt applications. While you can use \QOI to install \QC, + \QC is an integrated development environment (IDE) for creating + applications. While you can use \QOI to install \QC, the stand-alone \QC installer never installs Qt or any Qt tools, such as qmake. To use \QC for Qt development, you also need to install a Qt version and a compiler. If you update the compiler version later, you @@ -45,9 +45,7 @@ available in \QC. If it does not, you must add the kits yourself to tell \QC where everything is. - To add kits, select \preferences > \uicontrol Kits > \uicontrol Add. - - For more information, see \l{Add kits}. + To add kits, go to \preferences > \uicontrol Kits and select \uicontrol Add. Each kit consists of a set of values that define one environment, such as a \l{glossary-device}{device}, compiler, and Qt version. If \preferences > @@ -57,48 +55,41 @@ If \uicontrol Auto-detected still does not show the Qt version, select \uicontrol {Add} to add it manually. - For more information, see \l{Add Qt versions}. - Also check that \preferences > \uicontrol Kits > \uicontrol {Compilers} shows your compiler. - For more information, see \l{Add compilers}. + Connect devices to the computer via USB to run, debug, and analyze + applications on them. You can connect Linux-based devices also + over a WLAN. Configure a connection between \QC and the computer, and + select the device in a kit. - You can connect devices to the development PC to run, debug, and - analyze applications on them from \QC. You can connect the device to the - development PC via USB. Additionally, you can connect Linux-based devices - over a WLAN. You must also configure a connection between \QC and the - development PC and specify the device in a kit. + To add devices, go to \preferences > \uicontrol Devices > + \uicontrol Devices and select \uicontrol Add. - To add devices, select \preferences > \uicontrol Devices > - \uicontrol Devices > \uicontrol Add. - - For more information, see \l{Connecting Devices}. + For more information, see \l{Manage Kits}{How To: Manage Kits} and + \l{Develop for Devices}{How To: Develop for Devices}. \section1 Changing Keyboard Shortcuts You can use \QC with your favorite keyboard shortcuts. - To view and edit all keyboard shortcuts defined in \QC, select - \preferences > - \uicontrol Environment > - \uicontrol Keyboard. For more information, see \l{Keyboard Shortcuts}. + To view and edit all keyboard shortcuts defined in \QC, go to \preferences > + \uicontrol Environment > \uicontrol Keyboard. For more information, see + \l{Keyboard Shortcuts}. \section1 Changing Color Schemes - Themes enable you to customize the appearance of the \QC UI: widgets, - colors, and icons. + Themes set the appearance of the \QC UI: widgets, colors, and icons. - To switch themes, select \preferences > \uicontrol Environment > - \uicontrol Interface, and then select a theme in the \uicontrol Theme field. + To switch themes, go to \preferences > \uicontrol Environment > + \uicontrol Interface and select a theme in \uicontrol Theme. - You can use the \QC text and code editors with your favorite color scheme - that defines how to highlight code elements and which background color to - use. You can select one of the predefined color schemes or create custom - ones. The color schemes apply to highlighting C++ files, QML files, and - generic files. + Use the \QC text and code editors with your favorite color scheme that sets + highlighting of code elements and the background color. Select one of the + predefined color schemes or create custom ones. The color schemes apply to + highlighting C++ files, QML files, and generic files. - To change the color scheme, select \preferences > + To change the color scheme, go to \preferences > \uicontrol {Text Editor} > \uicontrol {Font & Colors}. For more information, see \l{Change editor colors}. @@ -108,7 +99,7 @@ highlighting engine for Kate syntax definitions. \QC comes with most of the commonly used syntax files, and you can download additional files. - To download and use highlight definition files, select \preferences > + To download and use highlight definition files, go to \preferences > \uicontrol {Text Editor} > \uicontrol {Generic Highlighter}. For more information, see \l{Download highlight definitions}. @@ -117,10 +108,10 @@ As you write code, \QC suggests properties, IDs, and code snippets to complete the code. It lists context-sensitive suggestions for - the statement currently under your cursor. You can add, modify, and remove + the statement currently under your cursor. Add, modify, and remove snippets in the snippet editor. - To open the snippet editor, select \preferences > + To open the snippet editor, go to \preferences > \uicontrol {Text Editor} > \uicontrol Snippets. For more information, see \l{Snippets}. @@ -131,8 +122,7 @@ to configure the version control in any special way to make it work with \QC. - However, some configuration options are available and you can set them in - \preferences > + However, you can set some configuration options in \preferences > \uicontrol {Version Control} > \uicontrol General. For more information about the supported functions, see @@ -144,13 +134,15 @@ You can \l{Enable and disable plugins}{enable} disabled plugins if you need them and disable plugins you don't need. - You can \l{Install plugins}{download and install} more plugins from + \l{Install plugins}{Download and install} more plugins from \l{https://marketplace.qt.io/}{Qt Marketplace} or some other source, such as \l{https://github.com/}{GitHub}. - To enable and disable plugins, select \uicontrol Help > + To enable and disable plugins, go to \uicontrol Help > \uicontrol {About Plugins}. - To install plugins, select \uicontrol Help > \uicontrol {About Plugins} > - \uicontrol {Install Plugins}. + To install plugins, go to \uicontrol Help > \uicontrol {About Plugins} and + select \uicontrol {Install Plugins}. + + \sa {Install \QC}, {Reset \QC settings}, {Preferences} */ diff --git a/doc/qtcreator/src/overview/creator-only/creator-deployment-overview.qdoc b/doc/qtcreator/src/overview/creator-only/creator-deployment-overview.qdoc deleted file mode 100644 index 000017249a..0000000000 --- a/doc/qtcreator/src/overview/creator-only/creator-deployment-overview.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -// Copyright (C) 2020 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -// ********************************************************************** -// NOTE: the sections are not ordered by their logical order to avoid -// reshuffling the file each time the index order changes (i.e., often). -// Run the fixnavi.pl script to adjust the links to the index order. -// ********************************************************************** - -/*! - \previouspage creator-running-targets.html - \page creator-deployment.html - \nextpage creator-deploying-android.html - - \title Deploying to Devices - - Deploy configurations in the \uicontrol Projects mode - \uicontrol {Run Settings} handle the packaging of the application as an - executable and copying it to a location you want to run the executable at. - The files can be copied to a location in the file system of the development - PC or a \l{glossary-device}{device}. - - \list - - \li \l{Deploying to Android} - - When you deploy the application to an Android device, \QC copies - the application files to the device. In addition, you can determine - the Qt libraries to use. - - \li \l {Deploying to Boot2Qt} - - When you deploy the application to a Boot2Qt device, \QC copies - the application files to the connected device. You can then test - and debug the application on the device with \QC. - - \li \l{Deploying to QNX Neutrino} - - When you deploy the application to a QNX Neutrino device, \QC copies - the application files to the connected device. You can then test and - debug the application on the device with \QC. - - \li \l{Deploying to Remote Linux} - - When you deploy the application to a generic Linux-based device, \QC - copies the application files to the connected device. You can then - test and debug the application on the device with \QC. - \endlist -*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc b/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc index 67605429f8..6a2602b34d 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-desktop-platforms.qdoc @@ -45,8 +45,7 @@ \li libxft-dev \li libxi-dev \li libxrandr-dev - \li libgl-dev and libglu-dev if you use Qt OpenGL (deprecated - in Qt 5) or Qt GUI OpenGL functions + \li libgl-dev and libglu-dev if you use Qt GUI OpenGL functions \endlist \section1 macOS diff --git a/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc b/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc index b1531ae685..e735c95adf 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-getting-started.qdoc @@ -14,8 +14,9 @@ \title Getting Started - To learn the basics of \QC, take the \e {Getting Started with Qt Creator} - course in \l{https://www.qt.io/courses/}{Qt Learning}. + To learn the basics of \QC, take the + \l{https://www.qt.io/academy/course-catalog#getting-started-with-qt-creator} + {Getting Started with Qt Creator} course in Qt Academy. For more information about installing \QC, see \l{Install \QC}. diff --git a/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc b/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc index ac5e1cae6b..2cbac901aa 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-glossary.qdoc @@ -77,7 +77,7 @@ \li \QC groups build and run specific settings as kits to make cross-platform development easier. Each kit consists of a set of values that define one environment, such as a \e {device}, - tool chain, Qt version, and debugger command to use. Configure kits at + toolchain, Qt version, and debugger command to use. Configure kits at \preferences > \uicontrol Kits. \row diff --git a/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc b/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc index de7c8b45d3..8d31098332 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-issues.qdoc @@ -41,7 +41,7 @@ settings are stored locally. \li The Okteta KDE custom widget plugin might be installed as part of - some Linux distributions. It can cause Qt Designer to crash. For + some Linux distributions. It can cause \QD to crash. For more information, see: \list diff --git a/doc/qtcreator/src/overview/creator-only/creator-mobile-platforms.qdoc b/doc/qtcreator/src/overview/creator-only/creator-mobile-platforms.qdoc deleted file mode 100644 index fef448c3f1..0000000000 --- a/doc/qtcreator/src/overview/creator-only/creator-mobile-platforms.qdoc +++ /dev/null @@ -1,73 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \page creator-mobile-platforms.html - \previouspage creator-reference.html - - \ingroup creator-reference-platforms - - \title Mobile Platforms - - \brief Mobile platforms that you can develop applications for. - - You can develop applications for the following mobile platforms: - - \list - \li \l Android - \li \l iOS - \endlist - - You must install the tool chain for building applications for the targeted - mobile platform on the development PC and use \QMT to - install Qt libraries that are built for the platform. You can then add a - \l{glossary-buildandrun-kit}{kit} with the tool chain and the Qt version - for the device's architecture. When possible, \QMT creates - suitable kits for you. - - You can connect mobile devices to the development PC and select the - appropriate kit to build, run, debug, and analyze applications from \QC. - - Before starting application development, analyze and define the requirements, - scope, and functionality of the application to ensure efficient functionality - and a smooth user experience on mobile devices. - - \section1 Android - - Starting from Qt 5.14.0, the Qt for Android package has all the - architectures (ABIs) installed as one. You can let \QC automatically - create kits for installed Qt version and tool chains. - - The following topics have more information about developing applications - for Android devices: - - \list - \li \l{Connecting Android Devices} - \li \l{Deploying to Android} - \li \l{Run on many platforms} - \li \l{Creating a Mobile Application} - \li \l{Debugging on Android Devices} - \li \l{Qt for Android} - \endlist - - \section1 iOS - - \note Deployment, running, and debugging on iOS 17 devices are not supported. - - To be able to use \QC on \macos, you must install Xcode, and therefore - you should already have the tool chain for building applications for - iOS. \QC automatically detects the tool chain and creates the necessary - kits to build applications for and run them on configured iOS devices. - - The following topics have more information about developing applications - for iOS devices: - - \list - \li \l{Connecting iOS Devices} - \li \l{Run on many platforms} - \li \l{Creating a Mobile Application} - \li \l{Qt for iOS} - \endlist - - \sa {Optimizing Applications for Mobile Devices}, {Supported Platforms} -*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc b/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc deleted file mode 100644 index fc33900659..0000000000 --- a/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc +++ /dev/null @@ -1,85 +0,0 @@ -// Copyright (C) 2022 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -// ********************************************************************** -// NOTE: the sections are not ordered by their logical order to avoid -// reshuffling the file each time the index order changes (i.e., often). -// Run the fixnavi.pl script to adjust the links to the index order. -// ********************************************************************** - -/*! - \page creator-connecting-mobile.html - \previouspage creator-deployment-embedded-linux.html - \nextpage creator-developing-android.html - - \title Connecting Devices - - You can connect \l{glossary-device}{devices} to the development PC to run, debug, - and analyze applications built for them from \QC. When you install Qt for a - target platform, such as Android or QNX, - the build and run settings for the development targets might be set up - automatically in \QC. - - You can connect the device to the development PC using a USB connection. - Additionally, you can connect Linux-based devices by using a WLAN - connection. - - The experimental WebAssembly plugin enables you to build your applications - in WebAssembly format, to deploy them, and to run them in a web browser. - - \list - - \li \l{Connecting Android Devices} - - Qt applications for Android are compiled as \c {shared objects} that - are loaded by a Java launcher that is part of Qt. - This is totally transparent to users. As Qt is composed of libraries - referencing each other, Qt 5 applications are only supported on - Android version 4.1 (API level 16), or later, and Qt 6 applications - on Android version 6.0 (API level 23), or later. You must install a - Qt version targeting Android and the Android SDK and NDK to develop - for Android devices. - - \li \l{Connecting Bare Metal Devices} - - You can connect bare metal devices to the development PC and use \QC - to debug applications on them with GDB or a hardware debugger. - - \li \l{Connecting Boot2Qt Devices} - - You can connect \l{Boot2Qt} devices to the development PC to run, - debug, and analyze applications built for them from \QC. - - \li \l {Adding Docker Devices} - - Create Docker devices from Docker images and use them to build, run, - and debug applications from \QC. - - \li \l{Connecting iOS Devices} - - You use the tools delivered with Xcode to connect devices to \QC. - \QC detects the tools and configured devices automatically and uses - the tools to build, deploy, and run applications. - - \li \l{Connecting MCUs} - - You can connect MCU boards to a development host to deploy, run, and - debug applications on them from \QC. - - \li \l{Connecting QNX Devices} - - You can connect QNX devices to the development PC to deploy, run and - debug applications on them from within \QC. This is currently only - supported for QNX Neutrino devices, and requires the QNX SDK to be - installed on the development PC. - - \li \l{Connecting Remote Linux Devices} - - If you have a tool chain for building applications for embedded - Linux devices installed on the development - PC, you can add it and the device to \QC. - - \endlist - - \sa {Building Applications for the Web}, {Run in Qt Application Manager} -*/ diff --git a/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc b/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc index b164224e84..127a59cf0d 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-overview.qdoc @@ -94,6 +94,11 @@ Load C++ plugins for QML to simulate data. \endlist + Use the QML live preview to preview a QML file or an entire Qt Quick + application on the desktop, as well as on Android and embedded Linux + devices. The changes you make to the UI are instantly visible to you + in the preview. + If you need a traditional user interface that has a clear structure and enforces a platform look and feel, use \l{Qt Widgets} and the integrated \l{\QD}. @@ -186,35 +191,66 @@ build the project. Build applications for, deploy them to, and run them on the desktop - environment or a device. With kits, as well as build, run, and deployment + environment or a device. With kits, as well as build, deploy, and run configurations, you can quickly switch between different setups and target platforms. For more information, see \l{Build and Run}{How To: Build and Run}, \l{Build Systems}, \l{Build Configurations}, and \l{Run Configurations}. - \section2 On Devices + \section2 Embedded Platforms + + You can develop applications for the following embedded platforms: + + \list + \li \l {Bare Metal} + \li \l {\B2Q} + \li \l {MCUs} + \li \l {QNX Neutrino} + \li \l {Remote Linux} + \endlist - When you install tool chains for device types as part of a Qt distribution, - the build and run configurations for the devices might be set up - automatically. However, you might need to install and configure some - additional software on the devices to be able to connect to them - from the computer. + Install the toolchain for building applications for the targeted + embedded platform on the computer, and then use \QOI to install Qt + libraries that are built for the platform. Add a kit with the toolchain and + the Qt version for the device's architecture. When possible, \QOI creates + suitable kits for you. - Deployment configurations handle the packaging and copying of the necessary + You can connect embedded devices to the computer and select the appropriate + kit to run, debug, and analyze applications built for them from \QC. + + \e {Deploy configurations} handle the packaging and copying of the necessary files to a location you want to run the executable at, such as the file system of a device. - For more information, see \l{Connecting Devices} and \l{Deploying to Devices}. + For more information, see \l{Develop for Devices}{How To: Develop for Devices} + and \l{Devices}. - \section2 Previewing QML + \section2 Mobile Platforms - Use the QML live preview to preview a QML file or an entire Qt Quick - application on the desktop, as well as on Android and embedded Linux - devices. The changes you make to the UI are instantly visible to you - in the preview. + You can develop applications for the following mobile platforms: - For more information, see \l{Validating with Target Hardware}. + \list + \li \l Android + \li \l iOS + \endlist + + Install the toolchain for building applications for the targeted mobile + platform on the computer, and then use \QOI to install Qt libraries that are + built for the platform. Add a kit with the toolchain and the Qt version for + the device's architecture. When possible, \QOI creates suitable kits for you. + + You can connect mobile devices to the computer and select the + appropriate kit to build, run, debug, and analyze applications from \QC. + + Before starting application development, analyze and define the requirements, + scope, and functionality of the application to ensure efficient functionality + and a smooth user experience on mobile devices. + + For more information, see + \l{Develop for Devices}{How To: Develop for Devices}, + \l{Optimizing Applications for Mobile Devices}, \l {Supported Platforms}, and + \l{Deploy Configurations}. \section1 Debugging Applications @@ -230,7 +266,7 @@ to find the next one. \endlist - \QC integrates several external native debuggers for inspecting the state of + \QC integrates several native debuggers for inspecting the state of your application while debugging. The debugger plugin automatically selects a suitable native debugger for each kit from the ones it finds on the computer. Edit the kits to override this choice. @@ -242,20 +278,20 @@ Connect devices to your computer to debug processes running on the devices. - For more information, see \l{Debugging}. + For more information, see \l{Debugging} and \l{Debug}{How To: Debug}. - \section1 Analyzing Source Code + \section1 Finding Issues in Source Code Devices have limited memory and CPU power, so you should use them carefully. \QC integrates code analysis tools for detecting memory leaks, profiling function execution, analyzing CPU use, and eliminating unnecessary complexity of code. Other tools provide code coverage and visualize trace events. - Install and configure the tools on your system to use them from \QC. - However, the QML Profiler is installed as part of \QC for profiling - Qt Quick applications. + Some tools, such as QML Profiler and Clang Tools, are installed with + \QC. Install and configure the other supported tools on the computer to use + them from \QC. - For more information, see \l{Analyzing Code}. + For more information, see \l{Analyzing Code} and \l{Analyze}{How To: Analyze}. \section1 Running Tests @@ -287,10 +323,32 @@ \image qtcreator-autotests.png - Map AUTs (Application Under Test) to \QC and run Squish test suites - and cases from it. + \section2 Using Squish + + \brief The experimental Squish plugin integrates Squish into \QC. + + \l{https://www.qt.io/product/quality-assurance/squish}{Squish} is an + automated GUI testing framework for testing Android, iOS, Java, \macos, + Qt, Tk, Windows, and XView applications, as well as HTML-based web + applications running in browsers. + + In \QC, you can: + + \list + \li Open existing Squish test suites. + \li Create new test suites and test cases. + \li Record test cases (in a very limited way compared to what you can do + inside the Squish IDE). + \li Use Squish Runner and Server to run test suites or cases and view + the results in the \uicontrol Squish \l{View output}{output}. + \li Set breakpoints before running tests to stop at certain locations and + inspect the local variables, similarly to when debugging a test. + \endlist + + To use the plugin, you must download and install Squish, create a connection + to the Squish Server, and specify the application under test (AUT) to run. - For more information, see \l{Test}{How To: Test} and \l{Using Squish}. + For more information, see \l{Test}{How To: Test}. \section1 Publishing Applications diff --git a/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc b/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc index 45432f561b..7415815ff0 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-reference.qdoc @@ -19,6 +19,20 @@ \annotatedlist creator-reference-analyzer + \section1 Debuggers + + Set up and use native debuggers to debug executable binary files, as well as + QML, Java, and Python source code. + + \annotatedlist creator-reference-debugger + + \section2 Debugger Views + + Inspect the state of your application while debugging in the + \uicontrol Debug mode. + + \annotatedlist creator-reference-debugger-views + \section1 Build Systems When you create projects, you can choose the build system to use for @@ -28,7 +42,7 @@ \annotatedlist creator-reference-build-systems - \section1 Build Configurations + \section2 Build Configurations Build configurations have everything you need to compile the sources into binaries. Build configurations use the tools and settings defined in their @@ -36,6 +50,35 @@ \annotatedlist creator-reference-build-configurations + \section1 Devices + + Connect devices to the computer to run, debug, and analyze applications + built for them from \QC. When you install Qt for a target platform, such + as Android or QNX, the build and run configurations for the development + targets might be set up automatically in \QC. + + \annotatedlist creator-reference-devices + + \section2 Deploy Configurations + + Deploy configurations handle the packaging of the application as an + executable and copying it to a location you want to run the executable at. + The files can be copied to a location in the file system of the computer + or a device. + + \annotatedlist creator-reference-deploy-configurations + + \section2 Run Configurations + + Run configurations start the application in the location where the + deploy configuration copied it. By default, when you select + \uicontrol Run, \QC builds the project, deploys it to the device + defined in the kit, and runs it there. If you did not make changes + to the project since you last built and deployed it, \QC simply runs + it again. + + \annotatedlist creator-reference-run-configurations + \section1 Editors When you open files, \QC chooses a suitable editor according to the file @@ -69,6 +112,10 @@ \annotatedlist creator-reference-preferences-cpp + \section2 Debugger + + \annotatedlist creator-reference-preferences-debugger + \section2 Kits Preferences for build and run kits. @@ -81,17 +128,6 @@ \annotatedlist creator-reference-preferences-text-editor - \section1 Run Configurations - - Run configurations start the application in the location where the - \e {deploy configuration} copied it. By default, when you select - \uicontrol Run, \QC builds the project, deploys it to the device - defined in the kit, and runs it there. If you did not make changes - to the project since you last built and deployed it, \QC simply runs - it again. - - \annotatedlist creator-reference-run-configurations - \section1 UI Design You can use a visual editor, \QD, for designing widget-based UIs diff --git a/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc b/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc index 9481519eb7..43c60144c4 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-supported-platforms.qdoc @@ -38,12 +38,7 @@ \li \image ok.png \li \image ok.png \row - \li \l Boot2Qt - \li \image ok.png - \li \image ok.png - \li \image ok.png - \row - \li \l{Remote Linux} + \li \l {\B2Q} \li \image ok.png \li \image ok.png \li \image ok.png @@ -53,7 +48,7 @@ \li \image ok.png \li \row - \li \l{Microcontroller Units (MCU)}{MCUs} + \li \l{MCUs} \li \image ok.png \li \li \image ok.png @@ -63,7 +58,12 @@ \li \image ok.png \li \inlineimage ok.png \row - \li \l{Building Applications for the Web}{WebAssembly} + \li \l{Remote Linux} + \li \image ok.png + \li \image ok.png + \li \image ok.png + \row + \li \l{Build applications for the web}{WebAssembly} \li \image ok.png \li \image ok.png \li \image ok.png @@ -74,5 +74,6 @@ \QC automatically runs scheduled checks for updates based on the settings specified in \preferences > \uicontrol Environment > \uicontrol Update. - \sa {Desktop Platforms}, {Embedded Platforms}, {Mobile Platforms} + \sa {Develop for Devices}{How To: Develop for Devices}, {Desktop Platforms}, + {Devices} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc b/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc index 3f24273f09..78eb3ecf68 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc @@ -51,7 +51,7 @@ If debug info is being generated, you can have it placed into separate files, rather than embedded into the binary, by selecting \uicontrol Enable in the \uicontrol {Separate debug info} field. For - more information, see \l{Using the Performance Analyzer}. To use default + more information, see \l{Analyze CPU usage}. To use default settings, select \uicontrol {Leave at Default}. \section1 Compiling QML diff --git a/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc b/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc index fa7663f02d..e6cb582b9b 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-how-to-add-wizards.qdoc @@ -44,5 +44,5 @@ to specify the position of the wizard. For example, \c B.MyClass. \endlist -\sa {Custom Wizards}, {Find settings files} + \sa {Run Qt Creator from the command line}, {Custom Wizards} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc index ac06f8cbd1..600b8f3079 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-build-run-tutorial.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -23,13 +23,12 @@ To run an example application on an Android or iOS device, you must set up the development environment for Android or iOS. For more information, see - \l{Connecting Android Devices} and \l{Connecting iOS Devices}. + \l{Developing for Android} and \l{Developing for iOS}. - To run an example application on a Boot2Qt device, you must set up - Boot2Qt on the development host and create connections + To run an example application on a \B2Q device, you must set up + \B2Q on the development host and create connections between the host and devices. For more information, see - \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guides} + \l{\B2Q: Documentation}. If you have \l{Qt Design Studio Manual}{\QDS} installed, you can open \QDS examples from \QC in \QDS. @@ -48,13 +47,20 @@ \li Select an example in the list of examples. You can also use tags (3) to filter examples. For instance, enter - the \uicontrol Boot2Qt tag (commercial only) in the search field - (4) to list examples that you can run on Boot2Qt devices. + the \uicontrol \B2Q tag (commercial only) in the search field + (4) to list examples that you can run on \B2Q devices. + + \li In \uicontrol {Configure Project}, select + \l{glossary-buildandrun-kit}{kits} for building the example for the + target platforms. + + \image qtcreator-configure-project.webp {Configure Project view} + + \li Select \uicontrol {Configure Project}. \li To check that you can compile and link the application code for a - device, click the \uicontrol {Kit Selector} and select a - \l{glossary-buildandrun-kit}{kit} for the - device. + device, click the \uicontrol {Kit Selector} and select the kit for + the device. \image qtcreator-examples-kit-selector.webp {Selecting a kit to build with} @@ -62,7 +68,7 @@ automatically detected the installed kit. If you cannot see any kits, see \l{Add kits}. - \li Click \inlineimage icons/run_small.png + \li Select \inlineimage icons/run_small.png (\uicontrol Run) to build and run the application. \li To see the compilation progress, press \key{Alt+4} to open @@ -70,9 +76,8 @@ If build errors occur, check that you have a Qt version, a \l{Add compilers}{compiler}, and the necessary kits installed. If - you are building for an \l{Connecting Android Devices}{Android device} - or \l{Connecting iOS Devices}{iOS device}, check that you set up the - development environment correctly. + you are building for an Android or iOS device, check that you set up + the development environment correctly. The \uicontrol Build progress bar on the toolbar turns green when you build the project successfully. The application opens on the @@ -80,4 +85,7 @@ \endlist + \sa {Manage Kits}{How To: Manage Kits}, {Open projects}, + {Developing for Android}, {Developing for iOS}, + {Compile Output}, {\B2Q: Documentation}, {Qt Design Studio Manual} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc deleted file mode 100644 index bd4743a437..0000000000 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-building-running.qdoc +++ /dev/null @@ -1,50 +0,0 @@ -// Copyright (C) 2019 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -// ********************************************************************** -// NOTE: the sections are not ordered by their logical order to avoid -// reshuffling the file each time the index order changes (i.e., often). -// Run the fixnavi.pl script to adjust the links to the index order. -// ********************************************************************** - -/*! - \previouspage creator-scxml.html - \page creator-building-running.html - \nextpage creator-live-preview.html - - \title Running on Devices - - \QC supports running and deploying Qt applications that you build - for different target platforms or with different compilers, debuggers, or - Qt versions. \l{glossary-buildandrun-kit}{Kits} define the tools, - \l{glossary-device}{device} type and other settings to use when building and - running your project. - - \list - - \li \l {Validating with Target Hardware} - - You can use the QML live preview to preview a QML file or an - entire Qt Quick application on the desktop, as well as on - Android and embedded Linux devices. The changes you make to - the UI are instantly visible to you in the preview. - - \li \l{Deploying to Devices} - - \e {Deploy configurations} handle the packaging and copying of - the necessary files to a location you want to run the executable - at. The files can be copied to a location in the file system of - the development PC or a device. - - \li \l{Connecting Devices} - - When you install tool chains for device types as part of a Qt distribution, - the build and run settings for the devices might be set up - automatically. However, you might need to install and configure some - additional software on the devices to be able to connect to them - from the development PC. - - \endlist - - \sa {Build and Run}{How To: Build and Run} -*/ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc index d42df965a7..7cfb8f86e0 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc @@ -36,7 +36,7 @@ \li Select the \uicontrol {Build and Run Kit Selector} icon or go to \uicontrol Build > \uicontrol {Open Build and Run Kit Selector} to select the build and run \l{glossary-buildandrun-kit}{kit} or an - \l{Managing Android Virtual Devices (AVD)}{Android device}. + \l{Manage AVDs}{Android device}. \image qtcreator-kit-selector.webp {Kit selector} @@ -105,7 +105,7 @@ \uicontrol Projects view. \sa {Configure projects for building}, {Build and Run}{How To: Build and Run}, - {Adding Docker Devices}, {Specifying Build Settings} + {Add Docker devices}, {Specifying Build Settings} */ /*! diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc index d92e8c90a4..42cc51bef9 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-compilers.qdoc @@ -103,8 +103,8 @@ \li Other than the listed compilers and remote compilers. \endtable - The emscripten compiler is tool chain for compiling to - \l{Building Applications for the Web}{WebAssembly}. + The emscripten compiler is toolchain for compiling to + \l{Build applications for the web}{WebAssembly}. \section2 Bare-metal compilers @@ -145,10 +145,10 @@ \endcode If these commands show paths, they have been added to the global PATH - variable during the installation of a tool chain based on Cygwin or \MinGW, + variable during the installation of a toolchain based on Cygwin or \MinGW, even though this is against Windows conventions. - To keep working with the third-party tool chain, create a new shell link + To keep working with the third-party toolchain, create a new shell link that adds the required paths (as Visual Studio and Qt do). The shell link must point to cmd.exe: @@ -157,19 +157,19 @@ where the /K parameter carries out the command specified in the bat file. Create the myenv.bat file at \e path_to, which should be in a convenient - location. In the file, specify the paths to the tool chains. For example, + location. In the file, specify the paths to the toolchains. For example, \c {set PATH=C:\path1;C:\path2;%PATH%} - where \e path1 and \e path2 are paths to the tool chains. + where \e path1 and \e path2 are paths to the toolchains. Finally, remove the paths from the global PATH, reboot the computer, and run the \c where commands again to verify that the global PATH is now clean. - You can use the shell link to run the tools in the third-party tool chains. + You can use the shell link to run the tools in the third-party toolchains. \sa {Compilers}, {Add Nim compilers}, {Add custom compilers}, - {Connecting Bare Metal Devices}, {Supported Platforms} + {Developing for Bare Metal Devices}, {Supported Platforms} */ /*! diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc index f91d6e2b0c..5388f7c6e5 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-creating.qdoc @@ -45,7 +45,7 @@ \uicontrol {New File} dialogs you can see an icon (1), a display name (2), and a description (3) of the wizard. - \image qtcreator-custom-wizard.png {Wizard details in the New Project dialog} + \image qtcreator-custom-wizard.webp {Wizard details in the New File dialog} In most project wizards, you can choose the build system to use for building the project: qmake, CMake, Qbs, and possibly others, depending on @@ -66,7 +66,7 @@ The installers create \l{glossary-buildandrun-kit}{kits} and specify build and run settings for the installed device types. However, you might need to install and configure some additional software on the devices to be able to - \l{Connecting Devices}{connect} to them from the development PC. + \l{Develop for Devices}{connect} to them from the computer. \sa {Manage Projects}{How To: Manage Projects}, {Custom Wizards} */ @@ -146,7 +146,7 @@ launcher for debugging and analysis tools. \row \li Squish - \li Create new \l {Using Squish}{Squish test suites}. + \li Create new Squish test suites. \endtable diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc index c2d2fe9e2d..f2d8d25424 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards-json.qdocinc @@ -238,7 +238,7 @@ { "key": "CN", "value": "%{JS: Cpp.className(value('Class'))}" }, { "key": "Base", "value": "%{JS: value('BaseCB') === '' ? value('BaseEdit') : value('BaseCB')}" }, { "key": "isQObject", "value": "%{JS: (value('Base') === 'QObject' || value('Base') === 'QWidget' || value('Base') === 'QMainWindow' || value('Base') === 'QQuickItem' ) ? 'true' : 'false'}" }, - { "key": "GUARD", "value": "%{JS: Cpp.classToHeaderGuard(value('Class'), Util.suffix(value('HdrFileName'))}" }, + { "key": "GUARD", "value": "%{JS: Cpp.headerGuard(value('HdrFileName'))}" }, { "key": "SharedDataInit", "value": "%{JS: value('IncludeQSharedData') ? 'data(new %{CN}Data)' : '' }" } ], \endcode diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc index 3abd3a1ab6..f4d7c81e63 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-custom-wizards.qdoc @@ -45,7 +45,7 @@ and \uicontrol {New File} dialogs. For each wizard, it shows an icon (1), a display name (2), and a description (3). - \image qtcreator-custom-wizard.png + \image qtcreator-custom-wizard.webp {New File wizard} \section1 Wizard Types diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc index 8762a9e97b..59db592705 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-debuggers.qdoc @@ -75,5 +75,6 @@ The debugger disappears from the list when you select \uicontrol Apply. Until then, you can cancel the deletion by clicking \uicontrol Restore. - \sa {Debugging}, {Setting Up Debugger}, {Troubleshooting Debugger} + \sa {Debugging}, {Debuggers}, {Debugger}, {Supported Native Debuggers}, + {Troubleshooting Debugger} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc index e4e682d2a6..2a57fcfaac 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc @@ -125,7 +125,7 @@ you first need to deploy your executable and possibly other files. \QC does that for you automatically if you enter the necessary information. This works the same way as explained for CMake in - \l {Deploying to Remote Linux}, + \l {Remote Linux Deploy Configuration}, except that you also need to include your application binary in the list. \section1 Create a run configuration diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc index 4d0e903863..1e2b8ed818 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc @@ -25,18 +25,16 @@ You can add kits for the desktop and for the following types of devices: \list - \li \l{Connecting Android Devices}{Android} - \li \l{Connecting Bare Metal Devices}{Bare Metal} - \li \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt} (commercial only) - \li \l{Emulator}{Boot2Qt Emulator} (commercial only) - \li \l{Adding Docker Devices}{Docker} (experimental) - \li \l{Connecting iOS Devices}{iOS} + \li \l{Developing for Android}{Android} + \li \l{Developing for Bare Metal Devices}{Bare Metal} + \li \l{\B2Q: Documentation}{\B2Q} (commercial only) + \li \l{Add Docker devices}{Docker} (experimental) + \li \l{Developing for iOS}{iOS} \li iOS Simulator - \li \l{Connecting MCUs}{MCU} (commercial only) - \li \l{Connecting QNX Devices}{QNX} - \li \l{Connecting Remote Linux Devices}{Remote Linux} - \li \l{Building Applications for the Web}{WebAssembly Runtime} + \li \l{Developing for MCUs}{MCU} (commercial only) + \li \l{Add a QNX Neutrino device}{QNX} + \li \l{Developing for Remote Linux Devices}{Remote Linux} + \li \l{Build applications for the web}{WebAssembly Runtime} \endlist To add kits: @@ -74,7 +72,7 @@ \title Kits \brief Set kit preferences. A kit consists of a set of values that define - one environment, such as a \e {device}, tool chain, Qt version, and debugger + one environment, such as a \e {device}, toolchain, Qt version, and debugger command to use. Typically, only a subset of the kit preferences is relevant for a particular @@ -136,7 +134,7 @@ cross-compiling, leave this field empty. \row \li \uicontrol {Emulator skin} - \li Skin to use for the \l {Emulator}{Boot2Qt Emulator Device}. + \li Skin to use for the \l {Emulator}{\B2Q Emulator Device}. \row \li \uicontrol {Compiler} \li C or C++ compiler that you use to build the project. You can add @@ -147,6 +145,9 @@ This setting is used to tell the code model which compiler is used. If your project type and build tool support it, \QC also tells the build tool to use this compiler for building the project. + + \note qmake ignores the value of this field and fetches the compiler + information from \uicontrol {Qt mkspec}, which you can change. \row \li \uicontrol Environment \li Select \uicontrol Change to modify environment variable values for diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc index f631e67389..66b69a573f 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-opening.qdoc @@ -63,15 +63,15 @@ To re-configure projects: \list 1 - \li In the \uicontrol {Configure Project} tab, select + \li In \uicontrol {Configure Project}, select \l{glossary-buildandrun-kit}{kits} for building and running your project. - \image qtcreator-open-project-kits.png {Configure Project tab} + \image qtcreator-configure-project.webp {Configure Project view} \li Select \uicontrol {Configure Project}. \endlist - The \uicontrol {Configure Project} tab displays a list of kits that you - install on the development PC and configure in \preferences > \uicontrol Kits. + \uicontrol {Configure Project} shows a list of kits that you + install on the computer and configure in \preferences > \uicontrol Kits. Even if you do not intend to build the project, the C++ and QML code models need a Qt version and compiler to offer code completion. To specify them, diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc index 0b06e1d84c..48958f8846 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-qt-versions.qdoc @@ -108,28 +108,45 @@ To verify the installation of a particular Qt version, \QC calls \c {qmake -query} and checks that the directories referenced in the - output exist. When \QC complains about the installation of a self-built Qt - version, try running \c {make install} in the build directory to actually - install Qt into the configured location. If you installed Qt using the Qt - Installer, run \QMT to check for updates or to reinstall - the Qt version. + output exist. If you installed Qt using \QOI, run + \QMT to check for updates or to reinstall the Qt version. - \section1 Minimum requirements - If your build of Qt is incomplete but you still want to use qmake as build - system, you need to ensure the following minimum requirements to use that - setup with \QC. + \section2 Self-built Qt versions - \list 1 + To build projects with a self-built Qt version, add it as described in + \l{Set up new Qt versions}. + + Your Qt has to meet the following minimum requirements: + + \list \li qmake is an executable that understands the \c -query command-line argument. \li The \c bin and \c include directories have to exist. \QC fetches these directories by running \c{qmake -query}. - \li The \c mkspecs directory should be complete enough to parse .pro - files. \endlist - If your Qt version has no \c libQtCore.so, \QC cannot detect the ABI. + Add a kit for the Qt version and configure it for CMake. + + \QC issues warnings if: + + \list + \li \c libQtCore.so is missing, so \QC cannot detect the ABI. + \li \c toolchain.cmake is missing. For example, you built Qt with the + \c -static option for an x86 platform. + \endlist + + Try the following: + + \list + \li Run \c {make install} in the build directory to install Qt into the + configured location. + \li Set the value of the \c CMAKE_PREFIX_PATH variable in \preferences > + \uicontrol Kits > \uicontrol Kits > \uicontrol {CMake Configuration} + to the location where you installed Qt. + \endlist + + \image qtcreator-edit-cmake-configuration-self-built-qt.webp {Setting the path to a self-built Qt} - \sa {kits-tab}{Kits} + \sa {Manage Kits}{How To: Manage Kits}, {kits-tab}{Kits} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc index f1b08ac048..b177af0b8d 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build-qbs.qdoc @@ -30,7 +30,7 @@ If debug info is being generated, you can have it placed into separate files, rather than embedded into the binary, by selecting \uicontrol Enable in the \uicontrol {Separate debug info} field. For - more information, see \l{Using the Performance Analyzer}. To use default + more information, see \l{Analyze CPU usage}. To use default settings, select \uicontrol {Leave at Default}. For more information about the QML debugging options, see @@ -59,7 +59,7 @@ \endlist \li In the \uicontrol ABIs field, select the ABIs for - the \l{Connecting Android Devices}{Android} device + the \l{Developing for Android}{Android} device architectures to build the project for. \li In the \uicontrol {Parallel jobs} field, specify the number of diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc index 31bc8204d4..b3ababb5fb 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc @@ -56,8 +56,8 @@ \section1 Build on remote devices - You can build applications on \l{Connecting Remote Linux Devices} - {remote Linux} or \l{Adding Docker Devices}{Docker} devices if you + You can build applications on \l{Developing for Remote Linux Devices} + {remote Linux} or \l{Add Docker devices}{Docker} devices if you have kits that specify the devices and toolchains to use. When the build device of the kit is a remote device, such as a remote Linux or Docker device, the \uicontrol Browse button next to the diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc index ce809fc536..db6aefeb64 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc @@ -141,6 +141,10 @@ Use the following syntax to enter environment variable names and values: \c {<VARIABLE>=<VALUE>}. + To temporarily disable a variable, add a hash character (#) to the beginning + of the line. + \note Using this approach for a different statement (append, prepend, unset) + may result in unexpected changes of the environment. To remove a variable value from the environment, enter the variable name. For example, \c TEST sets the value of the \c TEST variable empty when @@ -160,8 +164,8 @@ following lines. However, you can remove a value after you have referred to it on an earlier line. - To temporarily disable a variable, add a hash character (#) to the beginning - of the line. + To add a comment or disable any of the above actions, prefix it with two hash + characters (##). \sa {Specify the environment for projects}, {Configure projects for building}, {Configure projects for running}, {Use Qt Creator variables} diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc index 93510fa438..3f8e93f142 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc @@ -83,8 +83,9 @@ \list \li \l{Link projects to Axivion dashboards}{Axivion} \li \l{Specify clangd settings}{Clangd} - \li \l{Speficy Clang tools settings}{Clang Tools} + \li \l{Specify Clang tools settings}{Clang Tools} \li \l{Set Copilot preferences}{Copilot} + \li \l{Configure C++ code model}{C++ Code Model} \li \l{Specify code style}{C++ Code Style} \li \l{Set C++ file naming preferences}{C++ File Naming} \li \l{Specify dependencies}{Dependencies} @@ -132,7 +133,7 @@ Each kit consists of a set of values that define one environment, such as a \l{glossary-device}{device}, \l{Add compilers}{compiler}, - \l{Add debuggers}{debugger}, and \l{Add Qt versions}{Qt version}, as well + \l{Add debuggers}{Debugging}, and \l{Add Qt versions}{Qt version}, as well as steps for building, deploying, and running applications. To copy the build, deploy, and run steps from another kit, select diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc index 34233c90d8..99802a720b 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-analyze.qdoc @@ -13,8 +13,8 @@ you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Run > \uicontrol {Run Settings}. - \QC integrates \l{Analyzing Code}{Valgrind code analysis tools} for - detecting memory leaks and profiling function execution. + With \l{Valgrind's Tool Suite}, you can detect memory leaks and profile + function execution. To specify Valgrind settings for the current project: @@ -38,11 +38,12 @@ \endlist - Click \uicontrol {Restore Global} to revert to the global settings. + Select \uicontrol {Restore Global} to revert to the global settings. To specify global Valgrind settings, select \preferences > \uicontrol Analyzer. - \sa {Configuring Projects}, {Selecting Options for Memory Analysis}, - {Selecting Profiling Options}, {Using Valgrind Code Analysis Tools} + \sa {Detect memory leaks with Memcheck}, {Profile function execution}, + {Run Valgrind tools on external applications}, {Configuring Projects}, + {Valgrind Callgrind}, {Valgrind Memcheck} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc index 770478d5b6..b0609ab771 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdoc @@ -30,7 +30,7 @@ \list \li \l{Adding Custom Debugging Helpers}{Custom debugging helpers} - \li \l{Specifying GDB Settings}{GDB commands} to execute after GDB + \li \l{GDB}{GDB commands} to execute after GDB has started, but before the debugged program is started or attached, and before the debugging helpers are initialized \endlist @@ -42,5 +42,5 @@ {enable QML debugging} either globally or in the \uicontrol {Build Settings} of the project. - \sa {Configuring Projects}, {Debugging} + \sa {Configuring Projects}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc index 01458baf26..72085701e1 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdoc @@ -32,10 +32,10 @@ \section1 Run in Terminal - For console applications, check the \uicontrol{Run in terminal} check box. - To specify the terminal to use on Linux and \macos, select \preferences > + For console applications, select \uicontrol{Run in terminal}. + To specify the terminal to use on Linux and \macos, go to \preferences > \uicontrol Environment > \uicontrol System. To use an \l{Terminal} - {internal terminal}, select \preferences > \uicontrol Terminal > + {internal terminal}, go to \preferences > \uicontrol Terminal > \uicontrol {Use internal terminal}. \section1 Linker Libraries @@ -48,22 +48,21 @@ \c {make install}, and want to make sure that the deployed application will find the libraries also when it is run without \QC. - To disable library linking for the current project, deselect the - \uicontrol {Add build library search path to PATH} check box. To disable - library linking for all projects, select \preferences > - \uicontrol {Build & Run}, and then deselect the - \uicontrol {Add linker library search paths to run environment} check box. + To disable library linking for the current project, clear + \uicontrol {Add build library search path to PATH}. To disable + library linking for all projects, go to \preferences > + \uicontrol {Build & Run} and then clear + \uicontrol {Add linker library search paths to run environment}. - \section1 \macos Options + \section1 Debugging Linked Frameworks - The \uicontrol {Use debug version of frameworks (DYLD_IMAGE_SUFFIX=_debug)} option - (only available on \macos) enables you to debug (for example, step into) - linked frameworks, such as the Qt framework itself. You do not need this - option for debugging your application code. + On \macos, select \uicontrol {Use debug version of frameworks (DYLD_IMAGE_SUFFIX=_debug)} + to debug (for example, step into) linked frameworks, such as the Qt framework + itself. You do not need this option for debugging your application code. - \section1 Linux Options + \section1 Running as root User - On Linux, select the \uicontrol {Run as root user} check box to run the + On Linux and \macos, select \uicontrol {Run as root user} to run the application with root user permissions. \sa {Configure projects for running}, {Specify a custom executable to run}, diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc index 7f8ba6894b..bf816f4351 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc @@ -27,7 +27,7 @@ \list \li \l {Android Run Settings}{Android} - \li \l {Boot2Qt Run Settings}{Boot2Qt} + \li \l {\B2Q Run Settings}{\B2Q} \li \l {Desktop Device Run Settings}{Desktop} \li \l {Python Run Settings}{Python} \li \l {QNX Run Settings}{QNX} diff --git a/doc/qtcreator/src/projects/creator-projects-running.qdoc b/doc/qtcreator/src/projects/creator-projects-running.qdoc index 0b39d0d707..1dd25de23a 100644 --- a/doc/qtcreator/src/projects/creator-projects-running.qdoc +++ b/doc/qtcreator/src/projects/creator-projects-running.qdoc @@ -40,7 +40,7 @@ If you have connected \l{Mobile Platforms}{mobile devices} or \l{Embedded Platforms}{embedded devices} to the computer - or added virtual devices, such as \l{Managing Android Virtual Devices (AVD)} + or added virtual devices, such as \l{Manage AVDs} {Android Virtual Devices (AVD)}, you can select them in the kit selector. Select \uicontrol Manage to manage device settings. For example, you can add diff --git a/doc/qtcreator/src/python/creator-python-development.qdoc b/doc/qtcreator/src/python/creator-python-development.qdoc index d5cd5fe31c..8978c09d60 100644 --- a/doc/qtcreator/src/python/creator-python-development.qdoc +++ b/doc/qtcreator/src/python/creator-python-development.qdoc @@ -25,8 +25,8 @@ \li \l{Configure Python language servers} \li \l{Run Python applications} \li \l{Python Run Settings} - \li \l{PDB} - \li \l{Launching the Debugger} + \li \l{PDB versions} + \li \l{Supported Native Debuggers} \endlist For more information about developing with Qt for Python, including diff --git a/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc b/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc index 06fcb20abd..eb68e9e0f8 100644 --- a/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc @@ -9,22 +9,30 @@ // ********************************************************************** /*! - \previouspage creator-deployment-b2qt.html \page creator-deployment-qnx.html - \nextpage creator-deployment-embedded-linux.html - \title Deploying to QNX Neutrino + \previouspage creator-reference.html - You can specify settings for deploying applications to QNX Neutrino + \ingroup creator-reference-deploy-configurations + + \title QNX Neutrino Deploy Configuration + + \brief Copy application files to QNX Neutrino devices. + + Specify settings for deploying applications to QNX Neutrino devices in the project configuration file and in \uicontrol Projects > \uicontrol {Run Settings} > \uicontrol Deployment. \image qtcreator-qnx-deployment.png "Deploy to device" The deployment process is described in more detail in - \l{Deploying to Remote Linux}. + \l{Remote Linux Deploy Configuration}. \section1 Finding Configured Devices The \uicontrol {Check for a configured device} deployment step looks for a device that is ready for deployment. + + \sa {Build and Run}{How To: Build and Run}, {QNX Neutrino}{How To: Develop for QNX}, + {QNX Run Settings}, {Remote Linux Deploy Configuration}, + {Remote Linux Run Settings} */ diff --git a/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc b/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc index d7ec1e6417..f6990187c3 100644 --- a/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-developing-qnx.qdoc @@ -1,32 +1,51 @@ // Copyright (C) 2018 Blackberry -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-developing-mcu.html \page creator-developing-qnx.html - \nextpage creator-developing-generic-linux.html + \previouspage creator-how-tos.html - \title Connecting QNX Devices + \ingroup creator-how-to-qnx - You can connect QNX devices to the development PC to deploy, run and debug - applications on them from within \QC. The QNX Neutrino RTOS has additional + \title Add a QNX Neutrino device + + Create a connection between \QC and a QNX Neutrino device to run, debug, and + analyze applications on the device. The QNX Neutrino RTOS has additional command-line tools and services, as described in \l {Qt for QNX}. - \note In Qt 6, \QC support for QNX is considered experimental. + \image qtcreator-devices-qnx.webp {QNX device preferences} + \caption QNX device preferences + + \include qtcreator-add-linux-device.qdocinc {add linux device} {QNX Device} + + \sa {QNX Neutrino}{How To: Develop for QNX}, + {Remote Linux}{How To: Develop for remote Linux}, + {Manage Kits}{How To: Manage Kits} +*/ + +/*! + \page creator-how-to-create-qnx-kits.html + \previouspage creator-how-tos.html - \section1 Adding a QNX Neutrino Device in \QC + \ingroup creator-how-to-qnx - Adding a QNX Neutrino device is very similar to - \l{Connecting Remote Linux Devices}, except that - you need to select \uicontrol {QNX Device} in the - \uicontrol {Device Configuration} wizard. + \title Create kits for QNX Neutrino devices - \section1 Add kits for QNX Devices + To generate a build and run \l {Kits}{kit} for QNX Neutrino devices: - To view QNX device settings, select \preferences > - \uicontrol Devices > \uicontrol QNX. Select the \uicontrol {Generate kits} - check box to allow \QC to generate kits for QNX development. + \list 1 + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices. + \li Select \uicontrol Add > \uicontrol {QNX Device} > + \uicontrol {Start Wizard} to add a QNX Neutrino device. + \li Select \uicontrol Apply to fetch the information needed for + creating kits. + \li Go to \preferences > \uicontrol Devices > \uicontrol QNX. + \li Select \uicontrol {Create Kit} to create a kit for a particular + platform. + \image qtcreator-preferences-qnx.webp {QNX Preferences} + \li Activate the kit for your project. + \endlist - \sa {Add kits} + \sa {QNX Neutrino}{How To: Develop for QNX}, {Activate kits for a project} */ diff --git a/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc b/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc index 364ee316bc..13fc502533 100644 --- a/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-projects-how-to-run-qnx.qdoc @@ -5,20 +5,22 @@ \page creator-how-to-run-on-qnx.html \previouspage creator-how-tos.html - \ingroup creator-how-to-run + \ingroup creator-how-to-qnx \title Run on QNX devices To build an application and run it on a device: \list 1 - \li Connect the device to the computer or to the Wi-Fi network. - \li Configure the device and specify a connection to it. + \li Connect the device to the computer or to a network. + \li Go to \preferences > \uicontrol Devices > \uicontrol Devices, + and add a QNX device. + \image qtcreator-devices-qnx.webp {QNX device preferences} \li Make sure that your kit has your QNX device set. \li Select \inlineimage icons/run_small.png (\uicontrol Run). \endlist - \QC uses the compiler specified in the QNX tool chain to build the + \QC uses the compiler specified in the QNX toolchain to build the application. \note Debugging is currently only fully supported on Linux and \macos. @@ -32,7 +34,7 @@ \section2 Debug output cannot be shown - For the command-line output to show up in the \uicontrol{Application Output}, + For the command-line output to show up in \l {Application Output}, \QC has to create an SSH connection to the device. This is only possible if QNX Momentics is not running, and the SSH key configured for the device is a 4096-bit key. @@ -48,6 +50,6 @@ \c printf, \c ps, \c read, \c sed, \c sleep, \c uname, \c slog2info, and \c cat. - \sa {Connecting QNX Devices}, {Run on many platforms}, {Compilers}, - {Embedded Platforms}, {kit-preferences}{Kits} + \sa {QNX Neutrino}{How To: Develop for QNX}, {Run on many platforms}, + {Compilers}, {kit-preferences}{Kits} */ diff --git a/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc b/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc index c3fd8861c0..4e39314d8f 100644 --- a/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc +++ b/doc/qtcreator/src/qnx/creator-projects-settings-run-qnx.qdoc @@ -15,13 +15,14 @@ you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Run > \uicontrol {Run Settings}. - To run and debug an application on a QNX device, you must - create connections from the development PC to the device. Select - \uicontrol {Manage device configurations} to create a connection. + To run and debug an application on a QNX device, select + \uicontrol {Manage device configurations} to create a + connection between \QC and the device. Settings for QNX Neutrino devices are very similar to those for remote linux devices. - \sa {Remote Linux Run Settings}, {Activate kits for a project}, - {Configure projects for running}, {kits-tab}{Kits}, {Connecting QNX Devices} + \sa {QNX Neutrino}{How To: Develop for QNX}, {Manage Kits}{How To: Manage Kits}, + {Remote Linux Run Settings}, {Configure projects for running}, + {kits-tab}{Kits} */ diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 0a60027451..442ff25835 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -22,72 +22,8 @@ \endlist \li \l{Creating Projects} \li \l{Configuring Projects} - \li \l{Validating with Target Hardware} - \list - \li \l{Previewing on Desktop} - \li \l{Previewing on Devices} - \li \l{Previewing in Browsers} - \endlist - \li \l{Deploying to Devices} - \list - \li \l{Deploying to Android} - \li \l{Deploying to Boot2Qt} - \li \l{Deploying to QNX Neutrino} - \li \l{Deploying to Remote Linux} - \endlist - \li \l{Connecting Devices} - \list - \li \l{Connecting Android Devices} - \li \l{Connecting Bare Metal Devices} - \li \l{Connecting Boot2Qt Devices} - \li \l{Adding Docker Devices} - \li \l{Connecting iOS Devices} - \li \l{Connecting MCUs} - \li \l{Connecting QNX Devices} - \li \l{Connecting Remote Linux Devices} - \li \l{Building Applications for the Web} - \endlist \li \l{Debugging} - \list - \li \l{Setting Up Debugger} - \li \l{Launching the Debugger} - \li \l{Debug Mode Views} - \list - \li \l{Viewing Call Stack Trace} - \li \l{Setting Breakpoints} - \li \l{Viewing Threads} - \li \l{Viewing Modules} - \li \l{Viewing Source Files} - \li \l{Local Variables and Function Parameters} - \li \l{Evaluating Expressions} - \li \l{Viewing and Editing Register State} - \li \l{Debugger Log} - \li \l{Viewing Disassembled Code} - \endlist - \li \l{Stopping Applications} - \li \l{Examining Data} - \li \l{Remote Debugging} - \li \l{Debugger Preferences} - \li \l{Using Debugging Helpers} - \li \l{Debugging Qt Quick Projects} - \li \l{Troubleshooting Debugger} - \endlist \li \l{Analyzing Code} - \list - \li \l{Profiling QML Applications} - \li \l{Checking Code Coverage} - \li \l{Using Valgrind Code Analysis Tools} - \list - \li \l{Detecting Memory Leaks with Memcheck} - \li \l{Profiling Function Execution} - \li \l{Running Valgrind Tools on External Applications} - \endlist - \li \l{Detecting Memory Leaks with Heob} - \li \l{Analyzing CPU Usage} - \li \l{Analyzing Code with Cppcheck} - \li \l{Visualizing Chrome Trace Events} - \endlist - \li \l{Using Squish} \endlist \li \l{Tutorials} \generatelist creator-tutorials @@ -109,6 +45,27 @@ \generatelist creator-how-to-debug \li Design UIs \generatelist creator-how-to-design + \li Develop for Devices + \list + \li Android + \generatelist creator-how-to-android + \li Bare Metal + \generatelist creator-how-to-bare-metal + \li \B2Q + \generatelist creator-how-to-b2qt + \li Docker + \generatelist creator-how-to-docker + \li iOS + \generatelist creator-how-to-ios + \li MCUs + \generatelist creator-how-to-mcu + \li QNX Neutrino + \generatelist creator-how-to-qnx + \li Remote Linux + \generatelist creator-how-to-remote-linux + \li WebAssembly + \generatelist creator-how-to-webassembly + \endlist \li Edit Code \generatelist creator-how-to-edit \list @@ -143,14 +100,28 @@ \li \l{Reference} \generatelist creator-reference \list + \li Analyzers + \generatelist creator-reference-analyzer \li Build Systems \generatelist creator-reference-build-systems \list \li Build Configurations \generatelist creator-reference-build-configurations + \endlist + \li Devices + \generatelist creator-reference-devices + \list + \li Deploy Configurations + \generatelist creator-reference-deploy-configurations \li Run Configurations \generatelist creator-reference-run-configurations \endlist + \li Debugger + \generatelist creator-reference-debugger + \list + \li Debugger Views + \generatelist creator-reference-debugger-views + \endlist \li Editors \generatelist creator-reference-editors \li Platforms diff --git a/doc/qtcreator/src/qtcreator.qdoc b/doc/qtcreator/src/qtcreator.qdoc index cc3352dd10..96bafe421d 100644 --- a/doc/qtcreator/src/qtcreator.qdoc +++ b/doc/qtcreator/src/qtcreator.qdoc @@ -21,7 +21,7 @@ operating systems. For more information, see \l{Supported Platforms}. In addition, you can use the experimental - \l{Building Applications for the Web}{WebAssembly plugin} + \l{Build applications for the web}{WebAssembly plugin} to build applications in web format and run them in web browsers. @@ -39,12 +39,8 @@ \li \l{Getting Started} \li \l{Creating Projects} \li \l{Configuring Projects} - \li \l{Validating with Target Hardware} - \li \l{Connecting Devices} - \li \l{Deploying to Devices} \li \l{Debugging} \li \l{Analyzing Code} - \li \l{Using Squish} \endlist \li \b {\l{Tutorials}} \generatelist creator-tutorials @@ -54,6 +50,7 @@ \li \l{Build and Run} \li \l{Debug} \li \l{Design UIs} + \li \l{Develop for Devices} \li \l{Edit Code} \li \l{Manage Projects} \li \l{Read Documentation} @@ -65,6 +62,7 @@ \list \li \l {Acknowledgements} \li \l {Build Systems} + \li \l {Devices} \li \l {Command-Line Options} \li \l {Custom Wizards} \li \l {Keyboard Shortcuts} diff --git a/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc b/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc index f06917784b..b6f01f38a5 100644 --- a/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc +++ b/doc/qtcreator/src/qtquick/creator-only/creator-mobile-app-tutorial.qdoc @@ -32,12 +32,12 @@ To develop for Android devices, you must install \l{Qt for Android} and set up the development environment, as instructed in - \l{Connecting Android Devices}. + \l{Developing for Android}. To develop for iOS devices, you must install Xcode and use it to configure a device. For this, you need an Apple developer account and iOS Developer Program certificate that you receive from Apple. For more information, see - \l{Connecting iOS Devices}. + \l{Developing for iOS}. \include qtquick-tutorial-create-empty-project.qdocinc qtquick empty application diff --git a/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc b/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc index 8ff40ec941..58e3e900ba 100644 --- a/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc +++ b/doc/qtcreator/src/qtquick/creator-only/qt-design-viewer.qdoc @@ -1,27 +1,25 @@ -// Copyright (C) 2019 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qt-design-viewer.html - \previouspage creator-live-preview-devices.html - \nextpage creator-building-targets.html + \previouspage creator-how-tos.html - \title Previewing in Browsers + \ingroup creator-how-to-design + + \title Preview UI prototypes in browsers \image qt-design-viewer.png - \QDV is a QML viewer that runs in your web browser. This means that you can - run applications in most widely-used web browsers, such as Apple Safari, - Google Chrome, Microsoft Edge, and Mozilla Firefox, on the desktop and on - mobile devices. + Run Qt Quick UI Prototype projects in web browsers, such as Apple Safari, + Google Chrome, Microsoft Edge, and Mozilla Firefox, with \QDV. The startup and compilation time depend on your browser and configuration. - However, the actual performance of the application once started is - indistinguishable from the same application running on the desktop. + Once started, the application performs the same as when running on the + desktop. - You can run Qt Quick UI Prototype projects, which - have a .qmlproject file that defines the main QML file and the import paths. - Compress the project folder into a ZIP file that you upload to \QDV. + The .qmlproject configuration file defines the main QML file and the import + paths. Compress the project folder into a ZIP file that you upload to \QDV. The loaded applications remain locally in your browser. No data is uploaded into the cloud. @@ -30,11 +28,12 @@ \list 1 \li In the browser, open \l{ https://designviewer.qt.io/}{\QDV}. - \li Drag and drop your application package to \QDV, or click the load + \li Drag your application package to \QDV, or select the load icon to browse for your file. \endlist Your application is compiled and run on \QDV. - \sa {Create Qt Quick UI Prototypes} + \sa {Create Qt Quick UI Prototypes}, {Design UIs}{How To: Design UIs}, + {UI Design} */ diff --git a/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc b/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc index 0ff290f0d0..0fbb4fdea0 100644 --- a/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc +++ b/doc/qtcreator/src/qtquick/creator-only/qtquick-creating.qdoc @@ -149,8 +149,7 @@ imports that are used in the QML files. You can add imports later to combine Qt Quick basic types with - Qt Quick Controls, Qt Quick Dialogs, and Qt Quick Layouts (available - since Qt 5.1). + Qt Quick Controls, Qt Quick Dialogs, and Qt Quick Layouts. \li Select the \uicontrol {Use Qt Virtual Keyboard} check box to add support for \l{Qt Virtual Keyboard} to the application. diff --git a/doc/qtcreator/src/qtquick/creator-only/qtquick-live-preview-desktop.qdoc b/doc/qtcreator/src/qtquick/creator-only/qtquick-live-preview-desktop.qdoc new file mode 100644 index 0000000000..75a64831c0 --- /dev/null +++ b/doc/qtcreator/src/qtquick/creator-only/qtquick-live-preview-desktop.qdoc @@ -0,0 +1,22 @@ +// Copyright (C) 2024 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page creator-live-preview-desktop.html + \previouspage creator-how-tos.html + + \ingroup creator-how-to-design + + \title Preview a QML file on desktop + + To preview the currently active QML file on the desktop: + + \list + \li Select \inlineimage icons/live-preview.png (\uicontrol {Live Preview}) + on the \l{Edit Mode}{editor} toolbar. + \image qtcreator-live-preview.webp {Application running on top of the editor view} + \li Go to \uicontrol Build > \uicontrol {QML Preview}. + \endlist + + \sa {Design UIs}{How To: Design UIs}, {UI Design} +*/ diff --git a/doc/qtcreator/src/qtquick/creator-only/qtquick-states-scxml.qdocinc b/doc/qtcreator/src/qtquick/creator-only/qtquick-states-scxml.qdocinc deleted file mode 100644 index 1f0fd5a8e0..0000000000 --- a/doc/qtcreator/src/qtquick/creator-only/qtquick-states-scxml.qdocinc +++ /dev/null @@ -1,26 +0,0 @@ -// Copyright (C) 2020 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! -//! [scxml state machines] - - \section1 Using SCXML State Machines - - To use QML together with an SCXML state machine, add states and - bind them to the state machine in \l {Connection View} > - \uicontrol Backends, as described in \l {Managing C++ Backend Objects}. - - In the \uicontrol States view, you can select \uicontrol Actions > - \uicontrol {Set when Condition} to edit the \c when condition of states - to map QML states to the states of the SCXML state machine. For an example, - see \l {Qt SCXML Traffic Light QML Example (Dynamic)}. - - \image qmldesigner-states-when-condition.png - - If you add animation to the states, you can - \l{Validating with Target Hardware}{preview} - or \l{Run on many platforms}{run} - the application to test the animation. - -//! [scxml state machines] -*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc deleted file mode 100644 index 2f939c69cb..0000000000 --- a/doc/qtcreator/src/qtquick/qtquick-live-preview-desktop.qdoc +++ /dev/null @@ -1,51 +0,0 @@ -// Copyright (C) 2024 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \previouspage creator-live-preview.html - \page creator-live-preview-desktop.html - \nextpage creator-live-preview-devices.html - - \title Previewing on Desktop - - To preview the currently active QML file on the desktop: - - \list - \if defined(qtcreator) - \li Select \inlineimage icons/live-preview.png (\uicontrol {Live Preview}) - on the \l{Edit Mode}{editor} toolbar. - \image qtcreator-live-preview.webp {Application running on top of the editor view} - \li Select \uicontrol Build > \uicontrol {QML Preview}. - \endlist - \else - \li Select the \uicontrol {Live Preview} button on the top toolbar. - \li Press \key {Alt+P}. - \image studio-live-preview.webp - \endlist - - To preview any QML file in the project: - - \list - \li Select the \uicontrol {Live Preview} button on the top toolbar. - \li Right-click the filename in the \l Projects view, and select - \uicontrol {Preview File}. - \endlist - - To preview the whole UI, select \uicontrol {Live Preview} - when viewing the main QML file of the project. - - \section1 Overriding the Preview Tool - - By default, the QML runtime is used for previewing. - - To use some other tool: - - \list 1 - \li Select \inlineimage icons/settings.png to go to - \uicontrol {Run Settings}. - \image studio-run-settings.webp {Run Settings} - \li In \uicontrol {Override device QML viewer}, select the folder where - the preview tool executable is located. - \endlist - \endif -*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc index 584db4bb43..87142f4a51 100644 --- a/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-live-preview-devices.qdoc @@ -1,36 +1,46 @@ -// Copyright (C) 2020 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-live-preview-desktop.html \page creator-live-preview-devices.html + \if defined (qtdesignstudio) + \previouspage studio-live-preview-desktop.html \nextpage qt-design-viewer.html \title Previewing on Devices - To preview UIs on Android devices, you need to enable USB debugging on them - and connect them to your system with a USB cable. + \else + \previouspage creator-how-tos.html + + \ingroup creator-how-to-design + + \title Preview Qt Quick UIs on devices + \endif - To preview UIs on Boot2Qt devices, you need to connect the devices to your - system with a USB cable, or a wired or wireless connection, depending on - the device, and configure connections to them. The necessary kits have been - predefined and you only need to enable them for your current project. + To preview a UI on an Android device, turn on USB debugging on the device + and connect it to the computer with a USB cable. + + To preview a UI on a \B2Q device, connect the device to the computer + with a USB cable, or a wired or wireless connection, depending on + the device, and configure a connection to it. The necessary kits have been + predefined, but you need to select the one appropriate for your current + project. \e {Deploy configurations} handle the packaging and copying of the necessary files to a location in a device where you want to run the executable at. - \note To preview on a wirelessly connected device, select \preferences > \uicontrol Devices - and connect the device. + \note To preview on a wirelessly connected device, go to \preferences > + \uicontrol Devices and connect the device. To preview a UI on a device: \list 1 \if defined(qtcreator) - \li In \uicontrol Projects > \uicontrol {Build & Run}, enable the kit - predefined for the device type (1). + \li Go to \uicontrol Projects > \uicontrol {Build & Run}. + \li Activate the kit predefined for the device type (1). \li Select the kit for the device in the kit selector (2). - \image qtcreator-live-preview-kit.png + \image qtcreator-kit-selector-devices.webp {Kit selector} \else \li In the bottom toolbar, select \inlineimage icons/settings.png and enable the kit predefined for the device type. @@ -42,45 +52,36 @@ press \key {Alt+P}. \endlist - \section2 Previewing on Android Devices + \section2 On Android \if defined(qtcreator) - The USB debugging feature on Android devices enables creating connections - to the devices from \QDS and running the preview utility on them. + Use the USB debugging feature on an Android device to create a connection + to the device from \QC and run the preview utility on it. - Debugging is enabled in different ways on different Android devices. + Debugging is turned on in different ways on different Android devices. Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}. - On some devices \uicontrol {Developer Options} is hidden and becomes visible - when you tap the \uicontrol {Build number} field in \uicontrol Settings > - \uicontrol About several times. + Tap \uicontrol {Build number} in \uicontrol Settings > \uicontrol About + several times to show \uicontrol {Developer Options}. - After you have enabled debugging, connect the Android device to the system + After you turn on debugging, connect the Android device to the system with a USB cable. - The first time you preview a UI on devices, the preview utility - is copied to them. This might take some time. Thereafter, previewing will - get faster because only the UI files need to be copied to the - device. + The first time you preview a UI on a device, the preview utility + is copied to it, which might take some time. Thereafter, previewing + gets faster because only the UI files need to be copied to the device. \else - Preview your \QDS projects with \QUV. It is an application - that runs on your Android device. + Preview \QDS projects with \QUV on an Android device. Learn more about \l{Viewing Applications on Android}. \endif + \section2 On \B2Q - \section2 Previewing on Boot2Qt Devices - - You can preview UIs on Boot2Qt devices. For a list of supported devices, see - \l{https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html} - {Boot2Qt: Supported Target Devices and Development Hosts}. + Preview a UI on a supported \B2Q device that you configure as + instructed in the \B2Q documentation. - You must configure the device as instructed in the - \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} - {Boot2Qt: Installation Guides}. + \sa {\B2Q: Documentation}, {Support Levels for Target Hardware} - \note At the time of this writing, \macos is not supported as a development - host for Boot2Qt. This means that you cannot preview UIs on - devices if you are using \QC on \macos. For more information, see - \l {https://doc.qt.io/Boot2Qt/qtdc-supported-platforms.html#supported-development-hosts} - {Boot2Qt: Supported Development Hosts}. + \if defined(qtcreator) + \sa {Design UIs}{How To: Design UIs}, {UI Design} + \endif */ diff --git a/doc/qtcreator/src/qtquick/qtquick-live-preview.qdoc b/doc/qtcreator/src/qtquick/qtquick-live-preview.qdoc deleted file mode 100644 index 2d2ac0b36b..0000000000 --- a/doc/qtcreator/src/qtquick/qtquick-live-preview.qdoc +++ /dev/null @@ -1,67 +0,0 @@ -// Copyright (C) 2024 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only - -/*! - \page creator-live-preview.html - \if defined(qtdesignstudio) - \previouspage quick-states.html - \else - \previouspage creator-building-running.html - \endif - \nextpage creator-live-preview-desktop.html - - \title Validating with Target Hardware - - Preview a UI file or the entire UI on the desktop, as well as on embedded - Linux devices to instantly view the changes you make to the UI. On Android - devices, the preview shows the snapshot of your project from the moment - you start the preview on the device, not your changes. - - \if defined(qtcreator) - \image qtcreator-live-preview.webp {Application running on top of the editor} - \else - \image studio-live-preview.webp - \endif - - Or, use \QDV to run - \if defined(qtcreator) - \l{Create Qt Quick UI Prototypes}{Qt Quick UI projects} - \else - applications - \endif - in most widely-used web browsers on the desktop and in mobile devices and - share your designs with reviewers who don't have \QC. - - \list - \li \l{Previewing on Desktop} - - Preview individual QML files or the whole UI. - \li \l{Previewing on Devices} - - \if defined(qtcreator) - Preview Qt Quick applications on devices that you - connect to the development PC. For more information, see - \l {Connecting Devices}. - \else - When you install \QDS, everything you need for previewing on - devices is set up automatically. You only need to connect your - devices to your system. - \endif - - \if defined(qtdesignstudio) - \li \l{Sharing Applications Online} - - Share applications online and view them in a web browser. - - \li \l{Viewing Applications on Android} - - Preview your \QDS projects with \QUV. It is an application - that runs on your Android device. - \else - \li \l{Previewing in Browsers} - - Open \l{https://designviewer.qt.io/}{\QDV} - in a browser and load applications to it. - \endif - \endlist -*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc b/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc index 299bd05772..e1f7e3bce5 100644 --- a/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-modules-with-plugins.qdoc @@ -36,22 +36,25 @@ \list 1 \li Create custom components and place all the \c .qml files in a - directory dedicated to your module. For example: + directory dedicated to your module. For example, \c {imports\asset_imports}. - \li For Qt Quick UI Prototype projects (.qmlproject), specify the path to + \if defined(qtcreator) + \li For Qt Quick UI Prototype projects (.qmlproject), specify the path to the directory that has the module in the .qmlproject file of the application where you want to use the module - as a value of the \c importPaths variable. For example + as a value of the \c importPaths variable. For example, \c{importPaths: [ "imports", "asset_imports" ]}. - + \else + \li Specify the path to the directory that has the module in the + .qmlproject file of the application where you want to use the module + as a value of the \c importPaths variable. For example, + \c{importPaths: [ "imports", "asset_imports" ]}. + \endif \li Create a \c qmldir file for your module and place it in the module directory. For more information, see \l {Module Definition qmldir Files}. - \li Create a \c qmltypes file, as instructed in - \l {Generating Type Description Files}. - \li Create a directory named \c designer in your module directory. \li Create a \c .metainfo file for your module and place it in the @@ -66,18 +69,29 @@ \if defined(qtcreator) \li Import the module into the project, as instructed in \l {Importing QML Modules}. - \endlist \else \li Build your module using the same Qt version and compiler as \QDS. - For more information, see \l {Running QML Modules in Design Mode}. + + Your module and components should now appear in \uicontrol Components. + \endif + \endlist - Your module should now appear in \uicontrol Components. Your components - should appear in a subsection of \uicontrol Components if a valid - \c .metainfo file is in place. + \note If \QC cannot find the new QML module, build the project + and then go to \uicontrol {Tools} > \uicontrol {QML/JS} > + \uicontrol {Reset Code Model} to reset the code model. + \if defined(qtdesignstudio) + For more information about how to show the \uicontrol {Tools} menu, see + \l{Customizing the Menu Bar}. \endif - \section1 Generating Type Description Files + \if defined(qtcreator) + \section1 Developing with Qt 6.1 or Earlier + + Since Qt 6.2, CMake generates the \c qmltypes and \c qmldir files + automatically. + + \section2 Generating Type Description Files When \l{Defining QML Types from C++}{registering QML types}, make sure that the QML module has a \c{plugins.qmltypes} file. Ideally, it should be located @@ -110,6 +124,7 @@ \endcode The import path affects all the targets built by the CMake project. + \endif \if defined(qtdesignstudio) \section1 Running QML Modules in Design Mode @@ -128,4 +143,6 @@ environment variable to check whether the plugin is currently being run by an application or edited in the \uicontrol Design mode. \endif + + \sa {Resetting the Code Model} */ diff --git a/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc b/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc index 0fd232d8b9..b22bd5be5e 100644 --- a/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-profiler.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -8,185 +8,220 @@ // ********************************************************************** /*! - \page creator-qml-performance-monitor.html + \page creator-how-to-profile-qml.html \if defined(qtdesignstudio) - \previouspage creator-qml-debugging-example.html + \previouspage creator-qml-performance-monitor.html \nextpage studio-advanced.html \else - \previouspage creator-analyze-mode.html - \nextpage creator-coco.html - \endif - - \title Profiling QML Applications - - You can use the QML Profiler to find causes for typical performance problems - in your applications, such as slowness and unresponsive, stuttering user - interfaces. Typical causes include 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 for similar performance problems is creating, - painting, or updating invisible items, which takes time in the GUI thread. - - \if defined(qtcreator) - Triggering long-running C++ functions, such as paint methods and signal - handlers, also takes time in the GUI thread, but is more difficult to see in - the QML Profiler because it does not profile C++ code. + \previouspage creator-how-tos.html \endif - To find excessive use of JavaScript, check the frame rate in animations and - Scene Graph events, look for gaps, and check whether the application behaves - as expected. The JavaScript category displays the run time of functions, - which you should try to keep below 16 ms per frame. + \ingroup creator-how-to-analyze - To find problems caused by handling invisible items, look for dropped - frames and check that you are not using too many short bindings or signal - handlers that are updated per frame. You can also \l{Visualizing Overdraw} - {visualize Scene Graph overdraw} to check scene layout and find items that - are never visible to the users because they are located outside the screen - or hidden beneath other, visible elements. + \title Profile QML applications - \if defined(qtcreator) - If frames get dropped even though JavaScript is not being run, and there are - large, unexplained gaps in the timeline, check your custom QQuickItem - implementations. You can use \l{Using Valgrind Code Analysis Tools} - {Valgrind} or other general purpose profilers to analyze C++ code. - - You can use \e {full stack tracing} to trace from the top level QML or - JavaScript down to the C++ and all the way to the kernel space. You can - view the collected data in the \l{Visualizing Chrome Trace Events} - {Chrome Trace Format Viewer}. - \endif + With QML Profiler, you can find causes for typical performance problems + in your applications, such as slowness and unresponsive, stuttering user + interfaces. \if defined(qtdesignstudio) \note In this section, you are using advanced menu items. These are not visible by default. To toggle the visibility of advanced menu items, see - \l{Customizing the Menu}. + \l{Customizing the Menu Bar}. \endif - \section1 Using QML Profiler - To monitor the performance of an application in the QML Profiler: + To collect data about a QML application: \list 1 - - \li To be able to profile an application, you must set up QML debugging - for the project. For more information, see + \li Set up QML debugging for the project. For more information, see \l{Setting Up QML Debugging}. - \if defined(qtcreator) \li In the \uicontrol Projects mode, select a \l{glossary-buildandrun-kit} {kit} with Qt version 4.7.4 or later. \endif - \note To profile applications on \l{glossary-device}{devices}, you must install Qt libraries on them. - - \li Select \uicontrol Analyze > \uicontrol {QML Profiler} to profile the + \li Go to \uicontrol Analyze > \uicontrol {QML Profiler} to profile the current application. - - \li Select the - \inlineimage icons/qtcreator-analyze-start-button.png - (\uicontrol Start) button to start the application from the - QML Profiler. - - \note If data collection does not start automatically, select the - \inlineimage icons/recordfill.png - (\uicontrol {Enable Profiling}) button. - + \image qtcreator-qml-profiler-toolbar.webp {QML Profiler} + \li Select \inlineimage icons/qtcreator-analyze-start-button.png + (\uicontrol Start) to start the application from QML Profiler. \endlist - When you start analyzing an application, the application is launched, and - the QML Profiler immediately begins to collect data. This is indicated by + QML Profiler immediately begins to collect data, as indicated by the time running in the \uicontrol Elapsed field. - Data is collected until you select the \uicontrol {Enable Profiling} button. Data - collection - takes time, and therefore, there might be a delay - before the data is displayed. + \note If data collection does not start automatically, select + \inlineimage icons/recordfill.png (\uicontrol {Enable Profiling}). + + Data is collected until you select \inlineimage icons/recordfill.png again. + Data collection takes time, so expect a delay before seeing data. Do not use application commands to exit the application because data is - sent to the QML Profiler when you select the \uicontrol {Enable Profiling} button. - The application continues to run for some seconds, after which it is stopped - automatically. If you exit the application, the data is not sent. + sent to QML Profiler when you select \inlineimage icons/recordfill.png. + The application stops in seconds. If you exit the application, the data is + not sent. - Select the \uicontrol {Disable Profiling} button to disable the automatic - start of the data collection when an - application is launched. Data collection starts when you select the button - again. + Select \uicontrol {Disable Profiling} to disable the automatic start of the + data collection when an application is launched. Data collection starts when + you select the button again. To save all the collected data, select \uicontrol Analyze > \uicontrol {QML Profiler Options} > \uicontrol {Save QML Trace}. To view the saved data, select \uicontrol {Load QML Trace}. You can also deliver the saved data to others for examination or load data saved by them. - \section1 Specifying Flushing Settings + \section1 Flush data while profiling - You can specify flushing settings for the QML Profiler either globally for - all projects or separately for each project. To specify global settings, - select \preferences > \uicontrol Analyzer. + Set data flushing preferences either globally for all projects or separately + for each project. - To specify custom QML Profiler settings for a particular project, select - \uicontrol Projects > \uicontrol Run and then select \uicontrol Custom in - \uicontrol {QML Profiler Settings}. To restore the global settings for the - project, select \uicontrol {Restore Global}. + To set global preferences, go to \preferences > + \uicontrol Analyzer > \uicontrol {QML Profiler}. - \image qml-profiler-settings.png "QML Profiler Settings" + To specify custom QML Profiler settings for a particular project: - Select the \uicontrol {Flush data while profiling} check box to flush the - data periodically instead of flushing all data when profiling stops. This - saves memory on the target device and shortens the wait between the - profiling being stopped and the data being displayed. + \list 1 + \li Go to \uicontrol Projects > \uicontrol Run. + \li In \uicontrol {QML Profiler Settings}, select \uicontrol Custom. + \image qml-profiler-settings.png {QML Profiler Settings} + \endlist - In the \uicontrol {Flush interval} field, set the flush interval in - milliseconds. The shorter the interval, the more often the data is flushed. - The longer the interval, the more data has to be buffered in the target - application, potentially wasting memory. However, the flushing itself takes - time, which can distort the profiling results. + You can set the following preferences: - If you have multiple QML engines and you want to aggregate the data produced - by all of them into one trace, select the \uicontrol {Process data only when - process ends} check box. Otherwise, the profiling stops when one of the - engines stops. + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Flush data while profiling} + \li Flush the data periodically instead of flushing all data when + profiling stops. This saves memory on the target device and shortens + the wait between the profiling being stopped and the data + being displayed. + \row + \li \uicontrol {Flush interval} + \li Set the flush interval in + milliseconds. The shorter the interval, the more often the + data is flushed. The longer the interval, the more data has + to be buffered in the target application, potentially wasting + memory. However, the flushing itself takes time, which can + distort the profiling results. + \row + \li \uicontrol {Process data only when process ends} + \li Aggregate data from many QML engines into one trace. Otherwise, + the profiling stops when one of the engines stops. + \endtable + + To restore the global settings for the project, select + \uicontrol {Restore Global}. - \section1 Attaching to Running Qt Quick Applications + \section1 Attach to a running Qt Quick application - You can profile Qt Quick applications that are not launched by \QC. + You can profile a Qt Quick application that you do not run from \QC. However, you must enable QML debugging and profiling for the application in the project build settings. For more information, see \l{Setting Up QML Debugging}. - To attach to waiting applications: + To attach to a waiting application: \list 1 - \li Select \uicontrol Analyze > + \li Go to \uicontrol Analyze > \uicontrol {QML Profiler (Attach to Waiting Application)}. - \image qml-profiler-start-dialog.png "Start QML Profiler dialog" + \image qml-profiler-start-dialog.png {Start QML Profiler dialog} \li In \uicontrol Kit, select the kit used to build the application. \li In \uicontrol Port, specify the port to listen to. \li Select \uicontrol OK. \endlist + \sa {Profiling QML applications} + + \if defined(qtcreator) + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} + \endif +*/ + +/*! + \page creator-qml-performance-monitor.html + \if defined(qtdesignstudio) + \previouspage creator-qml-debugging-example.html + \nextpage creator-how-to-profile-qml.html + \else + \previouspage creator-reference.html + \endif + + \ingroup creator-reference-analyzer + + \title Profiling QML Applications + + \brief Improve the performance of QML applications. + + \if defined(qtdesignstudio) + \note In this section, you are using advanced menu items. These are not + visible by default. To toggle the visibility of advanced menu items, see + \l{Customizing the Menu}. + \endif + + With QML Profiler, you can find causes for typical performance problems + in your applications, such as slowness and unresponsive, stuttering user + interfaces. Typical causes include 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 for similar performance problems is creating or + updating invisible items, which takes time in the GUI thread. + + \if defined(qtcreator) + Triggering long-running C++ functions, such as paint methods and signal + handlers, also takes time in the GUI thread, but is more difficult to see in + QML Profiler because it does not profile C++ code. + \endif + + To find excessive use of JavaScript, check the frame rate in animations and + Scene Graph events, look for gaps, and check whether the application behaves + as expected. The JavaScript category displays the run time of functions, + which you should try to keep below 16 ms per frame. + + To find problems caused by handling invisible items, look for dropped + frames and check that you are not using too many short bindings or signal + handlers that are updated per frame. You can also \l{Visualizing Overdraw} + {visualize Scene Graph overdraw} to check scene layout and find items that + are never visible to the users because they are located outside the screen + or hidden beneath other, visible elements. + + \if defined(qtcreator) + If frames get dropped even though JavaScript is not being run, and there are + large, unexplained gaps in the timeline, check your custom QQuickItem + implementations. You can use \l{Profile function execution} + {Valgrind Callgrind} or other general purpose profilers to analyze C++ code. + + You can use \e {full stack tracing} to trace from the top level QML or + JavaScript down to the C++ and all the way to the kernel space. You can + view the collected data in the \l{Chrome Trace Format Visualizer} + {Chrome Trace Format Viewer}. + \endif + \section1 Analyzing Collected Data The \uicontrol Timeline view displays graphical representations of QML and JavaScript execution and a condensed view of all recorded events. - \image qtcreator-qml-performance-monitor.png "QML Profiler" + \image qtcreator-qml-profiler.webp {QML Profiler} Each row in the timeline (6) describes a type of QML events that were recorded. Move the cursor on an event on a row to see how long it takes and where in the source it is being called. To display the information only when - an event is selected, disable the \uicontrol {View Event Information on Mouseover} - button (4). + an event is selected, turn off \uicontrol {View Event Information on Mouseover} + (4). The outline (10) summarizes the period for which data was collected. Drag the zoom range (8) or click the outline to move on the outline. You can - also move between events by selecting the \uicontrol {Jump to Previous Event} - and \uicontrol {Jump to Next Event} buttons (1). + also move between events by selecting \uicontrol {Jump to Previous Event} + and \uicontrol {Jump to Next Event} (1). - Select the \uicontrol {Show Zoom Slider} button (2) to open a slider that you can - use to set the zoom level. You can also drag the zoom handles (9). To reset + Select \uicontrol {Show Zoom Slider} (2) to open a slider that sets the zoom + level. You can also drag the zoom handles (9). To reset the default zoom level, right-click the timeline to open the context menu, and select \uicontrol {Reset Zoom}. @@ -194,16 +229,16 @@ \section2 Selecting Event Ranges - You can select an event range (7) to view the frame rate of events and to - compare it with the frame rate of similar events. Select the - \uicontrol {Select Range} button (3) to activate the selection tool. Then click in + Select an event range (7) to view the frame rate of events and to + compare it with the frame rate of similar events. Select + \uicontrol {Select Range} (3) to activate the selection tool. Then click in the timeline to specify the beginning of the event range. Drag the selection handle to define the end of the range. The length of the range indicates the frame rate of the event. - You can use event ranges also to measure delays between two subsequent - events. Place a range between the end of the first event and the beginning - of the second event. The \uicontrol Duration field displays the delay between the + To measure delays between two subsequent events, place an event range between + the end of the first event and the beginning of the second event. The + \uicontrol Duration field displays the delay between the events in milliseconds. To zoom into an event range, double-click it. @@ -222,37 +257,28 @@ they include location in source code, duration and some relevant parts of the source code itself. - You can click on an event to move the cursor in the code editor to the part + Select an event to move the cursor in the code editor to the part of the code the event is associated with. The following types of events are displayed in the timeline view on one or - several rows. The availability of event types depends on the version of Qt - the application was compiled with and the version of Qt Quick it is using. + several rows. \table \header \li Event Category \li Description - \li Minimum Qt Version - \li Qt Quick Version - \row \li \uicontrol {Pixmap Cache} \li Displays the general amount of pixmap data cached, in pixels. In addition, displays a separate event for each picture being loaded, with specifics about its file name and size. - \li Qt 5.1 - \li Qt Quick 2 \row \li \uicontrol {Scene Graph} \li Displays the time when scene graph frames are rendered and some additional timing information for the various stages executed to do so. - \li Qt 5.1 - \li Qt Quick 2 - \row \li \uicontrol {Memory Usage} \li Displays block allocations of the JavaScript memory manager. @@ -265,98 +291,64 @@ The second row displays the actual usage of the allocated memory. This is the amount of JavaScript heap the application has actually requested. - \li Qt 5.4 - \li Qt Quick 2 - \row \li \uicontrol {Input Events} \li Displays mouse and keyboard events. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol Painting - \li Displays the time spent painting the scene for each frame. - \li Qt 4.7.4 - \li Qt Quick 1 - + \li Not used. \row \li \uicontrol Animations \li Displays the amount of animations that are active and the frame rate that they are running at. - Information about render thread animations is displayed for - applications that are built with Qt 5.3 or later. Render thread - animations are shown in a separate row then. - \li Qt 5.0 (Qt 5.3) - \li Qt Quick 2 - + Render thread animations are shown on a separate row. \row \li \uicontrol Compiling \li Displays the time spent compiling the QML files. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol Creating - \li Displays the time spent creating the elements in the scene. In Qt - Quick 2, creation of elements takes place in two stages. The first + \li Displays the time spent creating the elements in the scene. + The creation of elements takes place in two stages. The first stage is for the creation of the data structures, including child elements. The second stage represents the completion callbacks. Not all elements trigger completion callbacks, though. The stages are shown as separate events in the timeline. - For Qt Quick 2 applications compiled with versions of Qt before - 5.2.1 only the creation of top-level elements is shown, as single - events. - \li Qt 4.7.4 (Qt 5.2.1) - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol Binding \li Displays the time when a binding is evaluated and how long the evaluation takes. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol {Handling Signal} \li Displays the time when a signal is handled and how long the handling takes. - \li Qt 4.7.4 - \li Qt Quick 1 or Qt Quick 2 - \row \li \uicontrol JavaScript \li Displays the time spent executing the actual JavaScript behind bindings and signal handlers. It lists all the JavaScript functions you may be using to evaluate bindings or handle signals. - \li Qt 5.3 - \li Qt Quick 2 - \row \li \uicontrol Quick3D \li Displays the time spent rendering Qt Quick 3D frames, timing information for frame preparation and synchronization, particle system update times and particle update count, as well as texture and mesh memory allocations and memory consumption. - \li Qt 6.3 - \li Qt Quick 3D + This event type is available since Qt 6.3. \endtable \section2 Analyzing Scene Graph Events - In order to understand the scene graph category, it's important to - understand how the Qt Quick scene graph works. See - \l {Qt Quick Scene Graph} and \l {Qt Quick Scene Graph Default Renderer} - for a detailed description. The following events are reported in the + To understand the scene graph category, read more about how + Qt Quick scene graph works in \l {Qt Quick Scene Graph} and + \l {Qt Quick Scene Graph Default Renderer}. The following events are reported in the \uicontrol {Scene Graph} category. Not all events are generated by all render loops. In the Windows and Basic render loops everything runs in the same thread and the distinction between GUI thread and render thread is meaningless. - If you set the environment variable QSG_RENDER_TIMING, you get a textual + Set the environment variable QSG_RENDER_TIMING, to get a textual output of similar, but slightly different timings from the application - being profiled. For easier orientation, the differences are listed below. + being profiled. The differences are listed below. \table \header @@ -365,7 +357,6 @@ \li Render Loop Types \li Label in output of QSG_RENDER_TIMING \li Description - \li Caveats \row \li \uicontrol {Polish} \li GUI @@ -373,8 +364,6 @@ \li polish \li Final touch-up of items before they are rendered using QQuickItem::updatePolish(). - \li Versions of Qt prior to Qt 5.4 record no polish times for the basic - render loop and incorrect ones for the windows render loop. \row \li \uicontrol {GUI Thread Wait} \li GUI @@ -385,14 +374,12 @@ the same mutex at \uicontrol {GUI Thread Sync}. If this starts long before \uicontrol {Render Thread Sync}, there is \e free time in the GUI thread you could be using for running additional QML or JavaScript. - \li None \row \li \uicontrol {GUI Thread Sync} \li GUI \li Threaded \li blockedForSync \li The time the GUI thread is blocked, waiting for the render thread. - \li None \row \li \uicontrol {Animations} \li GUI @@ -403,7 +390,6 @@ animation events will be shown when using the basic render loop. Watch the \uicontrol {Animations} category to see animation timing in this case. - \li None \row \li \uicontrol {Render Thread Sync} \li Render @@ -411,7 +397,6 @@ \li Frame rendered ... sync \li Synchronizing the QML state into the scene graph using QQuickItem::updatePaintNode(). - \li None \row \li \uicontrol {Render} \li Render @@ -421,20 +406,12 @@ uploading all the necessary data to the GPU. This is the \e gross render time. Do not confuse it with the \e net \uicontrol{Render Render} time below. - \li With versions of Qt prior to Qt 5.5, the gross render time and the - below breakup of render times may be misaligned by some - microseconds due to different, unsynchronized timers being used to - measure them. For example \uicontrol {Render Preprocess} might seem to - start before \uicontrol {Render Thread Sync} is finished. \row \li \uicontrol {Swap} \li Render \li Threaded, Basic, Windows \li Frame rendered ... swap \li Swapping frames after rendering. - \li The output of swap times triggered by setting QSG_RENDER_TIMING is - incorrect for the basic render loop and versions of Qt prior to - Qt 5.4. The QML profiler shows the correct swap times. \row \li \uicontrol {Render Preprocess} \li Render @@ -442,8 +419,6 @@ \li time in renderer ... preprocess \li Calling QSGNode::preprocess() on all nodes that need to be preprocessed. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Render Update} \li Render @@ -455,8 +430,6 @@ with state from the GUI thread. In \uicontrol {Render Update}, all the nodes are combined to create the final scene. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Render Bind} \li Render @@ -464,8 +437,6 @@ \li time in renderer ... binding \li Binding the correct framebuffer for OpenGL rendering. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Render Render} \li Render @@ -473,38 +444,30 @@ \li time in renderer ... rendering \li The actual process of sending all the data to the GPU via OpenGL. This is part of the gross \uicontrol {Render} step. - \li May not be properly aligned with \uicontrol {Render} with versions of Qt - prior to Qt 5.5. \row \li \uicontrol {Material Compile} \li Render \li Threaded, Basic, Windows \li shader compiled \li Compiling GLSL shader programs. - \li None \row \li \uicontrol {Glyph Render} \li Render \li Threaded, Basic, Windows \li glyphs ... rendering \li Rendering of font glyphs into textures. - \li Versions of Qt prior to Qt 5.4 report incorrect times for these - events. \row \li \uicontrol {Glyph Upload} \li Render \li Threaded, Basic, Windows \li glyphs ... upload \li Uploading of glyph textures to the GPU. - \li Versions of Qt prior to Qt 5.4 report incorrect times for these - events. \row \li \uicontrol {Texture Bind} \li Render \li Threaded, Basic, Windows \li plain texture ... bind \li Binding a texture in the OpenGL context using glBindTextures. - \li None \row \li \uicontrol {Texture Convert} \li Render @@ -512,35 +475,30 @@ \li plain texture ... convert \li Converting the format and downscaling an image to make it suitable for usage as a texture. - \li None \row \li \uicontrol {Texture Swizzle} \li Render \li Threaded, Basic, Windows \li plain texture ... swizzle \li Swizzling the texture data on the CPU if necessary. - \li None \row \li \uicontrol {Texture Upload} \li Render \li Threaded, Basic, Windows \li plain texture ... upload / atlastexture uploaded \li Uploading the texture data to the GPU. - \li None \row \li \uicontrol {Texture Mipmap} \li Render \li Threaded, Basic, Windows \li plain texture ... mipmap \li Mipmapping a texture on the GPU. - \li None \row \li \uicontrol {Texture Delete} \li Render \li Threaded, Basic, Windows \li plain texture deleted \li Deleting a texture from the GPU that became unnecessary. - \li None \endtable \section2 Analyzing Qt Quick 3D Events @@ -550,7 +508,7 @@ Synchronize happens in scene graph synchronizing phase, while prepare and render happen in scene graph rendering phase. - Setting the environment variable \c QSG_RENDERER_DEBUG=render will also give + Set the environment variable \c QSG_RENDERER_DEBUG=render to get additional textual output of render call counts of different rendering passes. These call counts are summed up in the Render Frame event. @@ -616,24 +574,24 @@ The \uicontrol Statistics view displays the number of times each binding, create, compile, JavaScript, or signal event is triggered and the average time it - takes. This allows you to examine which events you need to optimize. A high + takes. Examine the statistics to learn which events to optimize. A high number of occurrences might indicate that an event is triggered unnecessarily. To view the median, longest, and shortest time for the occurrences, select \uicontrol {Extended Event Statistics} in the context menu. - Click on an event to move to it in the source code + Select an event to move to it in the source code in the code editor. \image qml-profiler-statistics.png "Statistics view" - The \uicontrol Callers and \uicontrol Callees panes show dependencies between events. + \uicontrol Callers and \uicontrol Callees show dependencies between events. They allow you to examine the internal functions of the application. - The \uicontrol Callers pane summarizes the QML events that trigger a binding. + \uicontrol Callers summarizes the QML events that trigger a binding. This tells you what caused a change in a binding. - The \uicontrol Callees pane summarizes the QML events that a binding triggers. + \uicontrol Callees summarizes the QML events that a binding triggers. This tells you which QML events are affected if you change a binding. - Click on an event to move to it in the source code in the code editor. + Select an event to move to it in the source code in the code editor. When you select an event in the \uicontrol Timeline view, information about it is displayed in the \uicontrol Statistics and \uicontrol {Flame Graph} @@ -642,9 +600,6 @@ To copy the contents of one view or row to the clipboard, select \uicontrol {Copy Table} or \uicontrol {Copy Row} in the context menu. - JavaScript events are shown in the \uicontrol Statistics view only for applications - that use Qt Quick 2 and are compiled with Qt 5.3 or later. - \section2 Visualizing Statistics as Flame Graphs The \uicontrol {Flame Graph} view shows a more concise statistical overview @@ -671,4 +626,9 @@ suitable for analyzing per frame execution times. However, it is very easy to see the total impact of the various QML and JavaScript events there. + \sa {Profile QML applications} + + \if defined(qtcreator) + \sa {Analyze}{How To: Analyze}, {Analyzers}, {Analyzing Code} + \endif */ diff --git a/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc b/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc index 24f3b38479..a8ce9dbb5a 100644 --- a/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-file-system-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -15,7 +15,11 @@ \title File System + \if defined(qtdesignstudio) + \brief View all the files in the current directory. + \else \brief Shows all the files in the current directory. + \endif \if defined(qtcreator) \note Usually, \l{Navigate with locator}{searching with the locator} @@ -25,14 +29,14 @@ \image qtcreator-filesystem-view.webp {File System view in the sidebar} \else - \image qtcreator-filesystem-view-design.png {File System view} + \image filesystem-view-design.webp {File System view} \endif - To move to the root directory of the file system, select \uicontrol Computer - in the menu (1). Select \uicontrol Home to move to the user's home - directory. Further, you can select a project to move to an open project - or \uicontrol Projects to move to the directory specified in the - \uicontrol {Projects directory} field in \preferences > + To go to the root directory of the file system, select \uicontrol Computer + in the menu (1). Select \uicontrol Home to go to the user's home + directory. Further, you can select a project to go to an open project + or \uicontrol Projects to go to the directory specified in + \uicontrol {Projects directory} in \preferences > \uicontrol {Build & Run} > \uicontrol General. The file that is currently active in the editor determines which folder @@ -46,12 +50,13 @@ \endlist To stop the synchronization between the editor and the - \uicontrol {File System} view, deselect the \inlineimage icons/linkicon.png - (\uicontrol {Synchronize Root Directory with Editor}) button. + \uicontrol {File System} view, clear \inlineimage icons/linkicon.png + (\uicontrol {Synchronize Root Directory with Editor}). The view displays the path to the active file as bread crumbs. You can move to any directory along the path by clicking it. + \if defined(qtcreator) \section1 File System Context Menu Use the context menu functions to: @@ -64,34 +69,24 @@ that has the file. To specify the terminal to use on Linux and \macos, select \preferences > \uicontrol Environment > \uicontrol System. - \if defined(qtcreator) To use an \l{Terminal} {internal terminal}, select \preferences > \uicontrol Terminal > \uicontrol {Use internal terminal}. - \endif \li Search in the selected directory. \li View file properties, such as name, path, MIME type, default editor, line endings, indentation, owner, size, last read and modified dates, and permissions. - \li Create new files. For more information, see - \if defined(qtdesignstudio) - \l{Adding Files to Projects}. - \else - \l{Create files}. - \endif + \li Create new files. For more information, see {Create files}. \li Rename existing files. To move the file to another directory, enter the relative or absolute path to its new location in addition to the new filename. \li Remove existing files. \li Create new folders. - \if defined(qtcreator) \li Compare the selected file with the currently open file in the diff editor. For more information, see \l{Compare files}. - \endif \li Display the contents of a particular directory in the view. \li Collapse all open folders. \endlist - \if defined(qtcreator) \section1 File System View Toolbar The toolbar in the \uicontrol {File System} view has additional @@ -101,16 +96,15 @@ (\uicontrol Options): \list - \li To hide the bread crumbs, deselect the - \uicontrol {Show Bread Crumbs} check box. + \li To hide the bread crumbs, clear \uicontrol {Show Bread Crumbs}. \li By default, the view separates folders from files and lists them - first. To list all items in alphabetic order, deselect the - \uicontrol {Show Folders on Top} check box. + first. To list all items in alphabetic order, clear + \uicontrol {Show Folders on Top}. \li To also show hidden files, select \uicontrol {Show Hidden Files}. \endlist To stop the synchronization with the file currently open in the - editor, deselect \inlineimage icons/linkicon.png + editor, clear \inlineimage icons/linkicon.png (\uicontrol {Synchronize with Editor}). \sa {View CMake project contents}, {Projects} diff --git a/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc b/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc index 230ce2adde..106562ab55 100644 --- a/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc +++ b/doc/qtcreator/src/user-interface/creator-only/creator-how-to-show-and-hide-sidebars.qdoc @@ -15,7 +15,7 @@ Select views in the sidebar menu (1): - \image qtcreator-sidebar.png + \image qtcreator-sidebar.webp {Views open in the sidebar} You can change the view of the sidebars in the following ways: diff --git a/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc b/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc index 5d78d8345c..61613519c3 100644 --- a/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-only/creator-reference-to-do-entries-view.qdoc @@ -63,7 +63,7 @@ \li To determine whether the keywords in the whole project, in the current file, or in a subproject are displayed by default, select - the appropriate option in the \uicontrol {Scanning scope} group. + the appropriate option in the \uicontrol {Scanning Scope} group. \endlist diff --git a/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc b/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc index 87760c448c..67c0134c78 100644 --- a/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-open-documents-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -16,13 +16,26 @@ \title Open Documents + \if defined(qtdesignstudio) + \brief View currently open files. + \else \brief Shows currently open files. + \endif + \if defined(qtdesignstudio) + \image open-documents-view.webp {Open Documents view} + \else \image qtcreator-open-documents-view.png {Open Documents view} + \endif You can use the context menu to apply some of the functions also available - in the \uicontrol File menu and in the \l {File System Context Menu} - {File System} view to the file that you select in the view. + in the \uicontrol File menu and in the + \if defined(qtcreator) + \l {File System Context Menu}{File System} + \else + \uicontrol {File System} + \endif + view to the file that you select in the view. In addition, you can: diff --git a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc index b6b74f0993..d28e6f9ef0 100644 --- a/doc/qtcreator/src/user-interface/creator-projects-view.qdoc +++ b/doc/qtcreator/src/user-interface/creator-projects-view.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2023 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -15,7 +15,11 @@ \title Projects + \if defined(qtdesignstudio) + \brief View a list of the files contained within the open project. + \else \brief Shows a list of projects in a project tree. + \endif \if defined(qtcreator) The project tree has a list of all projects open in the current @@ -29,7 +33,7 @@ is the fastest way to find a particular project, file, class, or function, or almost anything else in your project. \else - \image qtcreator-projects-view-design.png {Projects view} + \image projects-view-design.webp {Projects view} \endif You can use the project tree in the following ways: @@ -43,14 +47,19 @@ Use the \l{Switch between modes} {mode selector} to open the current file in another editor. \endif - \li To bring up a \l{Projects View Context Menu}{context menu} + \li To open a + \if defined(qtcreator) + \l{Projects View Context Menu}{context menu} + \else + context menu + \endif that has the actions most commonly needed, right-click an item in the project tree. For example, through the menu of the project root directory you can, among other actions, run and close the project. \li To see the absolute path of a file, move the mouse pointer over the file name. - \li To move files from one project to another, drag-and-drop them + \li To move files from one project to another, drag them in the project tree. \QC makes the necessary changes to project configuration files. \endlist @@ -58,6 +67,7 @@ \note If you cannot see a file in the \l Projects view, switch to the \uicontrol {File System} view, which shows all the files in the file system. + \if defined(qtcreator) \section1 Projects View Context Menu The \uicontrol Projects view has context menus for managing projects, @@ -65,22 +75,15 @@ projects and subprojects: \list - \if defined(qtcreator) \li Set a project as the active project. - \endif \li Execute \uicontrol Build menu commands. \li Create new files. For more information, see - \if defined(qtdesignstudio) - \l{Adding Files to Projects}. - \else \l{Create files}. - \endif \li Rename existing files. If you change the base name of a file, \QC displays a list of other files with the same base name and offers to rename them as well. If you rename a UI file (.ui), \QC also changes corresponding include statements accordingly. \li Remove existing files. - \if defined(qtcreator) \li Remove existing directories from \l{Import an existing project} {generic projects}. \li Add existing files and directories. @@ -88,16 +91,13 @@ \l{Add libraries to qmake projects}. \li Add and remove subprojects. \li Find unused functions. - \endif \li Search in the selected directory. \li Open a terminal window in the project directory. To specify the terminal to use on Linux and \macos, select \preferences > \uicontrol Environment > \uicontrol System. - \if defined(qtcreator) To use an \l{Terminal}{internal terminal}, select \preferences > \uicontrol Terminal > \uicontrol {Use internal terminal}. - \endif \li Open a terminal window in the project directory that you configured for building or running the project. \li Expand or collapse the tree view to show or hide all files and @@ -114,7 +114,6 @@ the \l {File System} view. To view a project in it, select \uicontrol {Show in File System View}. - \if defined(qtcreator) \section1 Projects View Toolbar The toolbar in the \uicontrol Projects view has additional options. diff --git a/doc/qtcreator/src/user-interface/creator-ui.qdoc b/doc/qtcreator/src/user-interface/creator-ui.qdoc index 9041e6432f..9794667f5b 100644 --- a/doc/qtcreator/src/user-interface/creator-ui.qdoc +++ b/doc/qtcreator/src/user-interface/creator-ui.qdoc @@ -95,7 +95,7 @@ \endif \if defined(qtdesignstudio) - \section1 Customizing the Menu + \section1 Customizing the Menu Bar By default, top-level menu items \uicontrol Build, \uicontrol Debug, and \uicontrol Analyze are not visible. These menu items have options for @@ -113,6 +113,9 @@ You need to restart \QDS to apply changes made to these settings. + \note To show or hide the \uicontrol {Menu Bar}, select \uicontrol View > + \uicontrol {Show Menu Bar}, or use \key {Ctrl+Alt+M}. + \section1 Customizing the UI The following topics describe how to customize the UI: diff --git a/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc b/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc index 443aa40be4..6c9c93ff51 100644 --- a/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc +++ b/doc/qtcreator/src/vcs/creator-only/creator-vcs-perforce.qdoc @@ -35,11 +35,26 @@ Set workspace details in \uicontrol {P4 user}, \uicontrol {P4 client}, and \uicontrol {P4 port}. - To specify the details individually for several projects, use configuration - files instead. Create a \c {p4config.txt} configuration file for each - project in the top level project directory, and run - \c{p4 set P4CONFIG=p4config.txt} once. You must deselect the - \uicontrol {Environment Variables} check box. + \section1 Using Configuration Files + + To specify workspace details individually for several projects, use + configuration files: + + \list 1 + \li Create a \c {p4config.txt} configuration file for each project in the + top level project directory. + \li Go to \preferences > \uicontrol {Version Control} > + \uicontrol Perforce. + \li Clear \uicontrol {Environment Variables}. + \li To set \c P4CONFIG to use the file that you created, run the + following command from the command line once: + \badcode + p4 set P4CONFIG=p4config.txt + \endcode + \endlist + + For more information about using the \c P4CONFIG variable, see + \l{Perforce: P4CONFIG}. \section1 Editing Files diff --git a/doc/qtcreator/src/vcs/creator-vcs-git.qdoc b/doc/qtcreator/src/vcs/creator-vcs-git.qdoc index ea23e53443..e853a86812 100644 --- a/doc/qtcreator/src/vcs/creator-vcs-git.qdoc +++ b/doc/qtcreator/src/vcs/creator-vcs-git.qdoc @@ -30,10 +30,6 @@ You can use the \l{http://code.google.com/p/gerrit/}{Gerrit} code review tool for projects that use Git. - \if defined(qtdesignstudio) - \include creator-vcs-options.qdocinc vcs options - \endif - \if defined(qtcreator) \section1 Using Git for Windows diff --git a/doc/qtcreator/src/webassembly/creator-webassembly.qdoc b/doc/qtcreator/src/webassembly/creator-webassembly.qdoc index 4a459e8cdd..ab757d7add 100644 --- a/doc/qtcreator/src/webassembly/creator-webassembly.qdoc +++ b/doc/qtcreator/src/webassembly/creator-webassembly.qdoc @@ -1,116 +1,71 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2024 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \previouspage creator-developing-generic-linux.html \page creator-setup-webassembly.html - \nextpage creator-build-process-customizing.html + \previouspage creator-how-tos.html - \title Building Applications for the Web + \ingroup creator-how-to-webassembly - WebAssembly is a binary format that allows sand-boxed executable code in - web pages. This format is nearly as fast as native machine code, and is - now supported by all major web browsers. + \title Build applications for the Web - \l {Qt for WebAssembly} enables building Qt applications so that they can be - integrated into web pages. It doesn't require any client-side installations - and reduces the use of server-side resources. + WebAssembly is a binary format that allows sand-boxed executable code in + web pages. This format is nearly as fast as native machine code. It is + supported by all major web browsers. - The experimental WebAssembly plugin enables you to build your applications - in WebAssembly format and deploy and run them in the local web browser. - You can change the web browser in the project's \l{Specifying Run Settings} - {run settings}. + Use \l {Qt for WebAssembly} to build your applications in WebAssembly format + and deploy and run them on the local web browser. Change the web browser in + the project's \l{Run applications in a web browser}{run settings}. \note Enable the WebAssembly plugin to use it. - To build applications for the web and run them in a web browser, you need to - install Qt for WebAssembly and the tool chain for compiling to WebAssembly. - - \section1 Requirements - - You need the following software to build Qt applications for the web and run - them in a browser: - - \list - \li Qt for WebAssembly 5.15, or later - \li On Windows: \l{http://wiki.qt.io/MinGW}{\MinGW} 7.3.0, or later - \li \l{https://emscripten.org/docs/introducing_emscripten/index.html} - {emscripten} tool chain for compiling to WebAssembly - \endlist - - \section1 Setting Up the Development Environment + To build applications for the web and run them in a web browser, install + Qt for WebAssembly with \QOI. It automatically adds a build and run kit + to \QC. - You need to install and configure Qt for WebAssembly and the tool chain for - compiling to WebAssembly. \QOI automatically adds a build and - run kit to \QC. + \section1 Set up WebAssembly development environment - \section2 Setting Up Qt for WebAssembly - - To set up Qt for WebAssembly: - - \list 1 - \li Use \QMT to install Qt for WebAssembly and, on - Windows, \MinGW (found in \uicontrol {Developer and Designer Tools}). - \li Check out a known-good Emscripten version supported by the Qt for - WebAssembly version that you installed, and install and activate - \c emscripten, as instructed in - \l {https://doc.qt.io/qt-5/wasm.html#install-emscripten} - {Install Emscripten}. - \endlist - - \section2 Specifying WebAssembly Settings - - To configure \QC for building Qt apps for the web: + To set up the development environment for WebAssembly: \list 1 - \li Select \preferences > \uicontrol Devices > \uicontrol WebAssembly. - \li In the \uicontrol {Emscripten SDK path} field, enter the root - directory where \c emsdk is installed. + \li Go to \preferences > \uicontrol Devices > \uicontrol WebAssembly. + \li In \uicontrol {Emscripten SDK path}, enter the root directory where + you installed \c emsdk. \li \QC configures the \uicontrol {Emscripten SDK environment} for you - if the \c emsdk is supported by the Qt for WebAssembly version that - you will use for developing the application. - \image qtcreator-webassembly-options.png "Qt for WebAssembly device preferences" - \li Select \preferences > \uicontrol Kits. - \image qtcreator-kit-webassembly.png "Qt for WebAssembly kit" - \li In the \uicontrol Compiler group, \uicontrol {Emscripten Compiler} - should have been automatically detected for both C++ and C. If not, - check that emscripten is set up correctly. + if your Qt for WebAssembly version supports the \c emsdk. + \image qtcreator-webassembly-options.png {Qt for WebAssembly device preferences} + \li Go to \preferences > \uicontrol Kits. + \image qtcreator-kit-webassembly.png {Qt for WebAssembly kit} + \li If \uicontrol {Emscripten Compiler} was not automatically set + for both C++ and C, check that emscripten is set up correctly. \endlist - \section2 Adding WebAssembly Kits + \sa {Run applications in a web browser} +*/ - The Qt for Web Assembly installation automatically adds build and run kits - to \QC. To add kits: +/*! + \page creator-how-to-run-webassembly.html + \previouspage creator-how-tos.html - \list 1 - \li Select \preferences > \uicontrol Kits > \uicontrol Add. - \li In the \uicontrol Name field, specify a name for the kit. - \li In the \uicontrol {Run device type} field, select - \uicontrol {WebAssembly Runtime}. - The value of the \uicontrol Device field is automatically - set to \uicontrol {Web Browser}. - \li In the \uicontrol Compiler field, select - \uicontrol {Emscripten Compiler} for both C and C++. - \li Select \uicontrol Apply to add the kit. - \endlist + \ingroup creator-how-to-webassembly - \section1 Running Applications in a Web Browser + \title Run applications in a web browser - To run a project: + To build Qt applications in \l{Qt for WebAssembly}{WebAssembly} format and + run them in a web browser: \list 1 \li Open a project for an application you want to run in a web browser. - \li Select \uicontrol Projects > \uicontrol {Build & Run}, and then + \li Go to \uicontrol Projects > \uicontrol {Build & Run}, and then select the WebAssembly kit as the build and run kit for the project. \li Select \uicontrol Run to specify run settings. - \li In the \uicontrol {Web browser} field, select the browser to run - the application in. - \image qtcreator-settings-run-webassembly.png "Selecting the browser to run in" + \li In \uicontrol {Web browser}, select a browser. + \image qtcreator-settings-run-webassembly.png {Selecting the browser to run in} \endlist - You can now build Qt applications in WebAssembly format and run them in + Build Qt applications in WebAssembly format and run them in a web browser as described in \l {Build for many platforms} and \l{Run on many platforms}. - \sa {Enable and disable plugins} + \sa {Build applications for the Web}, {Enable and disable plugins} */ diff --git a/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc b/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc index 93ed060e4a..eb93c69a8c 100644 --- a/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc +++ b/doc/qtcreator/src/widgets/creator-faq-qtdesigner.qdocinc @@ -4,7 +4,7 @@ /*! //! [qt designer faq] - \section1 Qt Designer Integration Questions + \section1 \QD Integration Questions \b {Why are custom widgets not loaded in the \uicontrol Design mode even though it works in standalone \QD?} @@ -13,7 +13,7 @@ that match its build key. The locations are different for standalone and integrated \QD. - For more information, see \l{Adding Qt Designer Plugins}. + For more information, see \l{Adding \QD Plugins}. //! [qt designer faq] */ diff --git a/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc b/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc index f3717ee049..8f744bced0 100644 --- a/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc +++ b/doc/qtcreator/src/widgets/qtdesigner-app-tutorial.qdoc @@ -197,7 +197,7 @@ \endlist For more information about designing forms with \QD, see the - \l{Qt Designer Manual}. + \l{\QD Manual}. \section2 Completing the Header File diff --git a/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc b/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc index b2357514fa..29d2c7d34b 100644 --- a/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc +++ b/doc/qtcreator/src/widgets/qtdesigner-overview.qdoc @@ -29,7 +29,7 @@ Furthermore, features such as widget promotion and custom plugins allow you to use your own widgets with \QD. - For more information about \QD, see the \l{Qt Designer Manual}. + For more information about \QD, see the \l{\QD Manual}. Generally, the integrated \QD has the same functions as the standalone \QD. The following sections describe the differences. @@ -62,7 +62,7 @@ \uicontrol {Follow Symbol Under Cursor} in the context menu or press \key F2 when the cursor is over a string literal. - \section1 Specifying Settings for Qt Designer + \section1 Specifying Settings for \QD You can drag and drop the views in \QD to new positions on the screen. @@ -102,7 +102,7 @@ \list 1 \li \preferences > \uicontrol Designer. - \image qtdesigner-embedded-design.png "Qt Designer Embedded Design preferences" + \image qtdesigner-embedded-design.png "Qt Widgets Designer Embedded Design preferences" \li In \uicontrol {Embedded Design}, select \inlineimage icons/plus.png to open the \uicontrol {Add Profile} dialog. \image qtdesigner-add-profile.png "Add Profile dialog" @@ -119,5 +119,5 @@ To import device profiles from .qdp files, select \uicontrol Open. To save them as .qdp files, select \uicontrol Save. - \sa {Creating a Qt Widget Based Application}, {Adding Qt Designer Plugins} + \sa {Creating a Qt Widget Based Application}, {Adding \QD Plugins} */ diff --git a/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc b/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc index 00f61ab051..3ce3dc02f7 100644 --- a/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc +++ b/doc/qtcreator/src/widgets/qtdesigner-plugins.qdoc @@ -26,7 +26,7 @@ and to change the default plugin path, see \l{How to Create Qt Plugins}. For more information about how to create plugins for \QD, see - \l{Using Custom Widgets with Qt Designer}. + \l{Using Custom Widgets with \QD}. \section1 Locating \QD Plugins @@ -42,7 +42,7 @@ To check which plugins were loaded successfully and which failed, choose \uicontrol Tools > \uicontrol {Form Editor} > - \uicontrol {About Qt Designer Plugins}. + \uicontrol {About \QD Plugins}. The standalone \QD is part of the Qt library used for building projects, located in \c {<Qt_version>\<compiler>\bin} in the Qt installation |
