diff options
| author | Eike Ziller <eike.ziller@qt.io> | 2023-03-29 12:21:50 +0200 |
|---|---|---|
| committer | Eike Ziller <eike.ziller@qt.io> | 2023-03-29 12:21:50 +0200 |
| commit | b36287731eb8ab3895a1e7e19f071009dd1c1ad4 (patch) | |
| tree | 4a9999b27058b8efee4ed74cd40f4f16dd97b34f /doc | |
| parent | 6ab923c39fd4ac66edb3cf708e3c789cb4a31428 (diff) | |
| parent | 81a5e2143cb7728316e02d24925f853e2db2099a (diff) | |
| download | qt-creator-b36287731eb8ab3895a1e7e19f071009dd1c1ad4.tar.gz | |
Merge remote-tracking branch 'origin/10.0'
Conflicts:
cmake/QtCreatorIDEBranding.cmake
qbs/modules/qtc/qtc.qbs
src/plugins/remotelinux/genericlinuxdeviceconfigurationwidget.cpp
src/tools/perfparser
Change-Id: Ie5643100e0eb00e0933359dce320169b876f5634
Diffstat (limited to 'doc')
62 files changed, 931 insertions, 609 deletions
diff --git a/doc/qtcreator/images/extraimages/images/5OiIqFTjUZI.jpg b/doc/qtcreator/images/extraimages/images/5OiIqFTjUZI.jpg Binary files differnew file mode 100644 index 0000000000..91dbba8327 --- /dev/null +++ b/doc/qtcreator/images/extraimages/images/5OiIqFTjUZI.jpg diff --git a/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf b/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf index af81e51192..200058d4a4 100644 --- a/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf +++ b/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf @@ -1,2 +1,3 @@ {HTML.extraimages,qhp.QtCreator.extraFiles} += \ - images/commercial.png + images/commercial.png \ + images/5OiIqFTjUZI.jpg diff --git a/doc/qtcreator/images/qcreator-debugger-select-start-address.webp b/doc/qtcreator/images/qcreator-debugger-select-start-address.webp Binary files differnew file mode 100644 index 0000000000..2e24b71085 --- /dev/null +++ b/doc/qtcreator/images/qcreator-debugger-select-start-address.webp diff --git a/doc/qtcreator/images/qtcreator-add-breakpoint.png b/doc/qtcreator/images/qtcreator-add-breakpoint.png Binary files differdeleted file mode 100644 index 1a399df7b9..0000000000 --- a/doc/qtcreator/images/qtcreator-add-breakpoint.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-add-breakpoint.webp b/doc/qtcreator/images/qtcreator-add-breakpoint.webp Binary files differnew file mode 100644 index 0000000000..8bef878050 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-add-breakpoint.webp diff --git a/doc/qtcreator/images/qtcreator-android-build-apk-step.png b/doc/qtcreator/images/qtcreator-android-build-apk-step.png Binary files differdeleted file mode 100644 index 8e3b7c43e0..0000000000 --- a/doc/qtcreator/images/qtcreator-android-build-apk-step.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-app-icon.png b/doc/qtcreator/images/qtcreator-android-manifest-editor-app-icon.png Binary files differdeleted file mode 100644 index 60678658b1..0000000000 --- a/doc/qtcreator/images/qtcreator-android-manifest-editor-app-icon.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-app-icon.webp b/doc/qtcreator/images/qtcreator-android-manifest-editor-app-icon.webp Binary files differnew file mode 100644 index 0000000000..b596da36f8 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-android-manifest-editor-app-icon.webp diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-package.png b/doc/qtcreator/images/qtcreator-android-manifest-editor-package.png Binary files differdeleted file mode 100644 index 843ca804bf..0000000000 --- a/doc/qtcreator/images/qtcreator-android-manifest-editor-package.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-package.webp b/doc/qtcreator/images/qtcreator-android-manifest-editor-package.webp Binary files differnew file mode 100644 index 0000000000..bc4546b838 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-android-manifest-editor-package.webp diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-permissions.png b/doc/qtcreator/images/qtcreator-android-manifest-editor-permissions.png Binary files differdeleted file mode 100644 index 3918c8fb7a..0000000000 --- a/doc/qtcreator/images/qtcreator-android-manifest-editor-permissions.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-permissions.webp b/doc/qtcreator/images/qtcreator-android-manifest-editor-permissions.webp Binary files differnew file mode 100644 index 0000000000..84c434e53d --- /dev/null +++ b/doc/qtcreator/images/qtcreator-android-manifest-editor-permissions.webp diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-services.png b/doc/qtcreator/images/qtcreator-android-manifest-editor-services.png Binary files differdeleted file mode 100644 index d9850e54ea..0000000000 --- a/doc/qtcreator/images/qtcreator-android-manifest-editor-services.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-splash-screen.png b/doc/qtcreator/images/qtcreator-android-manifest-editor-splash-screen.png Binary files differdeleted file mode 100644 index d90e58b33f..0000000000 --- a/doc/qtcreator/images/qtcreator-android-manifest-editor-splash-screen.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-manifest-editor-splash-screen.webp b/doc/qtcreator/images/qtcreator-android-manifest-editor-splash-screen.webp Binary files differnew file mode 100644 index 0000000000..b03558c66c --- /dev/null +++ b/doc/qtcreator/images/qtcreator-android-manifest-editor-splash-screen.webp diff --git a/doc/qtcreator/images/qtcreator-android-sdk-manager.png b/doc/qtcreator/images/qtcreator-android-sdk-manager.png Binary files differdeleted file mode 100644 index 7f24683d74..0000000000 --- a/doc/qtcreator/images/qtcreator-android-sdk-manager.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-android-sdk-manager.webp b/doc/qtcreator/images/qtcreator-android-sdk-manager.webp Binary files differnew file mode 100644 index 0000000000..89a1900c90 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-android-sdk-manager.webp diff --git a/doc/qtcreator/images/qtcreator-autotests-options-boost.png b/doc/qtcreator/images/qtcreator-autotests-options-boost.png Binary files differdeleted file mode 100644 index fedb2a7a15..0000000000 --- a/doc/qtcreator/images/qtcreator-autotests-options-boost.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-autotests-options-catch2.png b/doc/qtcreator/images/qtcreator-autotests-options-catch2.png Binary files differdeleted file mode 100644 index 347f497247..0000000000 --- a/doc/qtcreator/images/qtcreator-autotests-options-catch2.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-autotests-options-ctest.png b/doc/qtcreator/images/qtcreator-autotests-options-ctest.png Binary files differdeleted file mode 100644 index 071cba4a71..0000000000 --- a/doc/qtcreator/images/qtcreator-autotests-options-ctest.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-autotests-options-google.png b/doc/qtcreator/images/qtcreator-autotests-options-google.png Binary files differdeleted file mode 100644 index 640da46fd5..0000000000 --- a/doc/qtcreator/images/qtcreator-autotests-options-google.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-autotests-options-qt.png b/doc/qtcreator/images/qtcreator-autotests-options-qt.png Binary files differdeleted file mode 100644 index 808ac1109e..0000000000 --- a/doc/qtcreator/images/qtcreator-autotests-options-qt.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-autotests-options.png b/doc/qtcreator/images/qtcreator-autotests-options.png Binary files differdeleted file mode 100644 index 4d945f6c93..0000000000 --- a/doc/qtcreator/images/qtcreator-autotests-options.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-build-settings-android-apk.webp b/doc/qtcreator/images/qtcreator-build-settings-android-apk.webp Binary files differnew file mode 100644 index 0000000000..a0d28c9ecb --- /dev/null +++ b/doc/qtcreator/images/qtcreator-build-settings-android-apk.webp diff --git a/doc/qtcreator/images/qtcreator-debug-breakpoints.png b/doc/qtcreator/images/qtcreator-debug-breakpoints.png Binary files differdeleted file mode 100644 index 7594830661..0000000000 --- a/doc/qtcreator/images/qtcreator-debug-breakpoints.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-debug-breakpoints.webp b/doc/qtcreator/images/qtcreator-debug-breakpoints.webp Binary files differnew file mode 100644 index 0000000000..69c22405a2 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debug-breakpoints.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-breakpoint-preset.png b/doc/qtcreator/images/qtcreator-debugger-breakpoint-preset.png Binary files differdeleted file mode 100644 index e5fa486f2e..0000000000 --- a/doc/qtcreator/images/qtcreator-debugger-breakpoint-preset.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-debugger-breakpoint-preset.webp b/doc/qtcreator/images/qtcreator-debugger-breakpoint-preset.webp Binary files differnew file mode 100644 index 0000000000..9fd3335126 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-breakpoint-preset.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-disassembler-view.webp b/doc/qtcreator/images/qtcreator-debugger-disassembler-view.webp Binary files differnew file mode 100644 index 0000000000..7fcf5a13f1 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-disassembler-view.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-expressions.png b/doc/qtcreator/images/qtcreator-debugger-expressions.png Binary files differdeleted file mode 100644 index ef9e972071..0000000000 --- a/doc/qtcreator/images/qtcreator-debugger-expressions.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-debugger-expressions.webp b/doc/qtcreator/images/qtcreator-debugger-expressions.webp Binary files differnew file mode 100644 index 0000000000..2a14cce5d5 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-expressions.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-log-view.webp b/doc/qtcreator/images/qtcreator-debugger-log-view.webp Binary files differnew file mode 100644 index 0000000000..ce3e265365 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-log-view.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-memory-editor.webp b/doc/qtcreator/images/qtcreator-debugger-memory-editor.webp Binary files differnew file mode 100644 index 0000000000..ef51b1dd29 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-memory-editor.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-modules.webp b/doc/qtcreator/images/qtcreator-debugger-modules.webp Binary files differnew file mode 100644 index 0000000000..e4af9e817d --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-modules.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-new-evaluated-expression.webp b/doc/qtcreator/images/qtcreator-debugger-new-evaluated-expression.webp Binary files differnew file mode 100644 index 0000000000..1934a05372 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-new-evaluated-expression.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-peripheral-registers-view.webp b/doc/qtcreator/images/qtcreator-debugger-peripheral-registers-view.webp Binary files differnew file mode 100644 index 0000000000..34c8813108 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-peripheral-registers-view.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-registers-view.webp b/doc/qtcreator/images/qtcreator-debugger-registers-view.webp Binary files differnew file mode 100644 index 0000000000..05b08e9668 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-registers-view.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-source-files.webp b/doc/qtcreator/images/qtcreator-debugger-source-files.webp Binary files differnew file mode 100644 index 0000000000..7f8faabd4f --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-source-files.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-views-initial.webp b/doc/qtcreator/images/qtcreator-debugger-views-initial.webp Binary files differnew file mode 100644 index 0000000000..be250d19aa --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-views-initial.webp diff --git a/doc/qtcreator/images/qtcreator-debugger-views.png b/doc/qtcreator/images/qtcreator-debugger-views.png Binary files differdeleted file mode 100644 index 32e9257269..0000000000 --- a/doc/qtcreator/images/qtcreator-debugger-views.png +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-debugger-views.webp b/doc/qtcreator/images/qtcreator-debugger-views.webp Binary files differnew file mode 100644 index 0000000000..6d81d538f5 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-debugger-views.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-devices-docker-device.png b/doc/qtcreator/images/qtcreator-preferences-devices-docker-device.png Binary files differnew file mode 100644 index 0000000000..6465c5ae50 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-devices-docker-device.png diff --git a/doc/qtcreator/images/qtcreator-preferences-devices-docker-device.webp b/doc/qtcreator/images/qtcreator-preferences-devices-docker-device.webp Binary files differdeleted file mode 100644 index 413112c939..0000000000 --- a/doc/qtcreator/images/qtcreator-preferences-devices-docker-device.webp +++ /dev/null diff --git a/doc/qtcreator/images/qtcreator-preferences-testing-boosttest.webp b/doc/qtcreator/images/qtcreator-preferences-testing-boosttest.webp Binary files differnew file mode 100644 index 0000000000..5f29bae2b6 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-testing-boosttest.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-testing-catchtest.webp b/doc/qtcreator/images/qtcreator-preferences-testing-catchtest.webp Binary files differnew file mode 100644 index 0000000000..3e5cadcb2f --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-testing-catchtest.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-testing-ctest.webp b/doc/qtcreator/images/qtcreator-preferences-testing-ctest.webp Binary files differnew file mode 100644 index 0000000000..2394370dc8 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-testing-ctest.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-testing-general.webp b/doc/qtcreator/images/qtcreator-preferences-testing-general.webp Binary files differnew file mode 100644 index 0000000000..0b92925e6a --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-testing-general.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-testing-googletest.webp b/doc/qtcreator/images/qtcreator-preferences-testing-googletest.webp Binary files differnew file mode 100644 index 0000000000..1a60a66ae9 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-testing-googletest.webp diff --git a/doc/qtcreator/images/qtcreator-preferences-testing-qttest.webp b/doc/qtcreator/images/qtcreator-preferences-testing-qttest.webp Binary files differnew file mode 100644 index 0000000000..f6df07907e --- /dev/null +++ b/doc/qtcreator/images/qtcreator-preferences-testing-qttest.webp diff --git a/doc/qtcreator/images/qtcreator-run-settings-python.webp b/doc/qtcreator/images/qtcreator-run-settings-python.webp Binary files differnew file mode 100644 index 0000000000..341a931a17 --- /dev/null +++ b/doc/qtcreator/images/qtcreator-run-settings-python.webp diff --git a/doc/qtcreator/src/android/androiddev.qdoc b/doc/qtcreator/src/android/androiddev.qdoc index 2c39ce3e51..a171476b13 100644 --- a/doc/qtcreator/src/android/androiddev.qdoc +++ b/doc/qtcreator/src/android/androiddev.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -8,36 +8,37 @@ \title Connecting Android Devices - You can connect Android devices to the development PC using USB cables - to build, run, debug, and analyze applications from \QC. Devices with - Android version 4.1 (API level 16) or later are supported when developing - with Qt 5 and devices with Android version 6.0 (API level 23) when - developing with Qt 6. + You can connect Android devices to the development PC using USB cables to + build, run, debug, and analyze applications from \QC. - To develop for Android, you must have a tool chain for building applications - for Android devices installed on the development PC. \QC can automatically + 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. - Starting from Qt 5.14.0, the Qt for Android package has all the - architectures (ABIs) installed as one. - To enable helpful code editing features for Java, such as code completion, highlighting, function tooltips, and navigating in code, add a \l{Java Language Server}{Java language server}. - The Android Debug Bridge (adb) command line tool is integrated to \QC to - enable you to deploy applications to connected Android devices, to run - them, and to read their logs. It includes a client and server that run on + \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 following video shows the whole process from installing Qt for Android + to debugging an application on an Android device: + + \youtube 5OiIqFTjUZI + \section1 Requirements To use \QC to develop Qt applications for Android, you need - \l{Qt for Android} 5.2, or later, and the tool chain that \QC - can automatically download, install, and configure for you. - For more information, see \l{Manually Installing the Prerequisites}. + \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. \section1 Specifying Android Device Settings @@ -58,42 +59,39 @@ \uicontrol Android on Windows and Linux or \uicontrol {\QC} > \uicontrol Preferences > \uicontrol Devices > \uicontrol Android on \macos. - \image qtcreator-options-android-main.png "Android preferences" + \image qtcreator-options-android-main.png {Android preferences} \li In the \uicontrol {JDK location} field, 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 - \l{OpenJDK} installation. If none is found, you must set the path - manually. If you don't have a supported JDK installed, select + \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 to open the JDK download web page in the default browser. - \note We recommended using a 64-bit JDK because the 32-bit one - might cause issues with \c cmdline-tools, and some packages might - not be listed. + \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 - folder where you want the \l{Android SDK Command-line Tools} to be - installed. + 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 whether the tool chain is installed. - If packages are missing or updates are needed, the SDK Manager - offers to add or remove those packages. Before taking action, it - prompts you to accept the changes it is about to make. In addition, - it prompts you to accept Google licenses, as necessary. - \li The installed NDK versions are listed in - \uicontrol {Android NDK list}. - The locked items were installed by the SDK Manager, - and can only be modified from the \uicontrol {Android SDK Manager} - dialog. For more information, see \l{Managing Android NDK Packages}. + 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 + 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 + 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 warning if it cannot find a suitable Qt version. \li Optionally, in the \uicontrol {Android OpenSSL Settings} group, set the path to the prebuilt OpenSSL libraries. - For Qt applications that require OpenSSL support, \QC allows to + 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}. \li Select \uicontrol {Download OpenSSL} to download the OpenSSL @@ -103,21 +101,20 @@ \section2 Manual Setup - \note We recommend that you use the latest Android SDK Command-Line Tools. - Using Android SDK Tools version 25.2.5 or earlier is not supported because - they cannot be fully integrated with \QC. + \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. However, if the automatic setup does not meet your needs, you can download and install Android SDK Command-line Tools, and then install or update the - NDKs, tools and packages needed for development. For more information, see + necessary NDKs, tools, and packages. For more information, see \l{Getting Started with Qt for Android}. \section2 Viewing Android Tool Chain Settings - The Android SDK Command-Line Tools download URL, the essential - packages list, and the appropriate NDK for each Qt version are defined in a JSON - configuration file. The file is located under the user's \QC - resource folder: + 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. + The file is in the \QC resource folder: \badcode # Linux and macOS @@ -127,8 +124,8 @@ C:\Users\Username\AppData\Local\QtProject\qtcreator\android\sdk_definitions.json \endcode - For example, the SDK configuration file defines the NDK version 19.2.5345600 - to be used for Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1 versions: + 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: \badcode "specific_qt_versions": [ @@ -150,10 +147,10 @@ Linux or \uicontrol {\QC} > \uicontrol Preferences > \uicontrol Devices > \uicontrol Android on \macos. - \image qtcreator-options-android-sdk-tools.png "Android NDK and SDK checks" + \image qtcreator-options-android-sdk-tools.png {Android NDK and SDK checks} - The locked versions were installed by the SDK Manager, and can only - be modified from the \uicontrol {Android SDK Manager} dialog. + The 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}. To manually download NDKs, select \inlineimage icons/online.png @@ -173,7 +170,7 @@ tool, \l {sdkmanager}, for SDK package management. To make SDK management easier, \QC has an SDK Manager for installing, updating, and removing SDK packages. You can still use - sdkmanager for advanced SDK management. + \c sdkmanager for advanced SDK management. To view the installed Android SDK packages, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Devices > \uicontrol Android > @@ -181,7 +178,7 @@ \uicontrol Preferences > \uicontrol Devices > \uicontrol Android > \uicontrol {SDK Manager} on \macos. - \image qtcreator-android-sdk-manager.png "Android SDK Manager" + \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 @@ -194,27 +191,27 @@ \uicontrol {Update Installed}. Select the packages to update, and then select \uicontrol Apply. - To specify advanced sdkmanager settings, select + To specify advanced \c sdkmanager settings, select \uicontrol {Advanced Options} and enter arguments in the - \uicontrol {SDK Manager arguments} field. The available arguments are listed - and described in \uicontrol {Available arguments}. + \uicontrol {SDK Manager arguments} field. \uicontrol {Available arguments} + lists the arguments with descriptions. - \image qtcreator-android-sdk-manager-arguments.png "Android SDK Manager Arguments dialog" + \image qtcreator-android-sdk-manager-arguments.png {Android SDK Manager Arguments dialog} \section1 Managing Android Virtual Devices (AVD) - The available AVDs are listed in \uicontrol Edit > \uicontrol Preferences + To view the available AVDs, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Devices on Windows and Linux or \uicontrol {\QC} > \uicontrol Preferences > \uicontrol Devices > on \macos. You can add more AVDs. - \image qtcreator-android-avd-manager.png "Android device in Devices" + \image qtcreator-android-avd-manager.png {Android device in Devices} You can see the status of the selected device 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 they are automatically started when you + start AVDs separately because \QC starts them when you select them in the \l{Building for Multiple Platforms}{kit selector} to \l{Deploying to Android}{deploy applications} to them. @@ -223,7 +220,7 @@ To specify options for starting an AVD, select \uicontrol {AVD Arguments}. - \image qtcreator-android-avd-arguments.png "Startup options for AVDs" + \image qtcreator-android-avd-arguments.png {Startup options for AVDs} Specify the options in \uicontrol {Emulator command-line startup options}. For available options, see \l{Start the emulator from the command line}. @@ -247,7 +244,7 @@ or \uicontrol {\QC} > \uicontrol Preferences > \uicontrol Devices > \uicontrol Add > \uicontrol {Android Device} on \macos to open the \uicontrol {Create New AVD} dialog. - \image qtcreator-android-create-avd.png "Create New AVD dialog" + \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. \li Select \uicontrol OK to create the AVD. @@ -258,9 +255,9 @@ \section1 Debugging on Android Devices - Debugging is enabled in different ways on different 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 + 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}. @@ -269,7 +266,7 @@ the application for debugging. \note \QC cannot debug applications on Android devices if Android Studio is - running. If the following message is displayed in \l {Application Output}, + running. If the following message appears in \l {Application Output}, close Android Studio and try again: \badcode diff --git a/doc/qtcreator/src/android/deploying-android.qdoc b/doc/qtcreator/src/android/deploying-android.qdoc index 6375140fd8..0e1c2e7fde 100644 --- a/doc/qtcreator/src/android/deploying-android.qdoc +++ b/doc/qtcreator/src/android/deploying-android.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -8,24 +8,25 @@ \title Deploying to Android - On Android, applications are distributed in specially structured types of - ZIP packages called Application Packages (APK) or Android App Bundles (AAB). - APK files can be downloaded to and executed on a device, whereas AAB is - intended to be interpreted by the Google Play store and is used to generate - APK files. + 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 + device. You can upload AAB files to the Google Play store. \l{Qt for Android} has binaries for armv7a, arm64-v8a, x86, and x86-64. To support several different ABIs in your application, build an AAB that - has binaries for each of the ABIs. The Google Play store uses the - AAB to generate optimized APK packages for the devices issuing the download - request and automatically signs them with your publisher key. + has binaries for each of the ABIs. The Google Play store uses the AAB + to generate optimized APK packages for the devices that request download + and automatically signs them with your publisher key. \QC supports the following methods of deployment for Android applications: \list \li As a stand-alone, distributable application package (APK). - \li Since Qt 5.14.0, as an app bundle (AAB), intended for distribution - in the Google Play store. + \li As an app bundle (AAB) for distribution in the Google Play store. + + 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}. \endlist \note Since \QC 4.12, Ministro is not supported. @@ -39,56 +40,27 @@ \section1 Packaging Applications - Because bundling applications as APK packages is not - trivial, Qt 5 has a deployment tool called \c androiddeployqt. - When you deploy an application using a \e {Qt for Android kit}, \QC uses - the \c androiddeployqt tool to create the necessary files and to bundle them - into an APK: - - \list - - \li Java files, which serve as the entry point into your application and - that automatically load Qt and execute the native code in your - application. - - \li AndroidManifest.xml, which has meta-information about your - application. - - \li Other XML files, which specify the dependencies of your application. - - \li Resource files. - - \li Libraries and QML files, which can be included in the project - depending on the deployment method that you select. - - \li Gradle wrappers that are needed to download and use Gradle. - - \li Gradle script that is needed by Java IDEs, such as Android Studio. - It allows the user to extend the Java part without copying our Java - sources. It also allows the IDEs to offer code completion, syntax - highlighting, and so on. - - \endlist - - The Gradle wrappers and scripts are bundled only if you use Gradle to build - the application packages. For more information, see - \l{Connecting Android Devices}. + Because bundling applications as APK packages is not trivial, Qt has the + \l {The androiddeployqt Tool}{androiddeployqt} tool. When you deploy an + application using a \e {Qt for Android kit}, \QC runs the tool to + create the necessary files and to bundle them into an APK. For more + information, see \l{Android Package Templates}. To view the packages that the \c androiddeployqt tool created, select the \uicontrol {Open package location after build} check box. \section2 Specifying Deployment Settings - The available deployment settings are listed in the \uicontrol Method field. + The \uicontrol Method field lists deployment settings. To add deployment methods for a project, select \uicontrol Add. - \image qtcreator-android-deployment-settings.png "Deployment settings" + \image qtcreator-android-deployment-settings.png {Deployment settings} To rename the current deployment method, select \uicontrol Rename. To remove the current deployment method, select \uicontrol Remove. - The packages are deployed on the Android device that you select in the + \QC deploys the packages on the Android device that you select in the \l{Building for Multiple Platforms}{kit selector}. To add devices, select \uicontrol Manage. @@ -107,14 +79,13 @@ \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build > \uicontrol {Build Android APK} > \uicontrol Details. - \image qtcreator-android-build-apk-step.png "Build Android APK step" + \image qtcreator-build-settings-android-apk.webp {Build Android APK step} - The \c androiddeployqt tool uses the configuration information to - create APKs. For more information about the available options, see - \l{androiddeployqt}. + The \c androiddeployqt tool create APKs based on the settings. For more + information about the available options, see \l{androiddeployqt}. You can view information about what the \c androiddeployqt tool is doing in - \l {Compile Output}. To view additional information, select the + \l {Compile Output}. To view more information, select the \uicontrol {Verbose output} check box. Select \uicontrol {Add debug server} to include the debug server binary @@ -122,36 +93,31 @@ \section3 Selecting API Level - In the \uicontrol {Android build platform SDK} field, you can select the - API level to use for building the application. Usually, you should select - the highest API level available. + In the \uicontrol {Android build platform SDK} field, select the + \l{What is API Level?}{API level} to use for building the application. + Usually, you should select the highest API level available. - \note For Qt 5.12.0 to 5.12.5 and Qt 5.13.0 to 5.13.1, Android build - platform SDK 28 should be used. For more recent versions than Qt 5.13.1, - build platform SDK 29 or the most recent one should be used. - - This field does not specify the minimum supported API level nor the target - API level, which you can specify in the Android manifest. See - \l{Editing Manifest Files}. For more information about Android API levels, see - \l{What is API Level?}. + Usually, you should use the highest version of the Android SDK + build-tools for building. If necessary, select another version + in the \uicontrol {Android build-tools version} field. \section3 Building AABs For testing the application locally, use the APK format because - the package can be uploaded directly to the device and run. For - distribution to the Google Play store, create an AAB by selecting + \QC can install and run the package on the device. For distribution + to the Google Play store, create an AAB by selecting the \uicontrol {Build Android App Bundle (*.aab)} check box. When building with CMake, you can view the selected ABIs in \uicontrol {Initial Configuration} in the \uicontrol CMake section. You can set additional ABIs as values of the \c ANDROID_ABI key: - \image qtcreator-android-cmake-settings.png "CMake settings for building AABs" + \image qtcreator-android-cmake-settings.png {CMake settings for building AABs} When building with Qbs or qmake, you can select the ABIs in the \uicontrol ABIs field in the \uicontrol {Build Steps}: - \image qtcreator-android-build-steps.png "qmake settings for building AABs" + \image qtcreator-android-build-steps.png {qmake settings for building AABs} \section3 Signing Android Packages @@ -174,12 +140,12 @@ certificate has information about the algorithm that is used to sign the certificate, as well as the signature of the certificate. - The keystore is protected by a password. In addition, you can protect each + A password protects the keystore. In addition, you can protect each alias with its individual password. When you sign an Android application, you must select a keystore that - has certificates and a certificate alias from the keystore. The public - key (certificate) for the alias is embedded into the APK during signing. + has certificates and a certificate alias from the keystore. The signing + process embeds the public key (certificate) for the alias into the APK. To create a keystore and a self-signed certificate: @@ -250,8 +216,92 @@ You can use the configuration options to specify all the settings you need for the \c androiddeployqt tool. You only need an Android manifest file to specify Android-specific settings, such as the application icon. - However, the manifest file is needed when you want to publish the package - in the Play Store. + However, you need the manifest file to publish the package in the Play Store. + For more information about manifest files, see + \l {Qt Android Manifest File Configuration}. + + If you use CMake as the build system, you must specify the Android package + source directory, \c QT_ANDROID_PACKAGE_SOURCE_DIR, in the CMakeList.txt + file, as instructed in the \l{Locking Device Orientation} + {mobile device tutorial}. + + To use \QC to create an Android manifest file and to open it in the Android + Manifest Editor: + + \list 1 + + \li Select \uicontrol Projects > \uicontrol Build > + \uicontrol {Build Android APK} > \uicontrol {Create Templates}. + + \li Check the path in \uicontrol {Android package source directory}. + + \image qtcreator-android-create-template.png {Create Template dialog} + + \li Select \uicontrol {Copy the Gradle files to Android directory} if you + plan to extend the Java part of your Qt application. + + \li Select \uicontrol Finish to copy the template files to the \c android + directory and to open the manifest file for editing. + + \image qtcreator-android-manifest-editor-package.webp {Package info in Android Manifest Editor} + + \endlist + + The following table summarizes the options you can set. + + \table + \header + \li Option + \li Value + \row + \li \uicontrol {Package name} + \li A valid \l{Package Names}{package name} for the application. + For example, \c {org.example.myapplication}. + An automatically generated Java launcher that is packaged with the + application into an APK launches the application. + \row + \li \uicontrol {Version code} + \li An internal version number for the package that determines whether + one version of the application is more recent than another. + \row + \li \uicontrol {Version name} + \li The version number that is visible to users. + \row + \li \uicontrol {Minimum required SDK} + \li The minimum API level required to run the application if you set it + manually in the manifest file. + \row + \li \uicontrol {Target SDK} + \li The targeted API level of the application if you set it manually in + the manifest file. + \row + \li \uicontrol {Application name} + \li The application's name. + \row + \li \uicontrol {Activity name} + \li An activity name. + \row + \li \uicontrol {Style extraction} + \li The method that Qt uses to determine which \l{Styling}{UI style} + to use. + \row + \li \uicontrol {Screen orientation} + \li How to determine \l{Screen Orientation}{screen orientation}. + \row + \li \uicontrol {Application icon} + \li Images to use as \l{Icons}{application icons} depending on screen + resolution. + \row + \li \uicontrol {Splash screen} + \li Images to display as \l{Splash Screens}{splash screens} depending on + the screen orientation and resolution. + \row + \li \uicontrol Permissions + \li The \l{Setting Permissions}{permissions} that the application needs. + \endtable + + On the top header, select the \uicontrol {XML Source} tab to edit the file + in XML format. \section2 Package Names @@ -378,7 +428,7 @@ \li Locks the orientation to its current rotation, whatever that is. \endtable - \section2 Icons and Splash Screens + \section2 Icons You can set different images to be shown as application icons and splash screens on low, medium, high, and extra high DPI displays. The following @@ -399,16 +449,17 @@ high, and extra high DPI displays, as needed. Alternatively, set the icons for each resolution separately. - \image qtcreator-android-manifest-editor-app-icon.png "Application icons in Android Manifest Editor" + \image qtcreator-android-manifest-editor-app-icon.webp {Application icons in Android Manifest Editor} + + \section2 Splash Screens Specify settings for splash screens in the \uicontrol {Splash screen} tab. Select images to display as splash screens depending on the device orientation and screen resolution. - \image qtcreator-android-manifest-editor-splash-screen.png "Splash screens in Android Manifest Editor" + \image qtcreator-android-manifest-editor-splash-screen.webp {Splash screens in Android Manifest Editor} - By default, the splash screen is hidden automatically - when an activity is drawn. To keep it visible until + By default, drawing an activity hides the splash screen. To keep it visible until \l{https://doc.qt.io/qt-6/qnativeinterface-qandroidapplication.html#hideSplashScreen} {QNativeInterface::QAndroidApplication::hideSplashScreen()} is called, select the \uicontrol {Sticky splash screen} check box. @@ -424,102 +475,22 @@ Select \uicontrol {Clear All} to reset all settings or remove all images. - \section2 Android Manifest Editor - - If you use qmake as the build system, you can create an Android manifest - file and edit it in \QC. - - To create an Android manifest file and to open it in the Android Manifest - Editor: - - \list 1 - - \li Select \uicontrol Projects > \uicontrol Build > - \uicontrol {Build Android APK} > \uicontrol {Create Templates}. - - \li Check the path in \uicontrol {Android package source directory}. - - \image qtcreator-android-create-template.png "Create Template dialog" - - \li Select \uicontrol {Copy the Gradle files to Android directory} if you - plan to extend the Java part of your Qt application. - - \li Select \uicontrol Finish to copy the template files to the \c android - directory and to open the manifest file for editing. - - \li In the \uicontrol {Package name} field, enter a valid - \l{Package Names}{package name} for the application. - For example, \c {org.example.myapplication}. - The application is launched by an automatically generated Java launcher - that is packaged with the application into an Android package (.apk). - - \image qtcreator-android-manifest-editor-package.png "Package info in Android Manifest Editor" - - \li You can specify an internal version number for the package in the - \uicontrol {Version code} field. It is used to determine whether one version of - the application is more recent than another. In the \uicontrol {Version name} - field, specify the version number that is shown to users. - - \li In the \uicontrol {Minimum required SDK} field, select the minimum API level - required to run the application. The minimum supported API level for \QC is - android-9. However, Qt versions might have different minimum API levels, and - therefore \QC does not allow you to select an API level that the Qt version - specified for the kit does not support. - - \li In the \uicontrol {Target SDK} field, select the targeted API level of the - application. This affects the activation of some compatibility features in - the OS. The value used by the \c androiddeployqt tool by default is 14, which - means that the overflow button in the system navigation bar will not be - enabled by default. - - \li In the \uicontrol {Application name} field, set the application's name. - - \li In the \uicontrol {Activity name} field, set an activity name. - - \li In the \uicontrol {Style extraction} field, set the method that Qt - uses to \l{Styling}{determine which UI style to use}. - - \li In the \uicontrol {Screen orientation} field, select the option for - determining \l{Screen Orientation}{screen orientation}. - - \li In \uicontrol {Application icon}, specify images to use as application - icons depending on screen resolution. + \section2 Setting Permissions - \li In \uicontrol {Splash screen}, select images to display as splash - screens depending on the screen orientation and resolution. - - \li In \uicontrol {Android services}, select \uicontrol Add to add a service. - You must enter at least a service class name for a new service. If you select - \uicontrol {Run in external process}, you also need to enter a process name. - If you select \uicontrol {Run in external library}, you need to enter a library name. - Service arguments are mandatory for a service that is not run in an external - library. For more information about writing service code and structure of services, - see \l{Android Services}. - - \image qtcreator-android-manifest-editor-services.png "Android services in Android Manifest Editor" - - \li In the \uicontrol Permissions field, you can specify the permissions that your - application needs. Starting from Android 6.0 (API 23), permissions have to be - requested at runtime (see \l{QtAndroidPrivate::requestPermission()}). For - lower Android API levels, users are asked to grant the permissions when they + Starting from Android 6.0 (API 23), applications have to request permissions + at runtime (see \l{QtAndroidPrivate::requestPermission()}). For + lower Android API levels, users have to grant the permissions when they install the application. Android OS then grants the application access to the appropriate data and features. - \image qtcreator-android-manifest-editor-permissions.png "Permissions in Android Manifest Editor" + \image qtcreator-android-manifest-editor-permissions.webp {Permissions in Android Manifest Editor} - \li Select the \uicontrol {Include default permissions for Qt modules} and + Select the \uicontrol {Include default permissions for Qt modules} and \uicontrol {Include default features for Qt modules} check boxes to add the permissions needed by Qt libraries. This can be \c {android.permission.WRITE_EXTERNAL_STORAGE} for \l{Qt Core} or - \c {android.permission.ACCESS_COARSE_LOCATION} for - \l{https://doc.qt.io/qt-5.15/qtlocation-index.html}{Qt Location}. - - \li To add a permission, select it from the list, and then click \uicontrol Add. - - \endlist - - On the top header, select the \uicontrol {XML Source} tab to edit the file - in XML format. + \c {android.permission.ACCESS_BACKGROUND_LOCATION} for \l{Qt Positioning}. + To add a permission, select it from the list, and then click \uicontrol Add. */ diff --git a/doc/qtcreator/src/debugger/creator-debug-views.qdoc b/doc/qtcreator/src/debugger/creator-debug-views.qdoc index d0aa7b86da..78ee139e3f 100644 --- a/doc/qtcreator/src/debugger/creator-debug-views.qdoc +++ b/doc/qtcreator/src/debugger/creator-debug-views.qdoc @@ -12,7 +12,7 @@ \title Viewing Call Stack Trace - When the program being debugged is interrupted, \QC displays the nested + 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 particular function. For each function, \QC tries to retrieve the file name @@ -24,14 +24,17 @@ Since the call stack leading to the current position may originate or go through code for which no debug information is available, not all stack frames have corresponding source locations. Stack frames without - corresponding source locations are grayed out in the \uicontrol Stack view. + corresponding source locations are grayed out. If you click a frame with a known source location, the text editor jumps to - the corresponding location and updates the \uicontrol {Locals} and - \uicontrol {Expressions} views, making it seem like the program - was interrupted before entering the function. + the corresponding location and updates the + \l {Local Variables and Function Parameters}{Locals} and + \l {Evaluating Expressions}{Expressions} views, making it seem like the + application was interrupted before entering the function. - To find out which QML file is causing a Qt Quick 2 application to crash, + \section1 Loading QML Stack + + To find out which QML file is causing a Qt Quick application to crash, select \uicontrol {Load QML Stack} in the context menu in the \uicontrol Stack view. The debugger tries to retrieve the JavaScript stack from the stopped executable and prepends the frames to the C++ frames, @@ -66,8 +69,8 @@ \li Executing some system calls - \li Changes in a block of memory at a particular address when a - program is running + \li Changes in a block of memory at a particular address when an + application is running \li Emitting QML signals @@ -75,26 +78,30 @@ \endlist - The interruption of a program by a breakpoint can be restricted with certain - conditions. + A breakpoint interrupts the application every time the application reaches + its location unless you specify a boolean condition for it. The breakpoint + evaluates the expression each time the application passes it, and the + application stops only if the condition evaluates to \c true. + + \section1 Unclaimed and Claimed Breakpoints Breakpoints come in two varieties: \c unclaimed and \c claimed. An unclaimed breakpoint represents a task to interrupt the debugged - program and passes the control to you later. It has two states: + application and passes the control to you later. It has two states: \c pending and \c implanted. Unclaimed breakpoints are stored as a part of a session and exist - independently of whether a program is being debugged or not. They + independently of whether an application is being debugged or not. They are listed in the \uicontrol {Breakpoint Preset} view and in the editor using the \inlineimage icons/qtcreator-unclaimed-breakpoint-icon.png (\uicontrol {Unclaimed Breakpoint}) icon, when they refer to a position in code. - \image qtcreator-debugger-breakpoint-preset.png {Breakpoint Preset view} + \image qtcreator-debugger-breakpoint-preset.webp {Breakpoint Preset view} When a debugger starts, the debugging backend identifies breakpoints from the set of unclaimed breakpoints that might be handled by the - debugged program and claims them for its own exclusive use. Claimed + debugged application and claims them for its own exclusive use. Claimed breakpoints are listed in the \uicontrol {Breakpoints} view of the running debugger. This view only exists while the debugger is running. @@ -115,11 +122,11 @@ \uicontrol{Breakpoint Preset} view. When an implanted breakpoint is hit during the execution of the - debugged program, control is passed back to you. - You can then examine the state of the interrupted program, or + debugged application, control is passed back to you. + You can then examine the state of the interrupted application, or continue execution either line-by-line or continuously. - \image qtcreator-debug-breakpoints.png "Breakpoints view" + \image qtcreator-debug-breakpoints.webp {Breakpoints view} \section1 Adding Breakpoints @@ -133,7 +140,7 @@ \li In the code editor, click the left margin or press \key F9 (\key F8 on \macos) on a particular line you want the - program to stop. + application to stop. \li In the \uicontrol {Breakpoint Preset} view or the \uicontrol Breakpoints view: @@ -146,24 +153,68 @@ \endlist \li In the \uicontrol {Breakpoint type} field, select the location in the - program code where you want the program to stop. The other options - to specify depend on the selected location. - - \image qtcreator-add-breakpoint.png "Add Breakpoints" dialog - - \li In the \uicontrol Condition field, set the condition to be evaluated - before stopping at the breakpoint if the condition evaluates as - true. - - \li In the \uicontrol Ignore field, specify the number of times that the - breakpoint is ignored before the program stops. - - \li In the \uicontrol Commands field, specify the commands to execute - when the program stops; one command on a line. GDB executes the - commands in the order in which they are specified. + 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 + inoperative as if you had deleted it, but keep the information about the + breakpoint, so that you can enable it again later. + + The other options to specify depend on the location you select, such as file + name and line number, address, expression, or function name. The following + table summarizes the advanced options. + + \table + \header + \li Option + \li Value + \row + \li \uicontrol Condition + \li The condition to evaluate before stopping at the breakpoint if the + condition evaluates as \c true. + \row + \li \uicontrol {Ignore count} + \li The number of times to ignore the breakpoint before the application + stops. + \row + \li \uicontrol {Thread specification} + \li + \row + \li \uicontrol Path + \li Determines how to specify the path when setting breakpoints: + \list + \li \uicontrol {Use Engine Default} is the preferred setting of + the debugger engine. + \li \uicontrol {Use Full Path} passes the full path to avoid + ambiguity if several modules contain files with the same + name. This is the engine default for CDB and LLDB. + \li \uicontrol {Use File Name} passes the file name only. This is + useful when the location of the source tree does not match + the one used when building the modules. This is the engine + default for GDB as using full paths can be slow with it. + \endlist + \row + \li \uicontrol Module + \li Specify the module (base name of the library or executable) for + function or file type breakpoints to speed up debugger startup + (CDB, LLDB). + \row + \li \uicontrol Commands + \li Commands to execute when the application stops. List one command per + line. GDB executes the commands in the order in which you specify + them. + \row + \li \uicontrol {Tracepoint only} + \li A \e tracepoint lets you log information about the application + without adding log statements or otherwise modifying your code. + You can set conditions for the tracepoint. + \row + \li \uicontrol Message + \li The tracepoint message to show in \l {Application Output}. + \endtable + \if defined(qtcreator) \section1 Specifying Breakpoint Settings @@ -171,6 +222,8 @@ \uicontrol 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. @@ -261,12 +314,12 @@ disabled breakpoint. To re-enable a breakpoint, use any of the above methods. - With the notable exception of data breakpoints, breakpoints retain their - enabled or disabled state when the debugged program is restarted. + Other than data breakpoints retain their enabled or disabled state when the + debugged application is restarted. \section1 Setting Data Breakpoints - A \e {data breakpoint} stops the program when data is read or written at the + A \e {data breakpoint} stops the application when data is read or written at the specified address. To set a data breakpoint at an address: @@ -291,8 +344,8 @@ \uicontrol {Add Data Breakpoint at Object's Address} in the context menu to set the data breakpoint. - Data breakpoints will be disabled when the debugged program exits, as it - is unlikely that the used addresses will stay the same at the next program + Data breakpoints will be disabled when the debugged application exits, as it + is unlikely that the used addresses will stay the same at the next application launch. If you really want a data breakpoint to be active again, re-enable it manually. */ @@ -313,7 +366,7 @@ \image qtcreator-locals.png {Locals view} - Whenever a program stops under the control of the debugger, it retrieves + Whenever an application stops under the control of the debugger, it retrieves information about the topmost stack frame and displays it in the \uicontrol {Locals} view. The \uicontrol Locals pane shows information about parameters of the function in that frame as well as the @@ -321,6 +374,35 @@ function after pressing \key {Shift+F11}, the \uicontrol {Return Value} pane displays the value returned by the function. + You can expand the view contents to check that your application sets a + local value correctly. + + \if defined(qtcreator) + \section1 Locals View Actions + + Right-click the \uicontrol Locals view to select the following actions: + + //! [0] + \list + \li Add and remove expression evaluators + \li 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 Show tooltips in the \uicontrol Locals 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} + \endlist + //! [0] + \endif + + \section1 Selecting Object Type for Display + When using GDB, you can specify whether the dynamic or the static type of objects will be displayed. Select \uicontrol {Use dynamic object type for display} in the context menu. Keep in mind that choosing the dynamic type @@ -339,45 +421,88 @@ \title Evaluating Expressions To compute values of arithmetic expressions or function calls, use - expression evaluators in the \uicontrol Expressions view. To insert a new - expression evaluator, either double-click on an empty part of the - \uicontrol {Expressions} or \uicontrol {Locals} view, or select - \uicontrol {Add New Expression Evaluator} from the context menu, or drag and - drop an expression from the code editor. + expression evaluators in the \uicontrol Expressions view. + + You can examine static variables that the debuggers don't pick up as + \e {local variables}. For example, if you define + \c {static int staticVar = 42;} in a source file and then add \c staticVar + as an evaluated expression, you should see \e 42 in the view when the + debugger stops in the source file. - \image qtcreator-debugger-expressions.png {Expressions view} + \image qtcreator-debugger-expressions.webp {Expressions view} + + \section1 Adding Expression Evaluators + + To add expression evaluators, drag an expression from the code editor + to the \uicontrol Expressions view. + + You can also: + + \list + \li Double-click in the \uicontrol {Expressions} or + \l {Local Variables and Function Parameters}{Locals} view. + \li Select \uicontrol {Add New Expression Evaluator} from the context + menu. + \endlist + + Enter the expression in the \uicontrol {New Evaluated Expression} dialog: + + \image qtcreator-debugger-new-evaluated-expression.webp {New Evaluated Expression dialog} + + \omit + ## Visible in the context menu, but does not currently work. + + To insert widgets into expression evaluators, select a + widget in the debugged application and then select + \uicontrol {Select Widget to Add into Expression Evaluator} + in the context menu. + \endomit + + The set of evaluated expressions is saved in your session. \note Expression evaluators are powerful, but slow down debugger operation - significantly. It is advisable to not use them excessively, and to remove - unneeded expression evaluators as soon as possible. + significantly. Use them sparingly and remove them when you no longer need + them. Expression evaluators are re-evaluated whenever the current frame changes. - Note that functions used in the expressions are called each time, even if + The functions used in the expressions are called each time, even if they have side-effects. + \if defined(qtcreator) + \section1 Expressions View Actions + + Right-click the \uicontrol Expressions view to select the following actions: + + \include creator-debug-views.qdoc 0 + \endif + + \section1 JavaScript Expressions + The QML debugger can evaluate JavaScript expressions. \if defined(qtcreator) + + \section1 C and C++ Expressions + GDB, LLDB and CDB support the evaluation of simple C and C++ expressions. Functions can be called only if they are actually compiled into the debugged - executable or a library used by the executable. Most notably, inlined + executable or a library used by the executable. Inlined functions such as most \c{operator[]} implementations of standard containers are typically \e{not} available. - When using GDB or LLDB as backend, a special ranged syntax can be used to + When using GDB or LLDB as backend, you can use a special ranged syntax to display multiple values with one expression. A sub-expression of form \c{foo[a..b]} is split into a sequence of individually evaluated expressions \c{foo[a], ..., foo[b]}. - Compound variables of struct or class type are displayed as expandable in - the view. Expand entries to show all members. Together with the display of - value and type, you can examine and traverse the low-level layout of object - data. + You can expand compound variables of struct or class type to show their + members. As you also see the variable value and type, you can examine and + traverse the low-level layout of object data. GDB and LLDB, and therefore \QC's debugger, also work for optimized builds on Linux and \macos. Optimization can lead to re-ordering of instructions or removal of some local variables, causing the - \uicontrol {Locals} and \uicontrol {Expressions} view to show + \uicontrol {Locals} and \uicontrol {Expressions} views to show unexpected data. The debug information from GCC does not include enough @@ -388,8 +513,6 @@ \uicontrol {not in scope}. Not all uninitialized objects, however, can be recognized as such. - \note The set of evaluated expressions is saved in your session. - \section1 Inspecting Basic Qt Objects The most powerful feature of the debugger is that the \uicontrol {Locals} @@ -416,7 +539,7 @@ 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, - \c QString and \c std::string when the program is interrupted. To do so, + \c QString and \c std::string when the application is interrupted. To do so, click the \uicontrol Value column, modify the value with the inplace editor, and press \key Enter (or \key Return). 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 b97be123a3..ab0aff0f54 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc @@ -18,12 +18,12 @@ \l{Specifying Breakpoint Settings}{specify settings for breakpoints}, and map source paths to target paths. - You can view debug output in the \uicontrol {Debugger Log} view. + You can view debug output in the \l {Debugger Log} view. However, in some Linux distributions, such as Arch Linux, debug output is sent to the system log. To override this behavior, select the \uicontrol {Force logging to console} check box. This sets \c QT_LOGGING_TO_CONSOLE=1 in the environment of the debugged - program, which effectively prevents storing debug output in + application, which effectively prevents storing debug output in system logs. \section1 Mapping Source Paths @@ -96,7 +96,7 @@ future, select the \uicontrol {Use automatic symbol cache} check box. To execute GDB commands after GDB has been started, but before the debugged - program is started or attached, and before the debugging helpers are + application is started or attached, and before the debugging helpers are initialized, enter them in the \uicontrol {Additional Startup Commands} field. 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 ca68d35d37..d457abc4f9 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2021 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -15,48 +15,57 @@ \title Setting Up Debugger - The main debugger settings are associated with the - \l{glossary-buildandrun-kit}{kit} you build and run your project with. To + The main debugger preferences are associated with the + \l{Adding Kits}{kit} you build and run your project with. To specify the debugger and compiler to use for each kit, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Kits. + \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 (as is usually the case for the CDB debugger - on Windows, which you always must install yourself) or because the installed - version is not supported. For example, when your system does not have GDB + 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. - \note If you need to change the debugger to use for an automatically - detected \l{glossary-buildandrun-kit}{kit}, you can \uicontrol Clone the - kit and change the parameters in the clone. Make sure to select the cloned - kit for your project. + To change the debugger in an automatically detected kit, select + \uicontrol Edit > \uicontrol 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 \uicontrol Edit > \uicontrol Preferences > \uicontrol Kits > \uicontrol Debuggers > \uicontrol Add to add it. - \note To use the debugging tools for Windows, you must install them and add - the Microsoft Symbol Server to the symbol search path of the - debugger. For more information, see \l{Setting CDB Paths on Windows}. + \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}. - \note To use the Free Software Foundation (FSF) version of GDB on \macos, you - must sign it and modify your \l{glossary-buildandrun-kit}{kit} settings. + 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++ code and - installing the supported native debuggers. It also - applies for code in other compiled languages such as C, FORTRAN, Ada. + 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 on the debugger modes, see - \l{Launching the Debugger in Different Modes}. + For more information about launching the debugger in different modes, see + \l{Debugger Operating Modes}. \section1 Supported Native Debugger Versions - \QC supports native debuggers when working with compiled code. On - most supported platforms, the GNU Symbolic Debugger GDB can be used. On - Microsoft Windows, when using the Microsoft tool chain, the Microsoft - Console Debugger CDB is needed. On \macos and Linux, the LLDB debugger - can be used. + \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 + 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. + + \note You need a debugger version built with Python scripting support. The following table summarizes the support for debugging C++ code: @@ -89,28 +98,26 @@ \section2 Supported GDB Versions - Starting with version 3.1, \QC requires the Python scripting extension. GDB - builds without Python scripting are not supported anymore and will not work. - The minimum supported version is GDB 7.5 using Python version 2.7, or 3.3, - or newer. + Use GDB 7.5, or later, with the Python scripting extension and Python version + 3.3, or later. 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 - All versions of CDB targeting platforms supported by Qt are supported by - \QC. + \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 supporting C++ on the desktop. + 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. + 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. @@ -182,22 +189,15 @@ the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}. - \section3 Symbol Server - - We highly recommend that you add the Microsoft Symbol Server to the - symbol search path of the debugger. The Symbol Server has debugging - information for the operating system libraries for debugging Windows - applications. For more information, see \l{Setting CDB Paths on Windows}. - \section2 Debugging Tools for \macos The Qt binary distribution has both debug and release - variants of the libraries. But you have to explicitly tell the + 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 library. - If you use a qmake based project in \QC, you can set a flag in + If you use a qmake based project in \QC, you can set a flag in your \l{glossary-run-config}{run configuration}, in \uicontrol Projects mode. In the run configuration, select \uicontrol{Use debug version of frameworks}. @@ -210,6 +210,27 @@ We recommend using the LLDB version that is delivered with the latest Xcode. + \section2 PDB + + \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 Widget-Based Qt for Python Applications}{.pyproject} + configuration file. + + You must 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 @@ -264,7 +285,7 @@ (\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for \c $HOME). - \li To use the debugger, add the kit in the \uicontrol {Build Settings} + \li To use the debugger, enable the kit in the \uicontrol {Build Settings} of the project. \endlist diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc index 17d03346c3..a5e49e3749 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc @@ -35,7 +35,7 @@ low level virtual machine (LLVM) project, LLDB. \li Debug QML and Java code and Qt Quick applications - QML/JavaScript debugger. - \li Debug Python source code - \c pdb. + \li Debug Python source code - PDB. \endlist The following sections describe how to set up, launch, and interact with the @@ -130,44 +130,47 @@ debugger, select the \inlineimage icons/qtcreator-debug-button.png (\uicontrol {Start Debugging of Startup Project}) button or press \key F5. - \QC checks whether the compiled program is up-to-date, and rebuilds and + \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 he \uicontrol {Always deploy before running} check box in \uicontrol Edit > \uicontrol Preferences > \uicontrol {Build & Run} > - \uicontrol General. To debug the program without deploying + \uicontrol General. To debug the application without deploying it, select \uicontrol Debug > \uicontrol {Start Debugging} > \uicontrol {Start Debugging Without Deployment}. - The debugger then takes over and starts the program with suitable + The debugger then takes over and starts the application with suitable parameters. When using GDB or CDB as debug backend, you can specify additional commands - to execute before and after the backend and debugged program are started or + to execute before and after the backend and debugged application are started or attached in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > \uicontrol GDB and \uicontrol CDB. For more information, see \l{Debugger Preferences}. - To allow reading the user's default .gdbinit file on debugger startup, + 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}. - \note Starting a C++ program in the debugger can take a long time, typically - in the range of several seconds to minutes if complex features are used. + \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 Launching the Debugger in Different Modes + For \l {Creating Widget-Based Qt for Python Applications}{Python} projects, + start debugging the \c main.py file. If you encounter problems, check the + active build target in the \l{Building for Multiple Platforms}{kit selector}. + + \section1 Debugger Operating Modes The debugger plugin can run the native debuggers in various operating modes - depending on where and how the debugged process is started and run. Some of + 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 are set up in a - way to start the operating mode that is commonly used in a given context. So - if the current project is set up as a C++ application using the \MinGW - toolchain targeting desktop Windows, the GDB engine will be started in Start - Internal mode. If the current project is a QML application using C++ - plugins, a "mixed" QML/C++ engine will be started, with the C++ parts being + 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 @@ -179,24 +182,24 @@ \list - \li \b{Start Internal} to debug applications developed inside \QC such as - a Qt based GUI application. + \li \e{Start internal} to debug applications developed inside \QC, such as + a Qt Widgets-based application. - \li \b{Start External} to start and debug processes without a proper \QC + \li \e{Start external} to start and debug processes without a proper \QC project setup, either locally or on a remote machine. - \li \b{Attach} to debug processes already started and running outside + \li \e{Attach} to debug processes already started and running outside \QC, either locally or on a remote machine. - \li \b{Core} to debug crashed processes on Unix. + \li \e{Core} to debug crashed processes on Unix. - \li \b{Post-mortem} to debug crashed processes on Windows. + \li \e{Post-mortem} to debug crashed processes on Windows. \endlist - \section2 Launching in Start Internal Mode + \section2 Start Internal - Start Internal mode is the default start mode for most projects, including + Start internal mode is the default start mode for most projects, including all projects using a desktop Qt version and plain C++ projects. If you need a console window to operate your application, for example @@ -211,19 +214,19 @@ 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 + To launch the debugger in start internal mode, click the \uicontrol {Start Debugging} button for the active project. You can specify breakpoints before or after launching the debugger. For more information, see \l{Setting Breakpoints}. - \section2 Launching in Start External Mode + \section2 Start External - You can debug any executable already present on your local or on a remote + 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 identifies the device to debug the application on. - While this mode does not strictly require a project to be opened in \QC, + 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. To start and debug an external application: @@ -261,7 +264,7 @@ configuration to use. \endlist - \section2 Launching in Attach Mode + \section2 Attach You can attach the debugger to applications that are already running or instruct the debugger to attach to an application when it starts. @@ -285,7 +288,7 @@ To terminate the selected process, select \uicontrol {Kill Process}. - While this mode does not strictly require a project to be opened in \QC, + 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. You can specify breakpoints before or after attaching the debugger to the @@ -312,14 +315,14 @@ process to start. \endlist - \section2 Launching in Core Mode + \section2 Core - The Core mode is used to inspect \e {core} files (crash dumps) that are + 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 set up to allow this. To enable the dumping of core files on a Unix system, enter the following - command in the shell from which the application will be launched: + command in the shell from which the application is launched: \code ulimit -c unlimited @@ -350,12 +353,12 @@ the \c sysroot to use instead of the default \c sysroot. \endlist - Also in this mode, using a properly configured project that has the - sources of the crashed program is not strictly necessary, but helpful. + Even though using a properly configured project that has the sources of the + crashed application is not strictly necessary, it is helpful. - \section2 Launching in Post-Mortem Mode + \section2 Post-Mortem - The post-mortem mode is available only on Windows, if you have installed the + The post-mortem 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 @@ -365,7 +368,7 @@ You can launch the debugger in the post-mortem mode if an application crashes on Windows. Click the \uicontrol {Debug in \QC} button in the error - message that is displayed by the Windows operating system. + message from the Windows operating system. */ /*! @@ -552,43 +555,35 @@ \title Debug Mode Views In the \uicontrol Debug mode, you can inspect the state of your - application while debugging. You can interact with the debugger - in many ways, including the following: + application while debugging. - \list + \image qtcreator-debugger-views.webp {Debug mode views while debugging} + + You can interact with the debugger in many ways: - \li Go through a program line-by-line or instruction-by-instruction. + \list - \li Interrupt running programs. + \li Interrupt running applications. \li Set breakpoints. + \li Step through an application line-by-line or + instruction-by-instruction. + \li Examine the contents of the call stack. \li Examine and modify contents of local and global variables. \li Examine and modify registers and memory contents of - the debugged program. + the debugged application. \li Examine the list of loaded shared libraries. \li Disassemble sections of code. \endlist - \QC displays the raw information from the native debuggers in a clear - and concise manner with the goal to simplify the debugging process as much - as possible without losing the power of the native debuggers. - - In addition to the generic IDE functionality of the stack view, views - for locals and expressions, registers, and so on, \QC includes features to - make debugging Qt-based applications easy. The debugger plugin understands - the internal layout of several Qt classes, for example, QString, the Qt - containers, and most importantly QObject (and classes derived from it), as - well as most containers of the C++ Standard Library and some GCC extensions. - It uses this deeper understanding to present objects of such classes in a - useful way. - - Interact with the program you are debugging in the following views. + The following table summarizes the \uicontrol Debug mode views with links to + more information. \table \header @@ -597,12 +592,14 @@ \li Learn More \row \li Stack - \li Examine the the nested function calls leading to the current position + \li Examine the nested function calls leading to the current position as a call stack trace. \li \l {Viewing Call Stack Trace} \row - \li Breakpoints - \li Set \e {breakpoints} with conditions make the application stop in + \li Breakpoint Preset + + Breakpoints + \li Set \e {breakpoints} with conditions to make the application stop in a controlled way. A \e {watchpoint} stops the application when the value of an expression changes. \li \l {Setting Breakpoints} @@ -635,9 +632,11 @@ \row \li Peripheral Registers \li View the current state of peripheral registers. - \li + \li \l {Peripheral Registers} \row - \li Debugger Log + \li Global Debugger Log + + Debugger Log \li View debug output to find out why the debugger does not work. The log view acts as a console, so you can send the contents @@ -645,7 +644,7 @@ native debugger. \li \l{Troubleshooting Debugger} - \l {Directly Interacting with Native Debuggers} + \l {Debugger Log} \row \li Disassembler \li View disassembled code for the current function. @@ -656,19 +655,22 @@ \li \l {Working in Edit Mode} \endtable + \note The \uicontrol Views menu shows some views only while you are + debugging. + \section1 Managing Debug Views - The availability of views depends on whether - you are debugging C++ or QML. Frequently used views are shown by - default and rarely used ones are hidden. To change the default settings, - select \uicontrol View > \uicontrol Views, and then select views to - display or hide. Alternatively, you can enable or disable views from the - context menu of the title bar of any visible debug mode view. + When you are not debugging, the \uicontrol Debug mode shows the + \uicontrol {Debugger Preset} perspective: + + \image qtcreator-debugger-views-initial.webp {Initial Debug mode views} - \image qtcreator-debugger-views.png {Debug mode views} + 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. - You can drag and drop the views in \QC to new positions on the screen. The - size and position of views are saved for future sessions. Select + 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 \uicontrol View > \uicontrol Views > \uicontrol {Reset to Default Layout} to reset the views to their original sizes and positions. @@ -680,13 +682,18 @@ \section1 Customizing Debug Views - You can change the appearance and behavior of the debug views by specifying - settings in \uicontrol Preferences > \uicontrol Debugger. For example, you can: + To change the appearance and behavior of the debug views, set preferences + in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > + \uicontrol General. + + \image qtcreator-debugger-general-options.png {General tab in Debugger preferences} + + For example, you can: \list \li Use alternating row colors in debug views. \li Adopt font size changes from the main editor. - \li Have tooltips displayed in the main editor while you are debugging. + \li Show tooltips in the main editor while you are debugging. \li Close temporary source and memory views and switch to the previously used \QC mode when the debugger exits. \li Bring \QC to the foreground when the debugged application is @@ -703,17 +710,19 @@ \title Stopping Applications - Once the program starts running under the control of the debugger, it - behaves and performs as usual. You can interrupt a running C++ program by - selecting \uicontrol Debug > \uicontrol Interrupt. The program is - automatically interrupted when a breakpoint is hit. + 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 program stops, \QC: + Once the application stops, \QC: \list \li Retrieves data representing the \l{Viewing Call Stack Trace} - {call stack} at the program's current position. + {call stack} at the application's current position. \li Retrieves the contents of \l{Local Variables and Function Parameters} {local variables}. @@ -725,6 +734,8 @@ {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. */ /*! @@ -753,7 +764,7 @@ \li To leave the current function or subfunction, press \key {Shift+F11} (\key {Command+Shift+T} on \macos). - \li To continue running the program, press \key F5. + \li To continue running the application, press \key F5. \li To run to the line that has the cursor, press \key {Ctrl+F10} (\key {Shift+F8} on \macos). @@ -763,7 +774,7 @@ \endlist - You can continue executing the program until the current + You can continue executing the application until the current function completes or jump to an arbitrary position in the current function. \section1 Stepping Into Code @@ -849,15 +860,15 @@ \omit \section2 Creating Snapshots - A snapshot has the complete state of the debugged program at a time, + A snapshot has the complete state of the debugged application at a time, including the full memory contents. - To create snapshots of a debugged program, select \uicontrol {Create Snapshot} + To create snapshots of a debugged application, select \uicontrol {Create Snapshot} in the context menu in the \uicontrol {Debugger Perspectives} view. Double-click on entries in the \uicontrol {Debugger Perspectives} view to switch between snapshots. The debug mode views are updated to reflect the state - of the program at time of taking the snapshot. + of the application at time of taking the snapshot. \note Creating snapshots involves creating core files of the debugged process, requiring significant amount of disk space. For details, see @@ -873,10 +884,24 @@ \title Viewing Threads - If a multi-threaded program is interrupted, the \uicontrol Threads view or - the combobox named \uicontrol Threads in the debugger status bar can be used - to switch from one thread to another. The \uicontrol Stack view adjusts - itself accordingly. + 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, + and possibly private memory. + + When a multi-threaded application is interrupted, you can view the threads + currently active in the application and switch between them in the + \uicontrol Threads view (1): + + \image qtcreator-debugger-threads.webp {Threads view} + + You can also select a thread in the \uicontrol Threads field (2) on the + debugger toolbar. + + This allows you to select the thread that is in the focus of the debugger. + + The \l {Viewing Call Stack Trace}{Stack} view adjusts its contents + accordingly. */ /*! @@ -887,38 +912,59 @@ \title Viewing Modules The \uicontrol Modules view displays information that the debugger plugin - has about modules included in the application that is being debugged. A - module is a dynamic link library (\c {.dll}) in Windows, a shared object - (\c {.so}) in Linux, and a dynamic shared library (\c {.dylib}) in \macos. + has about modules included in the application that is being debugged. + + A module is: + + \list + \li A dynamic link library (\c {.dll}) in Windows + \li A shared object (\c {.so}) in Linux + \li A dynamic shared library (\c {.dylib}) in \macos + \endlist + + \image qtcreator-debugger-modules.webp {Modules view} In addition, the view displays symbols within the modules and indicates - where each module was loaded. + where each module was loaded. Right-click column headers to show and + hide columns in the view. - Right-click the view to open a context menu that has menu items for: + Right-click the view to select the following actions: \list - \li Updating the module list + \li Update the module list + + \li Show source files for a module + + \li Show dependencies between modules (Windows only) - \li Loading symbols for modules + \li Load symbols for modules - \li Examining modules + \li Examine modules - \li Editing module files + \li Edit module files - \li Showing symbols in modules + \li Show symbols in modules - \li Showing dependencies between modules (Windows only) + \li Show sections in modules + + \li Set \l{Debugger Preferences}{debugger preferences} \endlist - By default, the \uicontrol Modules view is hidden. + By default, the \uicontrol Modules view is hidden. To show it, select it in + \uicontrol Views on the debugger toolbar. + + \section1 Breaking on Loading Modules in CDB 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 \uicontrol Edit > \uicontrol Preferences > - \uicontrol Debugger > \uicontrol CDB. For more information, see - \l{Specifying CDB Settings}. + \uicontrol Debugger > \uicontrol CDB. + + \image qtcreator-cdb-options.png {CDB tab in Debugger preferences} + + For more information, see \l{Specifying CDB Settings}. */ /*! @@ -933,56 +979,170 @@ the source file is actually part of the project, or whether it was compiled elsewhere. The view shows the path to each file in the file system. - Right-click the view to open a context menu that has menu items for - reloading data and opening files. + \image qtcreator-debugger-source-files.webp {Source Files view} + + Right-click the view to select the following actions: + + \list + \li Reload data + \li Open the selected file + \li Set \l{Debugger Preferences}{debugger preferences} + \endlist + + By default, the \uicontrol {Source Files} view is hidden. To show it, select + it in \uicontrol Views on the debugger toolbar. + + \section1 External Sources 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. For more information, see \l{Mapping Source Paths}. + paths in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > + \uicontrol General: + + \image qtcreator-debugger-general-options.png {General tab in Debugger preferences} - By default, the \uicontrol {Source Files} view is hidden. + For more information, see \l{Mapping Source Paths}. */ /*! \page creator-registers-view.html \previouspage creator-expressions-view.html - \nextpage creator-debugger-log-view.html + \nextpage creator-peripheral-registers-view.html \title Viewing and Editing Register State - The \uicontrol Registers view displays the current state of the CPU registers. - Depending on the CPU type, there will be different registers available. The - values of registers that recently have changed are highlighted in red and empty - register values as well as leading zeroes are grayed out. + \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. + + The \uicontrol Registers view displays the current state of general-purpose + and special-purpose CPU registers. The available registers depend on the CPU + type. + + \image qtcreator-debugger-registers-view.webp {Registers view} - In addition it is possible to edit the content of registers while the program is - stopped. This applies to both General-purpose and Special-purpose registers. - Registers can be edited in the standard condensed view or in their particular parts - if the register is displayed expanded. + You can view register values when the application stops. Double-click + register values to edit them. - By default, the \uicontrol Registers view is hidden. + The values of registers that recently changed are highlighted in red. Empty + register values and leading zeroes are grayed out. + + Right-click column headers to show and hide the \uicontrol Name and + \uicontrol Value columns in the view. + + Right-click the view to select the following actions: + + \list + \li Reload register list. + \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}. + \endlist + + By default, the \uicontrol Registers view is hidden. To show it, select it in + \uicontrol Views on the debugger toolbar. + + \section1 Examining Memory + + You can examine memory in many formats, independently of the application's + data types. + + To open the memory editor, select a value \uicontrol Registers view, + and then select \uicontrol {Open Memory Editor at <value>} or + \uicontrol {Open Memory View at <value>} in the context menu: + + \image qtcreator-debugger-memory-editor.webp {Memory Editor} + + Hover the mouse pointer on a value to see details as a tooltip. + + Right-click a value to: + + \list + \li Copy the selection in ASCII or hexadecimal format. + \li Set a data breakpoint on the selection. + \li Jump to the selected address in the current data view or a new one. + \endlist */ /*! - \page creator-debugger-log-view.html + \page creator-peripheral-registers-view.html \previouspage creator-registers-view.html + \nextpage creator-debugger-log-view.html + + \title Peripheral Registers + + 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 + read them to get information from the device. To read registers in a + peripheral device, the application accesses its I/O addresses with a load + or store instruction that the CPU issues. + + \image qtcreator-debugger-peripheral-registers-view.webp {Peripheral Registers view} + + The \uicontrol Access column shows whether the register is read-and-write + (\uicontrol RW), read-only (\uicontrol RO), or write-only (\uicontrol WO). + \uicontrol N/A means that the access type is not available. + + Right-click column headers to show and hide columns in the view. + + Right-click the view to select the following actions: + + \list + \li View register groups. + \li Set \l{Debugger Preferences}{debugger preferences}. + \endlist + + By default, the \uicontrol {Peripheral Registers} view is hidden. To show it, + select it in \uicontrol Views on the debugger toolbar. +*/ + +/*! + \page creator-debugger-log-view.html + \previouspage creator-peripheral-registers-view.html \nextpage creator-disassembler-view.html - \title Directly Interacting with Native Debuggers + \title Debugger Log + + 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 \uicontrol Edit > + \uicontrol Preferences > \uicontrol Debugger > \uicontrol General > + \uicontrol {Force logging to console} check box. + + Right-click the view to select the following actions: + + \list + \li Copy, paste, cut, and delete log contents. + \li Undo and redo editing actions. + \li Select all log contents. + \li Clear log contents. + \li Save log contents as a file. + \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}. + \endlist + + \section1 Directly Interacting with Native Debuggers + + You can use the left pane of the \uicontrol {Debugger Log} view to directly + interact with the command line of the native debugger. - In some cases, it is convenient to directly interact with the command line - of the native debugger. In \QC, you can use the left pane of the - \uicontrol {Debugger Log} view for that purpose. When you press - \key {Ctrl+Enter}, the contents of the line under the text cursor are sent - directly to the native debugger. Alternatively, you can use the line edit at - the bottom of the view. Output is displayed in the right pane of the - \uicontrol {Debugger Log} view. + Press \key {Ctrl+Enter} to send the contents of the line under the + text cursor to the native debugger. Or, enter the command in the + \uicontrol Command field. The right side pane of the + \uicontrol {Debugger Log} view shows the command output. \note Usually, you do not need this feature because \QC offers better ways to handle the task. For example, instead of using the GDB \c print command from the command line, you can evaluate an expression in - the \uicontrol {Expressions} view. + the \l {Evaluating Expressions}{Expressions} view. */ /*! @@ -992,22 +1152,38 @@ \title Viewing Disassembled Code - The \uicontrol Disassembler view displays disassembled code for the current - function. + A \e disassembler translates machine language into assembly language for + human-readability. - The \uicontrol Disassembler view is useful for low-level commands for checking - single instructions, such as \uicontrol {Step Into} and \uicontrol {Step Over}. - By default, the \uicontrol Disassembler view is hidden. + The \uicontrol Disassembler view displays disassembled code for the current + function. It is useful for low-level commands for checking single + instructions, such as \uicontrol {Step Into} and \uicontrol {Step Over}. - To access the \uicontrol Disassembler view, check - \uicontrol Debug > \uicontrol {Operate by Instruction} while the debugger is - running. Alternatively, click the - \inlineimage icons/debugger_singleinstructionmode.png - (\uicontrol {Operate by Instruction}) tool button on the debugger tool bar. + \image qtcreator-debugger-disassembler-view.webp {Disassembler view} By default, GDB shows AT&T style disassembly. To switch to the Intel style, select \uicontrol Edit > \uicontrol 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 + the debugger is running. + \li Select the \inlineimage icons/debugger_singleinstructionmode.png + (\uicontrol {Operate by Instruction}) tool button on the debugger + toolbar. + \li In the \l {Viewing and Editing Register State}{Registers} view, + select a value, and then select \uicontrol {Open Disassembler at <value>} + in the context menu. + \endlist + + \section1 Starting Disassembler + + To start a disassembler from the \uicontrol Registers view, select + \uicontrol {Open Disassembler} and set the disassembler address: + + \image qcreator-debugger-select-start-address.webp {Select Start Address dialog} */ /*! @@ -1154,7 +1330,7 @@ The custom debugging helpers will be automatically picked up from \c personaltypes.py when you start a debugging session in \QC or select \uicontrol {Reload Debugging Helpers} from the context menu of the - \uicontrol {Debugger Log} view. + \l {Debugger Log} view. \section2 Debugging Helper Overview @@ -1700,7 +1876,7 @@ \li In the \uicontrol Debug mode, select \uicontrol View > \uicontrol Views > \uicontrol {Debugger Log} to open the - \uicontrol {Debugger Log} view. Browse the contents of the pane on + \l {Debugger Log} view. Browse the contents of the pane on the right hand side to find out what went wrong. Always attach the contents of the pane to debugger-related questions to the \QC mailing list (qt-creator@qt-project.org) or paste them to a @@ -1758,7 +1934,7 @@ \section2 Disabling Incremental Linking - Incremental linking can affect debugging. If the debugger log has + Incremental linking can affect debugging. If the \l {Debugger Log} view shows the \e {Unable to verify checksum of module} message, disable incremental linking. diff --git a/doc/qtcreator/src/docker/creator-docker.qdoc b/doc/qtcreator/src/docker/creator-docker.qdoc index d0123a2cdd..67604dae44 100644 --- a/doc/qtcreator/src/docker/creator-docker.qdoc +++ b/doc/qtcreator/src/docker/creator-docker.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -25,11 +25,9 @@ {debuggers} and \l{Adding Qt Versions}{Qt versions}, in the Docker container and creates kits for the devices. - You can use images that are available locally. You can pull - images from Docker hub or other registries using the + To pull images from Docker hub or other registries, use the \l{https://docs.docker.com/engine/reference/commandline/pull/}{docker pull} - command. To check that an image is available locally, run the - \c {docker images} command in a terminal. + command. \section1 Enabling Docker Plugin @@ -54,22 +52,46 @@ \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 In \uicontrol Devices, check and modify Docker device preferences. - \image qtcreator-preferences-devices-docker-device.webp "Docker device preferences" - \li Select \uicontrol {Run as outside user} to use the user ID - and group ID of the user running \QC in the Docker container. - \li Select \uicontrol {Do not modify entry point} to stop \QC from - modifying the entry point of the image if the image starts into - a shell. - \li In \uicontrol {Paths to mount}, specify host directories to - mount into the container, such as the project directory. - \li In \uicontrol {Search locations}, select where to search - for kit items. - \li Select \uicontrol {Auto-detect Kit Items} to find kit items and to - create kits for the Docker device. + \li In \uicontrol Devices, check and change 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. + + \table + \header + \li Option + \li Value + \row + \li \uicontrol {Run as outside user} + \li On Linux and \macos, sets the user ID and group ID of the user + running \QC in the Docker container. This option is not available + on Windows. + \row + \li \uicontrol {Do not modify entry point} + \li Stops \QC from modifying the \l {Modifying Entry Points}{entry point} + of the image. Make sure that the entry point starts a shell. + \row + \li \uicontrol {Enable flags needed for LLDB} + \li Adds the following flags to the container to allow LLDB to run: + \badcode + --cap-add=SYS_PTRACE --security-opt seccomp=unconfined + \endcode + \row + \li \uicontrol {Clangd executable} + \li The path to a remote Clangd executable to use for a remote code + model. + \row + \li \uicontrol {Paths to mount} + \li Host directories to \l{Specifying 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 + items. + \endtable + The following sections describe the Docker device preferences in more detail. \section2 Selecting Docker Images diff --git a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc index 48ba10de30..46b8781c08 100644 --- a/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc +++ b/doc/qtcreator/src/howto/creator-only/creator-autotest.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! @@ -10,7 +10,7 @@ \QC supports both \e {code based tests} and \e {build system based tests}. Code based testing offers special handling for particular testing - frameworks that is strongly tied to the underlying code models or + frameworks that strongly ties to the underlying code models or specialized parsers. Build system based testing is independent from any testing frameworks. It retrieves information directly from the underlying build system and uses it or even the build system as such to execute the @@ -20,14 +20,14 @@ applications and libraries: \list - \li \l{https://www.boost.org/doc/libs/1_70_0/libs/test/doc/html/index.html} + \li \l{https://www.boost.org/doc/libs/1_81_0/libs/test/doc/html/index.html} {Boost.Test} \li \l{https://github.com/catchorg/Catch2}{Catch2 test framework} \li \l{https://github.com/google/googletest}{Google C++ Testing Framework} \li \l{Qt Test} framework \endlist - \QC offers additional build system based support for + In addition, \QC offers build system based support for \l{https://cmake.org/cmake/help/latest/manual/ctest.1.html}{CTest}. You can use \QC to create, build, and run code based tests for your @@ -37,7 +37,7 @@ \section1 Build System Based Tests - The handling of build system based tests is disabled by default to avoid + By default, \QC does not handle build system based tests to avoid interference with code based parsers. To enable build system based tests, select the respective test tool in \uicontrol Preferences > \uicontrol Testing > \uicontrol General. @@ -47,12 +47,12 @@ The information in the tests tree is usually more detailed when using code based tests. - If you have enabled code based and build system based tests together you + If you enable both code based and build system based tests, you may duplicate tests inside the tests tree. See also \l {Selecting Tests to Run}. \section1 Creating Tests - You can use a wizard to create projects that have tests. + Use a wizard to create projects that have tests. \section2 Creating Qt and Qt Quick Tests @@ -75,7 +75,7 @@ \li For a Qt test, select the \uicontrol {GUI Application} check box to create a Qt application. - \image qtcreator-autotests-project-qt-test.png "Autotest project wizard - Qt Test" + \image qtcreator-autotests-project-qt-test.png {Autotest project wizard - Qt Test} \li In the \uicontrol {Test case name} field, enter a name for the test case. @@ -86,15 +86,15 @@ \li For a Qt Quick test, select the \uicontrol {Generate setup code} check box to execute C++ - code before any of the QML tests are run. The testing + code before running any of the QML tests. The testing framework will call slots and invocable functions, as described in \l{Executing C++ Before QML Tests}. - \image qtcreator-autotests-project-qtquick-test.png "Autotest project wizard - Qt Quick Test" + \image qtcreator-autotests-project-qtquick-test.png {Autotest project wizard - Qt Quick Test} \li Select the \uicontrol {Generate initialization and cleanup - code} checkbox to add functions to your test that are - executed by the testing framework to initialize and clean + code} checkbox to add functions to your test that the + testing framework executes to initialize and clean up the test. \li In the \uicontrol {Build system} field, select the build @@ -159,10 +159,10 @@ \section2 Creating Boost Tests To build and run Boost tests, you must have the Boost.Test installed on the - development host. Typically, it is installed when you install Boost. You can + development host. Typically, the Boost installation includes it. You can download Boost from \l{https://www.boost.org/}{Boost.org}. - If Boost libraries can be found by the used compiler and build system, you + If the compiler and build system can find the Boost libraries, you do not need to specify the include directory when creating the test. To create a Boost test: @@ -183,28 +183,27 @@ the test case. \li In the \uicontrol {Boost include dir (optional)} field, enter the path to the directory that has files needed - by Boost.Test, such as \e version.hpp and a subfolder called - \e test that has the test header files. + by Boost.Test, such as \e version.hpp and the \e test + subfolder that contains the test header files. \li In the \uicontrol {Build system} field, select the build system to use for building the project: qmake, CMake, or Qbs. \endlist \endlist - \QC creates the test in the specified project directory. + \QC creates the test in the project directory. For more information about creating Boost tests, see - \l{https://www.boost.org/doc/libs/1_70_0/libs/test/doc/html/index.html} + \l{https://www.boost.org/doc/libs/1_81_0/libs/test/doc/html/index.html} {Boost.Test}. \section2 Creating Catch2 Tests - To build and run Catch2 tests, you either must have Catch2 libraries and - headers installed, or you can use the single include header file in the + To build and run Catch2 tests, you can either install Catch2 + libraries and headers or use the single include header file in the Catch2 repository. - If the Catch2 headers can be found by the used compiler and build system - automatically, you do not need to specify the include directory when - creating the test. + If the compiler and build system can find the Catch2 headers automatically, + you do not need to specify the include directory when creating the test. To create a basic Catch2 test: @@ -219,9 +218,9 @@ \li In the \uicontrol {Test framework} field, select \uicontrol {Catch2}. \li In the \uicontrol {Test case name} field, specify a name - to be used for the test case file. + for the test case file. \li Select the \uicontrol {Use Qt libraries} check box - to use a self defined main function and set up the project + to use a self-defined main function and set up the project to use Qt features. \li In the \uicontrol {Catch2 include directory (optional)} field, you may enter a path to the directory that has the @@ -232,36 +231,34 @@ \endlist \endlist - \QC creates the test in the specified project directory. + \QC creates the test in the project directory. For more information about creating Catch2 tests, see \l{https://github.com/catchorg/Catch2/blob/master/docs/Readme.md} {Catch2}. \section2 Creating CTest Based Tests - CTest can execute tests for CMake based projects - and is not limited to a special test framework. - You simply configure tests inside the project files, usually CMakeLists.txt. - Basically this is done by enabling testing for the project and registering - the test applications or even special commands. + CTest can execute tests for CMake based projects regardless of the test + framework. You configure tests in the project file, usually, CMakeLists.txt. + Basically, you enable testing for the project and register the test + applications or even special commands. \code enable_testing() add_test(NAME test_example COMMAND test_example) \endcode - \c test_example must of course be added as an executable before trying to - register it as test or it may be any command that can be executed including - arguments. + Add \c test_example as an executable before trying to register it as test. + It may be any executable command including arguments. For detailed information on how to use CTest see \l{https://gitlab.kitware.com/cmake/community/-/wikis/doc/ctest/Testing-With-CTest} {Testing with CTest}. \section1 Setting Up the Google C++ Testing Framework - To build and run Google tests, you must have the Google C++ Testing - framework installed and configured on the development host. You can either - clone it from Git Hub or install it from an installation package. + To build and run Google tests, install and configure the Google C++ Testing + framework on the development host. You can either clone it from Git Hub or + install it from an installation package. To configure a project to use a cloned Google testing framework, edit the \c INCLUDEPATH variable in the project file (.pro) to include the source @@ -275,8 +272,7 @@ \li \c googlemock/include \endlist - You also need to add the necessary files to the \c SOURCES variable. For - example: + Also, add the necessary files to the \c SOURCES variable. For example: \list \li \c googletest/src/gtest-all.cc @@ -320,7 +316,7 @@ \li \inlineimage icons/qtcreator-run-failed-tests.png (\uicontrol {Run Failed Tests}) to re-run the tests which failed in the last run. - Depending on the framework this may select additional tests if it + Depending on the framework, this may select more tests if it is impossible to distinguish or to fully address the test. \li \inlineimage icons/qtcreator-run-tests-in-current-file.png (\uicontrol {Run Tests for Current File}) to run the tests @@ -338,7 +334,7 @@ The functions to run tests are also available in the context menu in the \uicontrol Tests view and in \uicontrol Tools > \uicontrol Tests. - \note If you have enabled build system based and code based tests, + \note If you enable both build system based and code based tests, you may run tests twice when using \uicontrol {Run All Tests} or \uicontrol {Run Selected Tests}. This happens if the tests can be found by the code based test frameworks and are registered as test @@ -356,8 +352,8 @@ \image qtcreator-tests-view.png If a Qt Quick test case does not have a name, it is marked - \uicontrol Unnamed in the list. Unnamed test cases are executed when you - select \uicontrol {Run All Tests}. You cannot select or deselect them. + \uicontrol Unnamed in the list. \uicontrol {Run All Tests} executes + unnamed test cases. You cannot select or deselect them. \QC scans the project for tests when you open the project and updates the test list for the currently active test frameworks when you edit tests. @@ -369,8 +365,8 @@ Cleanup Functions} or \uicontrol {Show Data Functions}. Double-click a function in the list to open its source code in the code editor. - The test cases are listed in alphabetic, case insensitive order. To list - them in the order in which they are defined in the source code, + The \uicontrol Tests view lists test cases in alphabetic, case insensitive + order. To list them in the order in which they appear in the source code, select \inlineimage icons/leafsort.png (\uicontrol {Sort Naturally}). @@ -396,46 +392,52 @@ \uicontrol Edit > \uicontrol Preferences > \uicontrol {Testing} > \uicontrol General. - \image qtcreator-autotests-options.png "Testing General preferences" + \image qtcreator-preferences-testing-general.webp {General tab in Testing preferences} You can customize some settings at project level. To change settings for the current project instead of globally, select \uicontrol Projects > \uicontrol {Project Settings} > \uicontrol {Testing}. - In the \uicontrol {Active Test Frameworks} list you can select which tests - \QC will handle. To improve the performance of full scans for tests, disable - test frameworks you are not using. + In the \uicontrol {Active Test Frameworks} list, select tests for \QC to + handle. To improve the performance of full scans for tests, disable + test frameworks you do not use. To group related test cases for an active test framework, select the \uicontrol Group check box next to the framework name in the \uicontrol {Active Test Frameworks} list. - By default, tests are grouped based on the directory where they are located. + By default, \QC groups tests that are in the same directory. - Internal messages and run configuration warnings for deduced configurations - are omitted by default. To view them, deselect the \uicontrol {Omit internal - messages} and \uicontrol {Omit run configuration warnings} check boxes. + \QC omits internal messages and run configuration warnings for + deduced configurations by default. To view them, deselect the + \uicontrol {Omit internal messages} and + \uicontrol {Omit run configuration warnings} check boxes. - By default, test result output is limited to 100,000 characters. The view - is automatically scrolled down when new results are added. To display + By default, test result output shows a maximum of 100,000 characters. The + view automatically scrolls to show the latest results. To display full results, deselect the \uicontrol {Limit result output} check box. To disable automatic scrolling, deselect the \uicontrol {Automatically scroll results} check box. - Test results can be grouped by the executable path that was used to run the - tests. This is useful if you have multiple test executables and run them all - at once. To enable this functionality you need to select the - \uicontrol {Group results by application} check box. + Set the maximum number of lines in the test result tooltip and description + in \uicontrol {Limit result description}. + + To group test results by the executable path that you use to run the + tests, select \uicontrol {Group results by application}. This is useful + if you have multiple test executables and run them all at once. - It is possible to automatically run the currently available tests after - successfully building the current project. In \uicontrol {Automatically run}, - select which tests should be run after a successful build. + To automatically run tests after successfully building the current project, + select them in \uicontrol {Automatically run}. - In some special setups, \QC cannot deduce which executable or run - configuration it should use. If \QC repeatedly asks you to select the - tests to run when trying to execute tests, you can enable it to cache - your choices and use them were appropriate. The cached information is - cleared when you switch to another project, close the current one, or - select \uicontrol {Reset Cached Choices}. + Sometimes, \QC cannot deduce which executable or run configuration to use. + If \QC repeatedly asks you to select the tests to run when trying to execute + tests, you can let it cache your choices and use them where appropriate. \QC + clears the cache when you switch to another project, close the current one, + or select \uicontrol {Reset Cached Choices}. + + Select the \uicontrol {Process arguments} check box to pass arguments to the + test executable that you specify in the \l {Managing Run Configurations} + {run configuration}. This is an experimental feature that might cause the + execution of the test executable to fail. \section2 Specifying Settings for Running Qt Tests @@ -447,7 +449,7 @@ walltime, CPU tick counter, event counter, Valgrind Callgrind, and Linux Perf. For more information, see \l{Creating a Benchmark}. - \image qtcreator-autotests-options-qt.png + \image qtcreator-preferences-testing-qttest.webp {Qt Tests tab in Testing preferences} To receive verbose output when running benchmarks, select the \uicontrol {Verbose benchmarks} check box. @@ -459,13 +461,13 @@ \uicontrol {Log signals and slots} check box. To explicitly limit the maximum number of warnings in the test log, select - the \uicontrol {Limit warnings} check box and specify the intended number - inside the spin box next to it. Set the number to 0 if you want no limit - at all. The default number is 2000. + the \uicontrol {Limit warnings} check box and set the limit. Set it to 0 if + you want no limit at all. The default number is 2000. - To check for Qt Quick Tests that are derived from TestCase select the + To check for Qt Quick Tests that are derived from TestCase, select the \uicontrol {Check for derived Qt Quick tests} check box. - Note: this feature is rather expensive and will increase the + + \note This feature is rather expensive and increases the scan time significantly. \section2 Specifying Settings for Running Google Tests @@ -473,24 +475,24 @@ To specify settings for running Google tests, select \uicontrol Edit > \uicontrol Preferences > \uicontrol {Testing} > \uicontrol {Google Test}. - \image qtcreator-autotests-options-google.png + \image qtcreator-preferences-testing-googletest.webp {Gooble Test tab in Testing preferences} To run disabled tests, select the \uicontrol {Run disabled tests} check box. To run several iterations of the tests, select the \uicontrol {Repeat tests} - check box and enter the number of times the tests should be run in the + check box and enter the number of times to run the tests in the \uicontrol Iterations field. To make sure that the tests are independent and - repeatable, you can run them in a different order each time by selecting the - \uicontrol {Shuffle tests} check box. + repeatable, run them in a different order each time by selecting the + \uicontrol {Shuffle tests} check box. Set the seed for initializing the + randomizer in the \uicontrol Seed field. The value 0 generates a seed + based on the current timestamp. To turn failures into debugger breakpoints, select the - \uicontrol {Break on failure while debugging} check box. To turn assertion - failures into C++ exceptions, select the \uicontrol {Throw on failure} check - box. + \uicontrol {Break on failure while debugging} check box. To group Google tests by using a GTest filter, select \uicontrol {GTest Filter} in the \uicontrol {Group mode} field, - and specify the filter to use in the \uicontrol {Active filter} + and specify the filter in the \uicontrol {Active filter} field. For more information about GTest filters, see \l{https://github.com/google/googletest/blob/master/docs/advanced.md#running-a-subset-of-the-tests} {Running a Subset of the Tests}. @@ -501,16 +503,18 @@ \li To specify settings for running Boost tests, select \uicontrol Edit > \uicontrol Preferences > \uicontrol {Testing} > \uicontrol {Boost Test}. - \image qtcreator-autotests-options-boost.png + \image qtcreator-preferences-testing-boosttest.webp {Boost Test tab in Testing preferences} \li In the \uicontrol {Log format} field, select the error report - format to specify the type of events you want recorded in the + format to specify the type of events to record in the test report. \li In the \uicontrol {Report level} field, select the verbosity level of the test result report. Select \uicontrol No if you do not want a report. \li Select the \uicontrol Randomize check box to execute the tests in a random order, using the seed specified in the \uicontrol Seed - field for initializing the randomizer. + field for initializing the randomizer. The value 0 means no + randomization, the value 1 uses the current time, and any other + value generates a random seed. \li Select the \uicontrol {Catch system errors} check box to catch system errors. \li Select the \uicontrol {Floating point exceptions} check box to @@ -524,7 +528,7 @@ \li To specify settings for running Catch2 tests, select \uicontrol Edit > \uicontrol Preferences > \uicontrol {Testing} > \uicontrol {Catch Test}. - \image qtcreator-autotests-options-catch2.png "Catch Test preferences" + \image qtcreator-preferences-testing-catchtest.webp {Catch Test tab in Testing preferences} \li Select the \uicontrol {Show success} check box to show succeeding expressions as well. By default Catch2 will print only fails. \li Select the \uicontrol {Break on failure while debugging} check box @@ -538,16 +542,15 @@ \li Select the \uicontrol {Abort after} check box to abort the test after the number of failures specified inside the spin box. \li Select the \uicontrol {Benchmark samples} check box to specify - the number of samples to be collected while running benchmarks. + the number of samples to collect while running benchmarks. \li Select the \uicontrol {Benchmark resamples} check box to specify - the number of resamples to be used for the statistical - bootstrapping performed after the benchmarking. + the number of resamples to use for statistical bootstrapping after + benchmarking. \li Select the \uicontrol {Benchmark confidence interval} check box - to specify the confidence interval used for the statistical - bootstrapping. + to specify the confidence interval for statistical bootstrapping. \li Select the \uicontrol {Benchmark warmup time} check box to specify - the warmup time for each test before benchmarking start. - \li Select the \uicontrol {Disable analysis} check box to disable the + the warmup time for each test before benchmarking starts. + \li Select the \uicontrol {Disable analysis} check box to disable statistical analysis and bootstrapping. \endlist @@ -556,7 +559,7 @@ \li To specify settings for running CTest-based tests, select \uicontrol Edit > \uicontrol Preferences > \uicontrol {Testing} > \uicontrol {CTest}. - \image qtcreator-autotests-options-ctest.png "CTest preferences" + \image qtcreator-preferences-testing-ctest.webp {CTest tab in Testing preferences} \li Select the \uicontrol {Output on failure} check box to show test specific output if a test fails. Contrary to the CTest default this is enabled by default. @@ -570,30 +573,37 @@ \li Select \uicontrol {Repeat tests} if you want to re-run tests under certain circumstances. \li In the \uicontrol {Repetition mode} field, select the mode for - re-running tests. The maximum count for repeating a test can be - specified in the \uicontrol {Count} field. + re-running tests. Set the maximum count for repeating a test in + the \uicontrol {Count} field. \li Select \uicontrol {Run in parallel} to run the tests in parallel using the specified number of \uicontrol {Jobs}. - \li Select \uicontrol {Test load} to be able to limit the parallel + \li Select \uicontrol {Test load} to limit the parallel execution. CTest will not start a new test if it would cause the - CPU load to pass the threshold given in \uicontrol {Threshold}. + CPU load to pass the threshold set in \uicontrol {Threshold}. \endlist \section1 Viewing Test Output - The test results are displayed in \l{Viewing Output}{Test Results} - in XML format. XML can be parsed more easily and reliably than plain text. + The \l{Viewing Output}{Test Results} view shows Qt and Qt Quick test results + in XML format and other test results in plain text format. - However, if a Qt test crashes, it might not produce complete XML code that - can be parsed, which might lead to information loss. The lost information - might be retrievable when viewing the results as plain text. - To view the results of Qt tests as plain text, select \uicontrol Edit > + \section2 Qt Test Output + + XML can be parsed more easily and reliably than plain text. However, if a Qt + or Qt Quick test crashes, it might not produce complete XML + code that can be parsed, which might lead to information loss. You might see + the lost information when viewing the results as plain text. + + To view the + results of Qt and Qt Quick tests as plain text, select \uicontrol Edit > \uicontrol Preferences > \uicontrol {Testing} > \uicontrol {Qt Test}, and then deselect the \uicontrol {Use XML output} check box. Then select the \inlineimage icons/text.png (\uicontrol {Switch Between Visual and Text Display}) button in \uicontrol {Test Results} to switch to the text display. + \section2 Summary of Messages + The following table lists the messages that \uicontrol {Test Results} displays: @@ -643,6 +653,12 @@ \endtable + To view only messages of a particular type, select + \inlineimage icons/filtericon.png + (\uicontrol {Filter Test Results}), and then select the types of messages to + show. To show all messages, select \uicontrol {Check All Filters}. To + deselect all message types, select \uicontrol {Uncheck All Filters}. + Since Qt 5.4, you can add a BLACKLIST file for tests. It is mainly used internally by the Qt CI system. @@ -664,10 +680,4 @@ \li Blacklisted test case passed even though it was expected to fail. \endtable - - To view only messages of a particular type, select - \inlineimage icons/filtericon.png - (\uicontrol {Filter Test Results}), and then select the types of messages to - show. To show all messages, select \uicontrol {Check All Filters}. To - deselect all message types, select \uicontrol {Uncheck All Filters}. */ diff --git a/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc b/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc index 6a883fe37a..6a1d6a1227 100644 --- a/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc +++ b/doc/qtcreator/src/howto/creator-only/qtcreator-faq.qdoc @@ -175,7 +175,7 @@ \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 > \uicontrol {Debugger Log}. + select \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/projects/creator-only/creator-projects-targets.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc index a242e94e15..04b639f1dd 100644 --- a/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc +++ b/doc/qtcreator/src/projects/creator-only/creator-projects-targets.qdoc @@ -1,4 +1,4 @@ -// Copyright (C) 2022 The Qt Company Ltd. +// Copyright (C) 2023 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only // ********************************************************************** @@ -30,11 +30,12 @@ \li \l{https://doc.qt.io/Boot2Qt/b2qt-installation-guides.html} {Boot2Qt Device} (commercial only) \li \l{Emulator}{Boot2Qt Emulator Device} (commercial only) - \li \l{Connecting Remote Linux Devices}{Remote Linux Device} + \li \l{Adding Docker Devices}{Docker Device} (experimental) \li \l{Connecting iOS Devices}{iOS Device} \li iOS Simulator \li \l{Connecting MCUs}{MCU Device} (commercial only) \li \l{Connecting QNX Devices}{QNX Device} + \li \l{Connecting Remote Linux Devices}{Remote Linux Device} \li \l{Building Applications for the Web}{WebAssembly Runtime} \endlist diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index d514c329c3..e2299cd05c 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -175,7 +175,7 @@ \li \l{Local Variables and Function Parameters} \li \l{Evaluating Expressions} \li \l{Viewing and Editing Register State} - \li \l{Directly Interacting with Native Debuggers} + \li \l{Debugger Log} \li \l{Viewing Disassembled Code} \li \endlist diff --git a/doc/qtcreatordev/src/qtcreator-ui-text.qdoc b/doc/qtcreatordev/src/qtcreator-ui-text.qdoc index 1d053b3893..84688a4b85 100644 --- a/doc/qtcreatordev/src/qtcreator-ui-text.qdoc +++ b/doc/qtcreatordev/src/qtcreator-ui-text.qdoc @@ -413,7 +413,7 @@ provides them with functions for managing the information. Available in \uicontrol Debug mode, for interaction with the program that is running under the control of the debugger. - \image qtcreator-debugger-views.png "Views" + \image qtcreator-debugger-views.webp "Views" \li Use descriptive names for views. \endtable |
