// 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-reference.html

    \ingroup creator-reference-preferences-debugger

    \title General

    \brief Customize debug views and map source paths.

    To set general preferences that are common to all debuggers, go to
    \preferences > \uicontrol Debugger > \uicontrol General.

    \image qtcreator-preferences-debugger-general.webp {Debugger General preferences}

    You can customize the appearance and behavior of the debug views and
    setting breakpoints, as well as map source paths to target paths.

    You can view debug output in the \l {Debugger Log} view.
    However, in some Linux distributions, such as Arch Linux, debug
    output is sent to the system log. To override this behavior, select
    \uicontrol {Force logging to console}. This sets
    \c QT_LOGGING_TO_CONSOLE=1 in the environment of the debugged
    application, which effectively prevents storing debug output in
    system logs.

    \section1 Breakpoints

    To use a full absolute path in breakpoints, select
    \uicontrol {Set breakpoints using a full absolute path}.

    GDB and CDB enable setting breakpoints on source lines for which no code
    was generated. In such situations, the breakpoint is shifted to the next
    source code line for which the code was actually generated. To reflect
    such temporary changes by moving the breakpoint markers in the source code
    editor, select \uicontrol GDB > \uicontrol {Adjust breakpoint locations}
    or \uicontrol CDB > \uicontrol {Correct breakpoint location}.

    When using GDB as backend, you can extend the ordinary GDB
    breakpoint class by using Python. Select \uicontrol GDB >
    \uicontrol {Use pseudo message tracepoints}.

    When using CDB as backend, you can specify that the debugger should break on
    specific events, such as C++ exceptions, thread creation or exit, loading or
    unloading \l{Viewing Modules}{application modules}, or particular output by
    selecting preferences in \uicontrol CDB > \uicontrol {Break on}. To disable
    first-chance break on access violation exceptions, select
    \uicontrol {Ignore first chance access violations}.
    The second occurrence of an access violation will break into the debugger.

    You can automatically add breakpoints on some functions to catch error
    and warning messages. For more information, see \l{CDB} and \l{GDB}.

    For more information on breakpoints, see
    \l{http://sourceware.org/gdb/onlinedocs/gdb/Breakpoints.html#Breakpoints}
    {Breakpoints, Watchpoints, and Catchpoints} in GDB documentation.

    \section1 Source Paths Mapping

    To enable the debugger to step into the code and display the source code
    when using a copy of the source tree at a location different from the one
    at which the libraries were built, you can map source paths to target
    paths.

    To automatically map the source paths to a Qt version that has not been
    patched, select \uicontrol {Add Qt Sources} and browse to the location
    of the Qt source files.

    To manually map the source paths to target paths:

    \list 1
        \li In \uicontrol {Source Paths Mapping}, select \uicontrol Add to add
            an entry to the path list.
        \li In \uicontrol {Source path}, specify the source path in
            the debug information of the executable as reported by the debugger.
        \li In \uicontrol {Target path}, specify the actual location
            of the source tree on the local machine.
    \endlist

    \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}
*/

/*!
    \page creator-preferences-debugger-gdb.html
    \previouspage creator-reference.html

    \ingroup creator-reference-preferences-debugger

    \title GDB

    \brief Manage the GDB process.

    To specify preferences for managing the GDB process, go to \preferences >
    \uicontrol Debugger > \uicontrol GDB.

    \image qtcreator-preferences-debugger-gdb.webp {GDB preferences}

    The following table summarizes the preferences.

    \table
    \header
        \li Preference
        \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
    initialized, enter them in \uicontrol {Additional Startup Commands}.

    To execute GDB commands after GDB has successfully attached to remote
    targets, enter them in \uicontrol {Additional Attach Commands}.
    You can add commands to further set up the target here, such as
    \c {monitor reset} or \c {load}.

    To execute simple Python commands, prefix them with \c python. To execute
    sequences of Python commands spanning multiple lines, prepend the block
    with \c python  on a separate line, and append \c end on a separate line.
    To execute arbitrary Python scripts, use
    \c {python execfile('/path/to/script.py')}.

    \section1 Extended GDB Preferences

    The preferences 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.

    \table
    \header
        \li Preference
        \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}
*/

/*!
    \page creator-preferences-debugger-cdb.html
    \previouspage creator-reference.html

    \ingroup creator-reference-preferences-debugger

    \title CDB

    \brief Manage the CDB process.

    To set preferences for managing the CDB process, go to \preferences >
    \uicontrol Debugger > \uicontrol CDB.

    \image qtcreator-preferences-debugger-cdb.webp {CDB preferences}

    The following table summarizes the preferences.

    \table
    \header
        \li Preference
        \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 {Enable heap debugging}
        \li Allocates memory using the debug heap rather than the normal heap.
            The debug heap has checks that help diagnose heap related bugs, but
            negatively impacts performance when allocating memory in the debugged
            process.
    \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}
*/

/*!
    \page creator-preferences-debugger-cdb-paths.html
    \previouspage creator-reference.html

    \ingroup creator-reference-preferences-debugger

    \title CDB Paths

    \brief Add the Microsoft Symbol Server to the symbol search path of the
    debugger.

    To obtain debugging information for the operating system libraries for
    debugging Windows applications, add the Microsoft Symbol Server
    to the symbol search path of the debugger:

    \list 1
        \li Go to \preferences > \uicontrol Debugger > \uicontrol {CDB Paths}.
            \image qtcreator-debugger-cdb-paths.png
        \li In the \uicontrol {Symbol Paths} group, select \uicontrol Insert.
        \li Select the directory where you want to store the cached information.
            Use a subfolder in a temporary directory, such as
            \c {C:\temp\symbolcache}.
        \li Select \uicontrol OK.
    \endlist

    \note Populating the cache might take a long time on a slow network
    connection.

    To use the Source Server infrastructure for fetching missing source files
    directly from version control or the web, enter the following string in
    \uicontrol {Source Paths}: \c srv*.

    \sa {Debug}{How To: Debug}, {Debugging}, {Debuggers}, {Debugger}
*/
