diff options
author | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2024-04-19 16:45:16 +0200 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@qt.io> | 2024-04-23 13:15:41 +0000 |
commit | 820e65894d4f8e915aa84eb7f9079bd406247c70 (patch) | |
tree | 4c8841f450f2f776e080350661dabfd41617162b /doc/qtcreator/src/debugger/creator-only | |
parent | d9c8590c5fd10b1feceb389c142ec244909739a2 (diff) |
Doc: Update debugger docs
- Make CDB and GDB preference docs more scannable by using tables.
- Describe the "Use debug info daemon" GDB option(update the screenshot).
- Add info about asynchronous GDB command execution.
- Replace "select" with "go to" for menus.
- Update some \sa links.
Change-Id: I029541b0bed284f12d6de7dbb10bbe0de05ac5c9
Reviewed-by: Christian Stenger <christian.stenger@qt.io>
Diffstat (limited to 'doc/qtcreator/src/debugger/creator-only')
-rw-r--r-- | doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc | 230 | ||||
-rw-r--r-- | doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc | 31 |
2 files changed, 151 insertions, 110 deletions
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 4dbc4a4377..b3fef5c0e3 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdoc @@ -100,45 +100,61 @@ \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} - To specify a timeout for terminating non-responsive GDB processes, set the - number of seconds to wait in the \uicontrol {GDB timeout} field. The default - value of 20 seconds should be sufficient for most applications, but if - loading big libraries or listing source files takes much longer than - that on slow machines, you should increase the value. - - To compress several steps into one step for less noisy debugging when - stepping into code, select the \uicontrol {Skip known frames when stepping} - check box. For example, the atomic reference counting code is skipped, and - a single \e {Step Into} for a signal emission ends up directly in the slot - connected to it. - - To display a message box as soon as your application receives a signal, such - as SIGSEGV, during debugging, select the \uicontrol {Show a message box when - receiving a signal} check box. - - GDB allows setting breakpoints on source lines for which no code was - generated. In such situations, the breakpoint is shifted to the next - source code line for which the code was actually generated. To reflect - such temporary changes by moving the breakpoint markers in the source - code editor, select the \uicontrol {Adjust breakpoint locations} check box. - - To specify whether the dynamic or the static type of objects will be - displayed, select the \uicontrol {Use dynamic object type for display} - check box. Keep in mind that choosing the dynamic type might be slower. - - To allow reading the user's default .gdbinit file on debugger startup, - select the \uicontrol {Load .gdbinit file on startup} check box. - - To use the default GDB pretty printers installed in your system - or linked to the libraries your application uses, select the - \uicontrol {Load system GDB pretty printers} check box. - - By default, GDB shows AT&T style disassembly. To switch to the Intel style, - select the \uicontrol {Use Intel style disassembly} check box. - - To have GDB automatically save a copy of its symbol index in a cache - on disk and retrieve it from there when loading the same binary in the - future, select the \uicontrol {Use automatic symbol cache} check box. + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {GDB timeout} + \li The timeout for terminating non-responsive GDB processes in seconds + The default value of 40 seconds should be sufficient for most + applications, but if loading big libraries or listing source files + takes much longer than that on slow machines, increase the value. + \row + \li \uicontrol {Skip known frames when stepping} + \li Compresses several steps into one step for less noisy debugging when + stepping into code. For example, the atomic reference counting code + is skipped, and a single \e {Step Into} for a signal emission ends up + directly in the slot connected to it. + \row + \li \uicontrol {Show a message box when receiving a signal} + \li Shows a message box as soon as your application receives a signal, + such as SIGSEGV, during debugging. + \row + \li \uicontrol {Adjust breakpoint locations} + \li GDB allows setting breakpoints on source lines for which no code was + generated. In such situations, the breakpoint is shifted to the next + source code line for which the code was actually generated. To reflect + such temporary changes by moving the breakpoint markers in the source + code editor, select this checkbox. + \row + \li \uicontrol {Use dynamic object type for display} + \li Whether the dynamic or the static type of objects will be + displayed. Choosing the dynamic type might make debugging slower. + \row + \li \uicontrol {Load .gdbinit file on startup} + \li Reads the user's default .gdbinit file on debugger startup. + \row + \li \uicontrol {Load system GDB pretty printers} + \li Uses the default GDB pretty printers installed on the computer + or linked to the libraries your application uses. + \row + \li \uicontrol {Use Intel style disassembly} + \li Switches from the default AT&T style disassembly to the Intel style. + \row + \li \uicontrol {Use automatic symbol cache} + \li Automatically saves a copy of the GDB symbol index in a cache on disk + and retrieves it from there when loading the same binary in the + future. + \row + \li \uicontrol {Use debug info daemon} + \li Tries to automatically retrieve debug information for system + packages. + \endtable + + \section1 Executing Additional Commands To execute GDB commands after GDB has been started, but before the debugged application is started or attached, and before the debugging helpers are @@ -163,23 +179,38 @@ Enabling them may negatively impact your debugging experience, so use them with care. - To use asynchronous mode to control the inferior, select the - respective check box. - - To add common paths to locations of debug information, such as - \c {/usr/src/debug}, when starting GDB, select the - \uicontrol {Use common locations for debug information} check box. - - To stop when \c qWarning, \c qFatal, or \c abort is called, select the - respective check box. - - To enable stepping backwards, select the \uicontrol {Enable reverse - debugging} check box. This feature is very slow and unstable on the - GDB side. It exhibits unpredictable behavior when going backwards over - system calls and is very likely to destroy your debugging session. - - To keep debugging all children after a fork, select the - \uicontrol {Debug all child processes} check box. + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Use asynchronous mode to control the inferior} + \li Execute commands in the background (asynchronous) mode. + GDB immediately opens a command prompt where you can issue + other commands while your program runs. + \row + \li \uicontrol {Use common locations for debug information} + \li Adds common paths to locations of debug information, such as + \c {/usr/src/debug}, when starting GDB. + \row + \li \uicontrol {Stop when qWarning() is called} + \li Adds a breakpoint on each \c qWarning() function. + \row + \li \uicontrol {Stop when qFatal() is called} + \li Adds a breakpoint on each \c qFatal() function. + \row + \li \uicontrol {Stop when abort() is called} + \li Adds a breakpoint on each \c abort() function. + \row + \li \uicontrol {Enable reverse debugging} + \li Enables stepping backwards. This feature is very slow and unstable + on the GDB side. It exhibits unpredictable behavior when steapping + backwards over system calls and is very likely to destroy your + debugging session. + \row + \li\uicontrol {Debug all child processes} + \li Keeps debugging all children after a fork. + \endtable \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ @@ -199,44 +230,55 @@ \image qtcreator-cdb-options.png "CDB preferences" - You can specify additional arguments for starting CDB in the - \uicontrol {Additional arguments} field. - - If a console application does not start up properly in the configured - console and the subsequent attach fails, you can diagnose the issue by - using CDB's native console. Select the \uicontrol {Use CDB console} - check box to override the console set in the Windows system - environment variables. Note that the native console does not - prompt on application exit. - - To automatically add a breakpoint on the \c CrtCbgReport() function, - select the \uicontrol {Stop when CrtCbgReport() is called} check box. - This catches runtime error messages caused by \c assert(), for example. - - In the \uicontrol {Break on} group, specify whether the debugger should - break on C++ exceptions, on thread creation or exit, on loading or - unloading the specified \l{Viewing Modules}{application modules}, or on - the specified output. - - To disable first-chance break on access violation exceptions, select the - \uicontrol {Ignore first chance access violations} check box. - The second occurrence of an access violation will break into the debugger. - - CDB enables setting breakpoints in comments or on source lines for which - no code was generated. In such situations, the breakpoint is shifted to - the next source code line for which the code was actually generated. To - reflect such temporary changes by moving the breakpoint markers in the - source code editor, select the \uicontrol {Correct breakpoint location} - check box. For more information, see \l{Setting Breakpoints}. - - 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}. - - To display information about first-chance and second-chance exceptions - in \l Issues, select the check boxes - in the \uicontrol {Add Exceptions to Issues View} group. + The following table summarizes the preferences. + + \table + \header + \li Setting + \li Value + \row + \li \uicontrol {Additional arguments} + \li Additional arguments for starting CDB. + \row + \li \uicontrol {Use CDB console} + \li If a console application does not start up properly in the configured + console and the subsequent attach fails, diagnose the issue by + using CDB's native console. Select this checkbox to override the + console set in the Windows system environment variables. Note that + the native console does not prompt on application exit. + \row + \li \uicontrol {Ignore first chance access violations} + \li Disables first-chance break on access violation exceptions. + The second occurrence of an access violation will break into the + debugger. + \row + \li \uicontrol {Stop when CrtDbgReport() is called} + \li Automatically adds a breakpoint on the \c CrtDbgReport() function to + catch runtime error messages caused by \c assert(), for example. + \row + \li \uicontrol {Correct breakpoint location} + \li CDB enables setting breakpoints in comments or on source lines for + which no code was generated. In such situations, the breakpoint is + shifted to the next source code line for which the code was actually + generated. To reflect such temporary changes by moving the breakpoint + markers in the source code editor, select this checkbox. For more + information, see \l{Setting Breakpoints}. + \row + \li \uicontrol {Use Python dumper} + \li Uses the abstraction layer of Python Dumper classes to create a + description of data items in the \uicontrol Locals and + \uicontrol Expressions views. + For more information, see \l{Debugging Helper Implementation}. + \row + \li \uicontrol {Break on} + \li Whether the debugger should break on C++ exceptions, on thread + creation or exit, on loading or unloading the specified + \l{Viewing Modules}{application modules}, or on the specified output. + \row + \li \uicontrol {Add Exceptions to Issues View} + \li Shows information about first-chance and second-chance exceptions + in \l Issues. + \endtable \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger} */ diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc index 5a5805b977..8cae9932ec 100644 --- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc +++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc @@ -118,7 +118,7 @@ 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 > + To interrupt a running C++ application, go to \uicontrol Debug > \uicontrol Interrupt. The debugger automatically interrupts the application when it hits a \l {Setting Breakpoints}{breakpoint}. @@ -581,10 +581,9 @@ \endlist - By default, a non-responsive GDB process is terminated after 20 seconds. - To increase the timeout in \uicontrol {GDB timeout}, select - \preferences > \uicontrol Debugger > - \uicontrol GDB. + By default, a non-responsive GDB process is terminated after 40 seconds. + To increase the timeout in \uicontrol {GDB timeout}, go to \preferences > + \uicontrol Debugger > \uicontrol GDB. For more information about connecting with \c {target extended-remote} mode in GDB, see \l{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html} @@ -795,7 +794,7 @@ During debugging, the mode shows the views that you usually need to debug C++ or QML applications. To show other views or to hide views, - select \uicontrol Views. + go to \uicontrol Views. You can drag the views in \QC to new positions on the screen. \QC saves the size and position of views as a perspective for future sessions. Select @@ -848,7 +847,7 @@ select \uicontrol {Close Editor Tooltips} in the context menu in the \uicontrol Locals or \uicontrol Expressions view. - To disable tooltips for performance reasons, select \preferences > + To disable tooltips for performance reasons, go to \preferences > \uicontrol Debugger > \uicontrol General > \uicontrol {Use tooltips in main editor when debugging}. @@ -906,7 +905,7 @@ classes in a useful way. To change the number of array elements that are - requested when expanding entries, select \preferences > \uicontrol {Debugging} + requested when expanding entries, go to \preferences > \uicontrol {Debugging} > \uicontrol {Locals & Expressions} > \uicontrol {Default array size}. @@ -1067,7 +1066,7 @@ If an instance of a class is derived from QObject, you can find all other objects connected to this object's slots with Qt's signals and slots - mechanism. Select \preferences > \uicontrol {Debugging} > + mechanism. Go to \preferences > \uicontrol {Debugging} > \uicontrol {Locals & Expressions} > \uicontrol {Use Debugging Helpers}. \image qtcreator-debugging-helper-options.webp {Locals & Expressions preferences} @@ -1197,7 +1196,7 @@ When using CDB as debug backend, you can specify that the debugger should break when application modules are loaded or unloaded. To enable breaking - for the specified modules, select \preferences > \uicontrol Debugger > + for the specified modules, go to \preferences > \uicontrol Debugger > \uicontrol CDB. \image qtcreator-cdb-options.png {CDB tab in Debugger preferences} @@ -1426,13 +1425,13 @@ \image qtcreator-debugger-disassembler-view.webp {Disassembler view} By default, GDB shows AT&T style disassembly. To switch to the Intel style, - select \preferences > \uicontrol Debugger > + go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Use Intel style disassembly}. To open the \uicontrol Disassembler view: \list - \li Select \uicontrol Debug > \uicontrol {Operate by Instruction} while + \li Go to \uicontrol Debug > \uicontrol {Operate by Instruction} while the debugger is running. \li Select the \inlineimage icons/debugger_singleinstructionmode.png (\uicontrol {Operate by Instruction}) tool button on the debugger @@ -1487,7 +1486,7 @@ You can have commands executed after built-in debugging helpers have been loaded and fully initialized. To load additional debugging helpers or - modify existing ones, select \preferences > \uicontrol Debugger > + modify existing ones, go to \preferences > \uicontrol Debugger > \uicontrol {Locals & Expressions}, and enter the commands in the \uicontrol {Debugging Helper Customization} field. @@ -1509,7 +1508,7 @@ \endcode To display a message box as soon as your application receives a signal - during debugging, select \preferences > \uicontrol Debugger > \uicontrol GDB > + during debugging, go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Show a message box when receiving a signal}. \section1 Adding Custom Debugging Helpers @@ -2111,7 +2110,7 @@ \li Make sure the debugger is \l{Supported Native Debuggers}{set up properly}. - \li In the \uicontrol Debug mode, select \uicontrol View > + \li In the \uicontrol Debug mode, go to \uicontrol View > \uicontrol Views > \uicontrol {Debugger Log} to open the \l {Debugger Log} view. Browse the contents of the pane on the right hand side to find out what went wrong. Always attach the @@ -2151,7 +2150,7 @@ When using GDB as backend, you can automatically save a copy of its symbol index in a cache on disk and retrieve it from there - when loading the same binary in the future. Select \preferences > + when loading the same binary in the future. Go to \preferences > \uicontrol Debugger > \uicontrol GDB > \uicontrol {Use automatic symbol cache}. \image qtcreator-preferences-debugger-gdb.webp {GDB preferences} |