diff options
Diffstat (limited to 'doc/qtcreator/src/debugger')
| -rw-r--r-- | doc/qtcreator/src/debugger/creator-debug-views.qdoc (renamed from doc/qtcreator/src/debugger/creator-debugger-common.qdocinc) | 318 | ||||
| -rw-r--r-- | doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc (renamed from doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdocinc) | 39 | ||||
| -rw-r--r-- | doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc | 118 | ||||
| -rw-r--r-- | doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc | 697 | ||||
| -rw-r--r-- | doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc | 4 | ||||
| -rw-r--r-- | doc/qtcreator/src/debugger/qtquick-debugging.qdoc | 13 |
6 files changed, 747 insertions, 442 deletions
diff --git a/doc/qtcreator/src/debugger/creator-debugger-common.qdocinc b/doc/qtcreator/src/debugger/creator-debug-views.qdoc index 1226853275..d1c2adff5f 100644 --- a/doc/qtcreator/src/debugger/creator-debugger-common.qdocinc +++ b/doc/qtcreator/src/debugger/creator-debug-views.qdoc @@ -1,13 +1,57 @@ -// 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 /*! + \page creator-stack-view.html + \if defined(qtdesignstudio) + \previouspage creator-debugging-qml.html + \else + \previouspage creator-debug-mode.html + \endif + \nextpage creator-breakpoints-view.html + + \title Viewing Call Stack Trace + + When the application being debugged is interrupted, \QC displays the nested + function calls leading to the current position as a call stack trace. This + stack trace is built up from call stack frames, each representing a + particular function. For each function, \QC tries to retrieve the file name + and line number of the corresponding source file. This data is shown in the + \uicontrol Stack view. + + \image qtcreator-debug-stack.png {Stack view} -//! [debugger-breakpoints] + 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. + + If you click a frame with a known source location, the text editor jumps to + 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. - \section1 Setting Breakpoints + \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, + should it find any. You can click a frame in the QML stack to open the QML + file in the editor. +*/ +/*! + \page creator-breakpoints-view.html + \previouspage creator-stack-view.html + \if defined(qtdesignstudio) + \nextpage creator-locals-view.html + \else + \nextpage creator-threads-view.html + \endif + \title Setting Breakpoints You can associate breakpoints with: @@ -25,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 @@ -34,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. @@ -74,13 +122,13 @@ \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} - \section2 Adding Breakpoints + \section1 Adding Breakpoints To add breakpoints: @@ -92,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: @@ -105,30 +153,76 @@ \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 + application code where you want the application to stop. - \li In the \uicontrol Condition field, set the condition to be evaluated - before stopping at the breakpoint if the condition evaluates as - true. + \image qtcreator-add-breakpoint.webp {Add Breakpoints} dialog + \endlist - \li In the \uicontrol Ignore field, specify the number of times that the - breakpoint is ignored before the program stops. + 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. - \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. + 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. - \endlist + \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) - \section2 Specifying Breakpoint Settings + \section1 Specifying Breakpoint Settings You can specify settings for breakpoints in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger. For more information, - see \l{Specifying Debugger Settings}. + 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. @@ -155,14 +249,14 @@ You can automatically add breakpoints on some functions to catch error and warning messages. For more information, see \l{Specifying CDB Settings} - and \l{Specifying Extended GDB Settings}. + and \l{Specifying GDB Settings}. For more information on breakpoints, see \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints} {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation. \endif - \section2 Moving Breakpoints + \section1 Moving Breakpoints To move a breakpoint: @@ -175,7 +269,7 @@ line number in the \uicontrol {Line number} field. \endlist - \section2 Deleting Breakpoints + \section1 Deleting Breakpoints To delete breakpoints: @@ -195,7 +289,7 @@ \endlist - \section2 Enabling and Disabling Breakpoints + \section1 Enabling and Disabling Breakpoints To temporarily disable a breakpoint without deleting it and losing associated data like conditions and commands: @@ -205,7 +299,7 @@ \li Right-click the breakpoint marker in the text editor and select \uicontrol{Disable Breakpoint}. - \li Select a line that contains a breakpoint and press \key Ctrl+F9 + \li Select a line that has a breakpoint and press \key Ctrl+F9 (\key Ctrl+F8 on \macos). \li In the \uicontrol {Breakpoint Preset} view or the @@ -220,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. - \section2 Setting Data Breakpoints + \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: @@ -250,55 +344,29 @@ \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. +*/ -//! [debugger-breakpoints] - -//! [debugger-call-stack-trace] - - \section1 Viewing Call Stack Trace - - When the program 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 - and line number of the corresponding source file. This data is shown in the - \uicontrol Stack view. - - \image qtcreator-debug-stack.png - - 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. - - 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. - - To find out which QML file is causing a Qt Quick 2 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, - should it find any. You can click a frame in the QML stack to open the QML - file in the editor. - -//! [debugger-call-stack-trace] - -//! [debugger-locals] +/*! + \page creator-locals-view.html + \if defined(qtdesignstudio) + \previouspage creator-breakpoints-view.html + \else + \previouspage creator-source-files-view.html + \endif + \nextpage creator-expressions-view.html - \section1 Local Variables and Function Parameters + \title Local Variables and Function Parameters - The Locals view consists of the \uicontrol Locals pane and the + The \uicontrol {Locals} view consists of the \uicontrol Locals pane and the \uicontrol {Return Value} pane (hidden when empty). - \image qtcreator-locals.png "Locals view" + \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 @@ -310,12 +378,18 @@ objects will be displayed. Select \uicontrol {Use dynamic object type for display} in the context menu. Keep in mind that choosing the dynamic type might be slower. +*/ -//! [debugger-locals] - -//! [debugger-expressions] +/*! + \page creator-expressions-view.html + \previouspage creator-locals-view.html + \if defined(qtdesignstudio) + \nextpage creator-qml-debugging-example.html + \else + \nextpage creator-registers-view.html + \endif - \section1 Evaluating Expressions + \title Evaluating Expressions To compute values of arithmetic expressions or function calls, use expression evaluators in the \uicontrol Expressions view. To insert a new @@ -324,7 +398,7 @@ \uicontrol {Add New Expression Evaluator} from the context menu, or drag and drop an expression from the code editor. - \image qtcreator-debugger-expressions.png + \image qtcreator-debugger-expressions.png {Expressions view} \note Expression evaluators are powerful, but slow down debugger operation significantly. It is advisable to not use them excessively, and to remove @@ -336,16 +410,12 @@ The QML debugger can evaluate JavaScript expressions. -//! [debugger-expressions] - -//! [debugger-expressions-cpp] - + \if defined(qtcreator) 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 functions such as most - \c{operator[]} implementations of standard containers are typically \e{not} - available. + Functions can be called only if they are actually compiled into the debugged + executable or a library used by the executable. Most notably, 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 display multiple values with one expression. A sub-expression of form @@ -357,49 +427,38 @@ value and type, you can examine and traverse the low-level layout of object data. - \table - \row - \li \b{Note:} - - \row - \li 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 - unexpected data. - \row - \li The debug information provided by GCC does not include enough - information about the time when a variable is initialized. - Therefore, \QC can not tell whether the contents of a local - variable contains "real data", or "initial noise". If a QObject - appears uninitialized, its value is reported as - \uicontrol {not in scope}. Not all uninitialized objects, - however, can be recognized as such. - \endtable + 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 + unexpected data. - \note The set of evaluated expressions is saved in your session. + The debug information from GCC does not include enough + information about the time when a variable is initialized. + Therefore, \QC can not tell whether the contents of a local + variable are \e {real data} or \e {initial noise}. If a QObject + appears uninitialized, its value is reported as + \uicontrol {not in scope}. Not all uninitialized objects, + however, can be recognized as such. -//! [debugger-expressions-cpp] - -//! [debugger-qt-basic-objects] + \note The set of evaluated expressions is saved in your session. \section1 Inspecting Basic Qt Objects - The \uicontrol {Locals} and \uicontrol {Expressions} views also provide access - to the most powerful feature of the debugger: comprehensive display of data - belonging to Qt's basic objects. For example, in case of QObject, instead of - displaying a pointer to some private data structure, you see a list of + The most powerful feature of the debugger is that the \uicontrol {Locals} + and \uicontrol {Expressions} views show the data that belongs to + Qt's basic objects. For example, in case of QObject, instead of + a pointer to some private data structure, you see a list of children, signals, and slots. Similarly, instead of displaying many pointers and integers, \QC's debugger displays the contents of a QHash or QMap in an orderly manner. Also, the - debugger displays access data for QFileInfo and provides access to the - \e real contents of QVariant. + debugger shows access data for QFileInfo and the \e real contents of QVariant. Right-click in the \uicontrol {Locals} or the \uicontrol {Expressions} view - to open a context menu that provides additional options for viewing data. The - available options depend on the type of the current items, and are provided - by the \l{Using Debugging Helpers}{Debugging Helpers}. Typically, + to open a context menu that has more options for viewing data. The + available options depend on the type of the current items, and come from + the \l{Using Debugging Helpers}{Debugging Helpers}. Typically, string-like data, such as \c{QByteArray} and \c{std::string}, offer a selection of encodings, as well as the possibility to use a full editor window. Map-like data, such as \c{QMap}, \c{QHash}, and \c{std::map}, offer @@ -410,7 +469,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). @@ -420,6 +479,5 @@ You can enable tooltips in the main editor displaying this information. For more information, see \l{See the value of variables in tooltips while debugging}. - -//! [debugger-qt-basic-objects] + \endif */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdocinc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc index 057f43aa41..334e3c86a6 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdocinc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc @@ -1,11 +1,12 @@ -// 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 /*! + \page creator-debugger-preferences.html + \previouspage creator-remote-debugging.html + \nextpage creator-debugging-helpers.html -//! [debugger-settings] - - \section1 Specifying Debugger Settings + \title Debugger Preferences To specify settings for managing debugger processes, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger. In the \uicontrol General tab, @@ -22,10 +23,10 @@ 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. - \section2 Mapping Source Paths + \section1 Mapping Source Paths 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 @@ -47,7 +48,7 @@ of the source tree on the local machine. \endlist - \section2 Specifying GDB Settings + \section1 Specifying GDB Settings To specify settings for managing the GDB process, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > \uicontrol GDB. @@ -95,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. @@ -110,16 +111,11 @@ To execute arbitrary Python scripts, use \c {python execfile('/path/to/script.py')}. - \section2 Specifying Extended GDB Settings - - To specify extended settings for GBD, select \uicontrol Edit > - \uicontrol Preferences > \uicontrol Debugger > \uicontrol {GDB Extended}. - The settings give access to advanced or experimental functions of GDB. + The settings in the \uicontrol Extended group give access to advanced + or experimental functions of GDB. Enabling them may negatively impact your debugging experience, so use them with care. - \image qtcreator-gdb-extended-options.png "GDB Extended preferences" - To use asynchronous mode to control the inferior, select the respective check box. @@ -138,7 +134,7 @@ To keep debugging all children after a fork, select the \uicontrol {Debug all child processes} check box. - \section2 Specifying CDB Settings + \section1 Specifying CDB Settings To specify settings for managing the CDB process, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > \uicontrol CDB. @@ -175,9 +171,8 @@ source code editor, select the \uicontrol {Correct breakpoint location} check box. For more information, see \l{Setting Breakpoints}. - To use the abstraction layer provided by Python Dumper - classes to create a description of data items displayed - in the \uicontrol Locals and \uicontrol Expressions + To use the abstraction layer of Python Dumper classes to create a description + of data items in the \uicontrol Locals and \uicontrol Expressions views, select the \uicontrol {Use Python dumper} check box. For more information, see \l{Debugging Helper Implementation}. @@ -185,10 +180,10 @@ in \l Issues, select the check boxes in the \uicontrol {Add Exceptions to Issues View} group. - \section2 Setting CDB Paths on Windows + \section1 Setting CDB Paths on Windows To obtain debugging information for the operating system libraries for - debugging Windows applications, add the Symbol Server provided by Microsoft + debugging Windows applications, add the Microsoft Symbol Server to the symbol search path of the debugger: \list 1 @@ -208,6 +203,4 @@ To use the Source Server infrastructure for fetching missing source files directly from version control or the web, enter the following string in the \uicontrol {Source Paths} field: \c srv*. - -//! [debugger-settings] */ 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 7e61aa9ddb..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 contains no, or an - outdated version of GDB and you want to use a locally installed replacement - instead). + 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 Symbol Server provided by Microsoft 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 explains the options you have for debugging C++ code and - provides installation notes for 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. @@ -145,8 +152,7 @@ \section1 Installing Native Debuggers - The following sections provide information about installing native - debuggers. + The following sections describe installing native debuggers. \section2 GDB @@ -183,24 +189,15 @@ the required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}. - \section3 Symbol Server - - It is highly recommended that you add the Symbol Server provided - by Microsoft to the symbol search path of the debugger. The - Symbol Server provides you with 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 contains both debug and release - variants of the libraries. But you have to explicitly tell the + The Qt binary distribution has both debug and release + variants of the libraries. However, you have to explicitly tell the runtime linker that you want to use the debug libraries even if your application is compiled as debug, as release is the default 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}. @@ -213,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 @@ -267,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 35d598d4c6..1009f765ab 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.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 // ********************************************************************** @@ -14,10 +14,32 @@ \title Debugging - \QC provides a debugger plugin that acts as an interface between the \QC - core and external native debuggers such as the GNU Symbolic Debugger (GDB), - the Microsoft Console Debugger (CDB), a QML/JavaScript debugger, and the - debugger of the low level virtual machine (LLVM) project, LLDB. + A debugger lets you see what happens \e inside an application while it runs + or when it crashes. A debugger can do the following to help you find errors + in the application: + + \list + \li Start the application with parameters that specify its behavior. + \li Stop the application when conditions are met. + \li Examine what happens when the application stops. + \li Make changes in the application when you fix an error and continue + to find the next one. + \endlist + + The \QC debugger plugin acts as an interface between the \QC + core and external native debuggers that you can use to: + + \list + \li Debug executable binary files - GNU Symbolic Debugger (GDB), + the Microsoft Console Debugger (CDB), and the debugger of the + 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 - PDB. + \endlist + + The following sections describe how to set up, launch, and interact with the + debugger: \list @@ -36,11 +58,34 @@ \key F5. Other, less common start options are available in the \uicontrol Debug > \uicontrol {Start Debugging} menu. - \li \l{Interacting with the Debugger} + \li \l{Debug Mode Views} - You can use the tool views in the \uicontrol Debug mode to inspect the + Use the views in the \uicontrol Debug mode to inspect the state of your application while debugging. + \li \l{Stopping Applications} + + You can interrupt a running application before it terminates + or to find out why the application does not work correctly. + Set breakpoints to stop the application for examining and changing + variables, setting new breakpoints or removing old ones, and then + continue running the application. + + \li \l{Examining Data} + + You can examine variable values and data structures in detail. + + \li \l{Remote Debugging} + + You can debug an application that runs on a remote target with the + necessary helper processes also running. + + \li \l{Debugger Preferences} + + Specify preferences for managing debugger processes. You can specify + preferences that are common to all debuggers, or the native debugger + that you use, GDB or CDB. + \li \l{Using Debugging Helpers} \QC is able to show complex data types in a customized, @@ -85,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 - deploys it if the \uicontrol {Build before deploying} field is set to - build the whole project or the application to run and the - \uicontrol {Always deploy before running} check box is selected in + \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{Specifying Debugger Settings}. + \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. + + 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 Launching the Debugger in Different Modes + \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 @@ -134,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 @@ -166,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: @@ -216,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. @@ -240,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 @@ -267,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 @@ -295,7 +343,7 @@ \li In the \uicontrol {Core file} field, specify the core file to inspect. \li In the \uicontrol {Executable of symbol file} field, specify - a file that contains debug information corresponding to the + a file that has debug information corresponding to the core file. Typically, this is the executable file or a \c {.debug} file if the debug information is stored separately from the executable. @@ -305,12 +353,12 @@ the \c sysroot to use instead of the default \c sysroot. \endlist - Also in this mode, using a properly configured project containing 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 @@ -320,13 +368,17 @@ 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. +*/ - \section1 Remote Debugging +/*! + \page creator-remote-debugging.html + \previouspage creator-debugger-examining-data.html + \nextpage creator-debugger-preferences.html - \QC provides very easy access to remote debugging. + \title Remote Debugging + \QC makes remote debugging easy. In general, the remote debugging setup consist of a probe running on the remote machine and a counterpart running on the host side. The probe is either integrated into the running process (e.g. for QML debugging) or runs @@ -344,7 +396,7 @@ Special use cases, such as attaching to a running process on the target, might still require manual setup. - \section3 Using GDB + \section1 Using GDB When debugging on a target supported by GDB server, a local GDB process talks to a GDB server running on the remote machine that controls the @@ -414,14 +466,13 @@ To increase the timeout in the \uicontrol {GDB timeout} field, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > \uicontrol GDB. For more information about settings that you can specify - to manage the GDB process, see \l{Specifying GDB Settings} and - \l{Specifying Extended GDB Settings}. + to manage the GDB process, see \l{Specifying GDB Settings}. For more information about connecting with \c {target extended-remote} mode in GDB, see \l{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html} {Debugging with GDB: Connecting to a Remote Target}. - \section3 Using CDB + \section1 Using CDB In remote mode, the local CDB process talks to a CDB process that runs on the remote machine. The process is started with special command line options @@ -431,7 +482,7 @@ \list 1 \li Install the \e{Debugging Tools for Windows} on the remote machine. - The installation folder contains the CDB command line executable + The installation folder has the CDB command line executable (\c cdb.exe). \li Copy the \QC CDB extension library and the dependencies from the Qt installation @@ -496,71 +547,125 @@ \page creator-debug-mode.html \if defined(qtdesignstudio) \previouspage studio-debugging.html - \nextpage creator-debugging-qml.html \else \previouspage creator-debugger-operating-modes.html - \nextpage creator-debugging-helpers.html \endif + \nextpage creator-stack-view.html - \title Interacting with the Debugger + \title Debug Mode Views - You can use the \QC \uicontrol Debug mode to inspect the state of your - application while debugging. You can interact with the debugger in several - ways, including the following: + In the \uicontrol Debug mode, you can inspect the state of your + 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 - \omit - \li Create snapshots of the current state of the debugged program - and re-examine them later. - \endomit + The following table summarizes the \uicontrol Debug mode views with links to + more information. + + \table + \header + \li View + \li Purpose + \li Learn More + \row + \li Stack + \li Examine the nested function calls leading to the current position + as a call stack trace. + \li \l {Viewing Call Stack Trace} + \row + \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} + \row + \li Threads + \li Switch between threads. + \li \l {Viewing Threads} + \row + \li Modules + \li View information about modules included in the application. + \li \l {Viewing Modules} + \row + \li Source Files + \li View a list of source files included in the project. + \li \l {Viewing Source Files} + \row + \li Locals + \li View information about the parameters of the function in the topmost + stack frame and local variables. + \li \l {Local Variables and Function Parameters} + \row + \li Expressions + \li Compute values of arithmetic expressions or function calls. + \li \l {Evaluating Expressions} + \row + \li Registers + \li View the current state of the CPU registers to examine the + application at the machine level. + \li \l {Viewing and Editing Register State} + \row + \li Peripheral Registers + \li View the current state of peripheral registers. + \li + \row + \li 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 + of the line under the text cursor in the log directly to the + native debugger. + \li \l{Troubleshooting Debugger} - \endlist + \l {Directly Interacting with Native Debuggers} + \row + \li Disassembler + \li View disassembled code for the current function. + \li \l {Viewing Disassembled Code} + \row + \li Editor + \li Open the current source file in the text editor for changing it. + \li \l {Working in Edit Mode} + \endtable + + \section1 Managing Debug Views - \QC displays the raw information provided by 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 provided by 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. - This deeper understanding is used to present objects of such classes in a - useful way. - - \section1 Using the Debugger - - In \uicontrol Debug mode, you can use several views to interact with the - program you are debugging. 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 debugger view. - - \image qtcreator-debugger-views.png "Debug mode 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 + 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} + + 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 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. @@ -570,29 +675,74 @@ To show and hide columns in views, toggle \uicontrol {Show Column} in the context menu. - 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. + \section1 Customizing Debug Views - Once the program stops, \QC: + 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 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 + interrupted. + \endlist - \li Retrieves data representing the call stack at the program's current - position. + For more information, see \l{Debugger Preferences}. +*/ - \li Retrieves the contents of local variables. +/*! + \page creator-debugger-stopping.html + \previouspage creator-disassembler-view.html + \nextpage creator-debugger-examining-data.html - \li Examines \uicontrol Expressions. + \title Stopping Applications - \li Updates the \uicontrol Registers, \uicontrol Modules, and - \uicontrol Disassembler views if you are debugging the C++ based - applications. + Once the application starts running under the control of the debugger, it + behaves and performs as usual. + + To interrupt a running C++ application, select \uicontrol Debug > + \uicontrol Interrupt. The debugger automatically interrupts + the application when it hits a \l {Setting Breakpoints}{breakpoint}. + + Once the application stops, \QC: + + \list + + \li Retrieves data representing the \l{Viewing Call Stack Trace} + {call stack} at the application's current position. + + \li Retrieves the contents of \l{Local Variables and Function Parameters} + {local variables}. + + \li Examines \l{Evaluating Expressions}{expressions}. + + \li Updates the \l{Viewing and Editing Register State}{Registers}, + \l{Viewing Modules}{Modules}, and \l{Viewing Disassembled Code} + {Disassembler} views if you are debugging C++ based applications. \endlist + You can \l{Examining Data}{Examine} and change variables, set or remove + breakpoints, and then continue running the application. +*/ + +/*! + \page creator-debugger-examining-data.html + \previouspage creator-debugger-stopping.html + \nextpage creator-remote-debugging.html - You can use the \uicontrol Debug mode views to examine the data in more detail. + \title Examining Data + + Use the \l{Local Variables and Function Parameters}{Locals} and + \l{Evaluating Expressions}{Expressions} views to examine the data + in more detail. You can use the following keyboard shortcuts: @@ -609,9 +759,9 @@ \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 containing the cursor, press \key {Ctrl+F10} + \li To run to the line that has the cursor, press \key {Ctrl+F10} (\key {Shift+F8} on \macos). \li To run to the selected function when you are stepping into a nested @@ -619,57 +769,52 @@ \endlist - It is also possible to 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. - \section2 Stepping Into Code + \section1 Stepping Into Code + + Use the following buttons to step through the code: + + \table + \header + \li Button + \li Function + \li Description + \row + \li \inlineimage icons/qtcreator-debug-button-stop.png + \li \uicontrol {Stop Debugger} + \li Stops the debugger. + \row + \li \inlineimage icons/debugger_stepover_small.png + \li \uicontrol {Step Over} + \li Steps over the next line inside the function being debugged. It + executes the call and moves to the next line to be executed in + the function. + \row + \li \inlineimage icons/debugger_stepinto_small.png + \li \uicontrol {Step Into} + \li Steps into the line that it is currently on. For a function call, + goes into the function and is ready to continue. + \row + \li \inlineimage icons/debugger_stepout_small.png + \li \uicontrol {Step Out} + \li Finishes executing the function and exits to the function that + it was called from. + \row + \li \inlineimage icons/qtcreator-debugging-continue.png + \li \uicontrol {Continue} + \li Resumes application execution at the address where it last + stopped. + \endtable When using GDB as the debugging backend, you can compress several steps into one step for less noisy debugging. For more information, see \l{Specifying GDB Settings}. - The extended GDB settings provide the option to step backwards in code, + The extended GDB settings have the option to step backwards in code, but this option should be used with care, as it is slow and unstable on the - GDB side. For more information, see \l{Specifying Extended GDB Settings}. - - \section2 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: - - \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 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 - interrupted. - \endlist - - For more information, see \l{Specifying Debugger Settings}. - - \include creator-debugger-common.qdocinc debugger-breakpoints - \include creator-debugger-common.qdocinc debugger-call-stack-trace - \include creator-debugger-common.qdocinc debugger-locals - \include creator-debugger-common.qdocinc debugger-expressions - \include creator-debugger-common.qdocinc debugger-expressions-cpp - \include creator-debugger-common.qdocinc debugger-qt-basic-objects - - \section1 Directly Interacting with Native Debuggers - - 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. - - \note Usually, you do not need this feature because \QC provides you - with 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. + GDB side. For more information, see \l{Specifying GDB Settings}. \section1 Debugging C++ Based Applications @@ -701,130 +846,228 @@ \section2 Stepping into Frameworks in \macos In \macos, external libraries are usually built into so-called Frameworks, - which may contain both release and debug versions of the library. When you + which may have both release and debug versions of the library. When you run applications on the \macos desktop, the release version of Frameworks is used by default. To step into Frameworks, select the \uicontrol {Use debug versions of Frameworks} option in the project run settings. - \section2 Viewing Threads + \omit + \section2 Creating Snapshots + + A snapshot has the complete state of the debugged application at a time, + including the full memory contents. + + 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 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 + \l{https://sourceware.org/gdb/onlinedocs/gdb/Core-File-Generation.html}. + + \endomit +*/ + +/*! + \page creator-threads-view.html + \previouspage creator-breakpoints-view.html + \nextpage creator-modules-view.html + + \title Viewing Threads + + 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. - 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. + 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): - \section2 Viewing Modules + \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. +*/ + +/*! + \page creator-modules-view.html + \previouspage creator-threads-view.html + \nextpage creator-source-files-view.html + + \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 contains 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}. +*/ + +/*! + \page creator-source-files-view.html + \previouspage creator-modules-view.html + \nextpage creator-locals-view.html - \section2 Viewing Source Files + \title Viewing Source Files The \uicontrol {Source Files} view lists all the source files included in the project. If you cannot step into an instruction, you can check whether the source file is actually part of the project, or whether it was compiled elsewhere. The view shows the path to each file in the file system. - Right-click the view to open a context menu that contains menu items for - reloading data and opening files. + \image qtcreator-debugger-source-files.webp {Source Files view} - 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}. + Right-click the view to select the following actions: - By default, the \uicontrol {Source Files} view is hidden. + \list + \li Reload data + \li Open the selected file + \li Set \l{Debugger Preferences}{debugger preferences} + \endlist - \section2 Viewing Disassembled Code + By default, the \uicontrol {Source Files} view is hidden. To show it, select + it in \uicontrol Views on the debugger toolbar. - The \uicontrol Disassembler view displays disassembled code for the current - function. + \section1 External Sources - 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. + To enable the debugger to step into the code and display the source code + when using a copy of the source tree at a location different from the one + at which the libraries were built, you can map source paths to target + paths in \uicontrol Edit > \uicontrol Preferences > \uicontrol Debugger > + \uicontrol General: - 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-general-options.png {General tab in Debugger preferences} - 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}. + For more information, see \l{Mapping Source Paths}. +*/ + +/*! + \page creator-registers-view.html + \previouspage creator-expressions-view.html + \nextpage creator-debugger-log-view.html - \section2 Viewing and Editing Register State + \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. - In addition it is possible to edit the content of registers while the program is + In addition it is possible to edit the content of registers while the application 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. By default, the \uicontrol Registers view is hidden. +*/ - \omit - \section2 Creating Snapshots +/*! + \page creator-debugger-log-view.html + \previouspage creator-registers-view.html + \nextpage creator-disassembler-view.html - A snapshot contains the complete state of the debugged program at a time, - including the full memory contents. + \title Directly Interacting with Native Debuggers - To create snapshots of a debugged program, select \uicontrol {Create Snapshot} - in the context menu in the \uicontrol {Debugger Perspectives} view. + 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. - Double-click on entries in the \uicontrol {Debugger Perspectives} view to - switch between snapshots. The debugger views are updated to reflect the state - of the program at time of taking the snapshot. + \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. +*/ - \note Creating snapshots involves creating core files of the debugged process, - requiring significant amount of disk space. For details, see - \l{https://sourceware.org/gdb/onlinedocs/gdb/Core-File-Generation.html}. +/*! + \page creator-disassembler-view.html + \previouspage creator-debugger-log-view.html + \nextpage creator-debugger-stopping.html - \endomit + \title Viewing Disassembled Code - \include creator-debugger-settings.qdocinc debugger-settings -*/ + The \uicontrol Disassembler view displays disassembled code for the current + function. + + 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. + 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 toolbar. + + 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}. +*/ /*! - \previouspage creator-debug-mode.html + \previouspage creator-debugger-preferences.html \page creator-debugging-helpers.html \nextpage creator-debugging-qml.html @@ -935,7 +1178,7 @@ \QC application package, where it is located in the \c Contents/resources/debugger folder. - The \c personaltypes.py file contains one example implementation: + The \c personaltypes.py file has one example implementation: \quotefromfile ../../../share/qtcreator/debugger/personaltypes.py \skipto qdump__ @@ -998,7 +1241,7 @@ \list - \li \c d of type \c Dumper, an object containing the current settings and + \li \c d of type \c Dumper, an object that has the current settings and providing facilities to build up an object representing a part of the \uicontrol Locals and \uicontrol Expressions views. @@ -1094,9 +1337,9 @@ As the format is not guaranteed to be stable, it is strongly recommended not to generate the wire format directly, but to use the abstraction - layer provided by the Python Dumper classes, specifically the \c{Dumper} + layer of the Python Dumper classes, specifically the \c{Dumper} class itself, and the \c{Dumper:Value} and \c{Dumper:Type} abstractions. - These provide a complete framework to take care of the \c iname and \c addr + These offer a complete framework to take care of the \c iname and \c addr fields, to handle children of simple types, references, pointers, enums, and known and unknown structs, as well as some convenience functions to handle common situations. @@ -1113,7 +1356,7 @@ \section3 Dumper Class - The \c Dumper class contains generic bookkeeping, low-level, and convenience + The \c Dumper class has generic bookkeeping, low-level, and convenience functions: \list @@ -1288,7 +1531,7 @@ built into or shipped alongside the debugged binary, or created on-the-fly by the debugging helper. - \QC uses the possibility to provide type information on-the-fly for most Qt + \QC offers type information on-the-fly for most Qt classes, obliterating the need to use \e Debug builds of Qt for the purpose of object introspection. @@ -1477,7 +1720,7 @@ inferior stopped because it received a signal from the operating system. Signal name:? signal meaning: Unknown signal.} - Some versions of Avira AntiVir Desktop-Products contain known issues in + Some versions of Avira AntiVir Desktop-Products have known issues in various development environments, including \QC. To fix the problem, Avira instructs you to update to version \c {avipbb.sys 10.0.22.22}. For more information, see @@ -1490,7 +1733,7 @@ \section1 Debugger Does Not Hit Breakpoints - You might have created a release build that does not contain debug + You might have created a release build that does not have debug information. A GNU Compiler Collection (GCC) debug build has the \c {-g} option on the compiler command line. Check that this option is present in the \l {Compile Output}. If it is not, adjust your build @@ -1571,7 +1814,7 @@ \section2 Disabling Incremental Linking - Incremental linking can affect debugging. If the debugger log contains + Incremental linking can affect debugging. If the debugger log has the \e {Unable to verify checksum of module} message, disable incremental linking. diff --git a/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc b/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc index 20c1f96c11..797788897a 100644 --- a/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc +++ b/doc/qtcreator/src/debugger/qtquick-debugger-example.qdoc @@ -10,7 +10,7 @@ /*! \page creator-qml-debugging-example.html \if defined(qtdesignstudio) - \previouspage creator-debugging-qml.html + \previouspage creator-expressions-view.html \nextpage creator-qml-performance-monitor.html \else \previouspage creator-debugging-example.html @@ -41,7 +41,7 @@ \li To look at the code that starts a new game, place a breakpoint in samegame.qml by clicking between the line number and the window - border on the line where where the \c startNewGame() function is + border on the line where the \c startNewGame() function is called (1). \image qtquick-example-setting-breakpoint1.png diff --git a/doc/qtcreator/src/debugger/qtquick-debugging.qdoc b/doc/qtcreator/src/debugger/qtquick-debugging.qdoc index 95259d6605..833cbe69c4 100644 --- a/doc/qtcreator/src/debugger/qtquick-debugging.qdoc +++ b/doc/qtcreator/src/debugger/qtquick-debugging.qdoc @@ -11,7 +11,7 @@ \page creator-debugging-qml.html \if defined(qtdesignstudio) \previouspage studio-debugging.html - \nextpage creator-qml-debugging-example.html + \nextpage creator-stack-view.html \else \previouspage creator-debugging-helpers.html \nextpage creator-debugging-example.html @@ -158,10 +158,10 @@ \list - \li \l{Setting Breakpoints}{Setting breakpoints} - \li \l{Viewing Call Stack Trace}{Viewing call stack trace} + \li \l{Setting Breakpoints}{Setting breakpoints} + \li \l{Local Variables and Function Parameters} {Viewing local variables and function parameters} @@ -169,13 +169,6 @@ \endlist - \if defined(qtdesignstudio) - \include creator-debugger-common.qdocinc debugger-breakpoints - \include creator-debugger-common.qdocinc debugger-call-stack-trace - \include creator-debugger-common.qdocinc debugger-locals - \include creator-debugger-common.qdocinc debugger-expressions - \endif - \section1 Inspecting Items While the application is running, you can use the \uicontrol {Locals} |