Doc: Describe debugger general and CDB settings

Task-number: QTCREATORBUG-24500
Change-Id: I9085dfdca1b59796a1ccba6db379eaa8559e724c
Reviewed-by: hjk <hjk@qt.io>

4 files changed, 118 insertions, 4 deletions

diff --git a/doc/qtcreator/images/qtcreator-cdb-options.png b/doc/qtcreator/images/qtcreator-cdb-options.png
new file mode 100644
index 0000000000..2e8211452b
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-cdb-options.png
diff --git a/doc/qtcreator/src/debugger/creator-debugger-common.qdocinc b/doc/qtcreator/src/debugger/creator-debugger-common.qdocinc
index e5366aa968..65e3bd226e 100644
--- a/doc/qtcreator/src/debugger/creator-debugger-common.qdocinc
+++ b/doc/qtcreator/src/debugger/creator-debugger-common.qdocinc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -61,7 +61,7 @@
 
     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. I has two states:
+    program 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
@@ -145,6 +145,35 @@
 
     \endlist
 
+    \section2 Specifying Breakpoint Settings
+
+    You can specify settings for breakpoints in \uicontrol Tools >
+    \uicontrol Options > \uicontrol Debugger. For more information,
+    see \l{Specifying Debugger Settings}.
+
+    To use a full absolute path in breakpoints, select the
+    \uicontrol {Set breakpoints using a full absolute path} check box.
+
+    GDB and CDB enable setting breakpoints on source lines for which no code
+    was generated. In such situations, the breakpoint is shifted to the next
+    source code line for which the code was actually generated. To reflect
+    such temporary changes by moving the breakpoint markers in the source code
+    editor, select \uicontrol GDB > \uicontrol {Adjust breakpoint locations}
+    or \uicontrol CDB > \uicontrol {Correct breakpoint location}.
+
+    When using CDB as backend, you can specify that the debugger should break on
+    specific events, such as C++ exceptions, thread creation or exit, loading or
+    unloading \l{Viewing Modules}{application modules}, or particular output.
+    Select the appropriate check boxes in the \uicontrol CDB >
+    \uicontrol {Break on} group. To disable first-chance break on access
+    violation exceptions, select the \uicontrol {Ignore first chance access
+    violations} check box. The second occurrence of an access violation will
+    break into the debugger.
+
+    You can automatically add breakpoints on some functions to catch error
+    and warning messages. For more information, see \l{Specifying CDB Settings}
+    and \l{Specifying Extended 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.
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 04b5d70f5d..75e9c31873 100644
--- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc
+++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc
@@ -325,6 +325,53 @@
     To keep debugging all children after a fork, select the
     \uicontrol {Debug all child processes} check box.
 
+    \section2 Specifying CDB Settings
+
+    To specify settings for managing the CDB process, select \uicontrol Tools >
+    \uicontrol Options > \uicontrol Debugger > \uicontrol CDB.
+
+    \image qtcreator-cdb-options.png "CDB options"
+
+    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 provided by Python Dumper
+    classes to create a description of data items displayed
+    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 add information about first-chance and second-chance exceptions
+    to the \uicontrol Issues output pane, select the check boxes
+    in the \uicontrol {Add Exceptions to the Issues View} group.
+
     \section1 Mapping Source Paths
 
     To enable the debugger to step into the code and display the source code
diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
index b1f1ede711..e95067dae3 100644
--- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
+++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
@@ -118,10 +118,15 @@
     The debugger then takes over and starts the program 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
+    attached in \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
+    \uicontrol GDB and \uicontrol CDB. For more information, see
+    \l{Specifying Debugger 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.
 
-
     \section1 Launching the Debugger in Different Modes
 
     The debugger plugin can run the native debuggers in various operating modes
@@ -171,6 +176,13 @@
     \uicontrol {Run Settings} and select the \uicontrol {Run in terminal} check
     box.
 
+    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 \uicontrol Tools > \uicontrol Options >
+    \uicontrol Debugger > \uicontrol CDB > \uicontrol {Use CDB console} to
+    override the console set in the Windows system environment variables.
+    Note that the native console does not prompt on application exit.
+
     To launch the debugger in Start Internal mode, click the
     \uicontrol {Start Debugging} button for the active project.
 
@@ -596,6 +608,23 @@
     It is also possible to continue executing the program until the current
     function completes or jump to an arbitrary position in the current function.
 
+   \section2 Customizing Debug Views
+
+    You can change the appearance and behavior of the debug views by specifying
+    settings in \uicontrol Options > \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
@@ -691,6 +720,12 @@
 
     By default, the \uicontrol Modules view is hidden.
 
+    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 Tools > \uicontrol Options >
+    \uicontrol Debugger > \uicontrol CDB. For more information, see
+    \l{Specifying CDB Settings}.
+
     \section2 Viewing Source Files
 
     The \uicontrol {Source Files} view lists all the source files included in
@@ -991,12 +1026,15 @@
     not to generate the wire format directly, but to use the abstraction
     layer provided by 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
     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.
 
+    When using CDB as debugger backend, you can enable the Python dumper by
+    selecting \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
+    \uicontrol CDB > \uicontrol {Use Python dumper}.
+
     \section3 Dumper Class
 
     The \c Dumper class contains generic bookkeeping, low-level, and convenience