// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************


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

    \ingroup creator-reference-debugger

    \title Supported Debuggers

    \brief Summary of supported debugger versions.

    You can use \QC to debug compiled code.
    On most supported platforms, you can use the GNU Symbolic Debugger (GDB).
    On Microsoft Windows, when using the Microsoft toolchain, 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:

    \table
        \header
            \li Platform
            \li Compiler
            \li Debugger
        \row
            \li Linux
            \li GCC, ICC
            \li GDB, LLDB
        \row
            \li Unix
            \li GCC, ICC
            \li GDB
        \row
            \li \macos
            \li GCC, Clang
            \li LLDB
        \row
            \li Windows/\MinGW
            \li GCC
            \li GDB
        \row
            \li Windows/MSVC
            \li Microsoft Visual C++ Compiler
            \li Debugging Tools for Windows/CDB
    \endtable

    \QC automatically selects a suitable debugger for
    each \l{Kits}{kit} from the ones found on the computer. The automatic
    setup fails if the debugger is not installed on the computer or
    if \QC does not support the installed version.

    \section1 GDB Versions

    Use GDB 7.5, or later, with the Python scripting extension and Python version
    3.7, 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.

    On Windows, use the Python-enabled GDB version that is bundled
    with the Qt package or comes with recent versions of \MinGW. On
    most Linux distributions, the GDB builds shipped with the system
    are sufficient.

    You can also build your own GDB, as instructed in
    \l{http://wiki.qt.io/QtCreator_Build_Gdb}{Building GDB}.

    Builds of GDB shipped with Xcode on \macos are no longer supported.

    \section1 Debugging Tools for Windows

    \QC supports all versions of CDB targeting platforms that Qt supports.

    To use the CDB debugger, install the \e {Debugging Tools for Windows} when
    you install \QC either by using \QOI (in \uicontrol Qt
    > \uicontrol Tools > \uicontrol {\QC}) or by using the stand-alone \QC
    installation packages.

    The 32-bit CDB version can only debug 32-bit executables, whereas the 64-bit
    version can debug both 64-bit and 32-bit executables. However, interrupting a
    32-bit executable with a 64-bit debugger can result in a stack trace of the
    WOW64 emulator 32-bit emulation layer being displayed.

    \QC extends the command-line debugger by loading the
    \c qtcreatorcdbext.dll extension library into it. The
    library must be available in the \c {libs\qtcreatorcdbext64}
    and \c {libs\qtcreatorcdbext32} folder. To install it there,
    select \uicontrol {\QC CDB Debugger Support} when you install \QC.

    When manually building \QC using
    the Microsoft Visual C++ Compiler, the build process checks for
    the required files in
    \c{"%ProgramFiles%\Debugging Tools for Windows"}.

    \section1 Debugging Tools for \macos

    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 \e debug because \e release is the default
    library.

    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}.

    For more detailed information about debugging on \macos,
    see: \l{http://developer.apple.com/library/mac/#technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391}
    {Mac OS X Debugging Magic}.
    \section1 LLDB Versions

    The LLDB debugger has similar functionality to the GDB debugger. LLDB
    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. You need a LLDB version built
    with Python support.

    We recommend using the LLDB version that is delivered with the latest Xcode.

    On Linux, the minimum supported version is LLDB 3.8.

    \section1 PDB Versions

    \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 {Tutorial: Qt Widgets and Python}{pyproject.toml}
    configuration file.

    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}

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