path: root/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc

/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/

// **********************************************************************
// 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.
// **********************************************************************


/*!
    \previouspage creator-debugging.html
    \page creator-debugger-engines.html
    \nextpage creator-debugger-operating-modes.html

    \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
    specify the debugger and compiler to use for each kit, select
    \uicontrol Tools > \uicontrol Options > \uicontrol Kits.

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

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

    If the debugger you want to use is not automatically detected, select
    \uicontrol Tools > \uicontrol Options > \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}.

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

    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.

    For more information on the debugger modes, see
    \l{Launching the Debugger in Different 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.

    The following table summarizes the support for debugging C++ code:

    \table
        \header
            \li Platform
            \li Compiler
            \li Native 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, FSF GDB (experimental)
        \row
            \li Windows/\MinGW
            \li GCC
            \li GDB
        \row
            \li Windows/MSVC
            \li Microsoft Visual C++ Compiler
            \li Debugging Tools for Windows/CDB
    \endtable

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

    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.

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

    On Linux, the minimum supported version is LLDB 3.8.

    \omit

    \section2 GDB Adapter Modes

    [Advanced Topic]

    The GDB native debugger used internally by the debugger plugin runs in
    different adapter modes to cope with the variety of supported platforms and
    environments. All GDB adapters inherit from  AbstractGdbAdapter:

    \list

        \li PlainGdbAdapter debugs locally started GUI processes. It is
            physically split into parts that are relevant only when Python is
            available, parts relevant only when Python is not available, and
            mixed code.

        \li TermGdbAdapter debugs locally started processes that need a console.

        \li AttachGdbAdapter debugs local processes started outside \QC.

        \li CoreGdbAdapter debugs core files generated from crashes.

        \li RemoteGdbAdapter interacts with the GDB server running on Linux.

    \endlist

    \endomit

    \section1 Installing Native Debuggers

    The following sections provide information about installing native
    debuggers.

    \section2 GDB

    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.

    \section2 Debugging Tools for Windows

    To use the CDB debugger, you must install the
    \e{Debugging tools for Windows}. You can download them from
    \l{https://developer.microsoft.com/windows/downloads/windows-10-sdk}
    {Download and Install Debugging Tools for Windows} as part of the Windows
    SDK.

    \note Visual Studio does not include the Debugging tools needed,
    and therefore, you must install them separately.

    In addition, you must select \uicontrol {\QC CDB Debugger Support}
    (in \uicontrol Qt > \uicontrol Tools > \uicontrol {\QC}) when you install
    Qt or the stand-alone \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"}.

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

    \section2 LLDB

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

    \section1 Specifying Debugger Settings

    To specify settings for managing debugger processes, select \uicontrol Tools
     > \uicontrol Options > \uicontrol Debugger. In the \uicontrol General tab,
     you can specify settings that are common to all debuggers.

     \image qtcreator-debugger-general-options.png

    \section2 Specifying GDB Settings

    To specify settings for managing the GDB process, select \uicontrol Tools >
    \uicontrol Options > \uicontrol Debugger > \uicontrol GDB.

    \image qtcreator-gdb-options.png "GDB options"

    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 execute GDB commands after GDB has been started, but before the debugged
    program is started or attached, and before the debugging helpers are
    initialized, enter them in the \uicontrol {Additional Startup Commands}
    field.

    To execute GDB commands after GDB has successfully attached to remote
    targets, enter them in the \uicontrol {Additional Attach Commands} field.
    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')}.

    \section2 Specifying Extended GDB Settings

    To specify extended settings for GBD, select \uicontrol Tools >
    \uicontrol Options > \uicontrol Debugger > \uicontrol {GDB Extended}.
    The settings 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 options"

    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.

    \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
    when using a copy of the source tree at a location different from the one
    at which the libraries were built, map the source paths to target paths:

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
            \uicontrol General > \uicontrol Add.

        \li In the \uicontrol {Source path} field, specify the source path in
            the debug information of the executable as reported by the debugger.

        \li In the \uicontrol {Target path} field, specify the actual location
            of the source tree on the local machine.

    \endlist

    \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
    to the symbol search path of the debugger:

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options > \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
    the \uicontrol {Source Paths} field: \c srv*.

    \section1 Setting up FSF GDB for \macos

    To use FSF GDB on \macos, you must sign it and add it to the \QC
    \l{glossary-buildandrun-kit}{kits}.

    \list 1

        \li To create a key for signing FSF GDB, select
            \uicontrol {Keychain Access} > \uicontrol {Certificate Assistant} >
            \uicontrol {Create a Certificate}:

        \list 1

            \li In the \uicontrol Name field, input \uicontrol fsfgdb to
                replace the existing content.

            \li In the \uicontrol {Certificate Type} field, select
                \uicontrol {Code Signing}.

            \li Select the \uicontrol {Let me override defaults} check box.

            \li Select \uicontrol Continue, and follow the instructions of the
                wizard (use the default settings), until the
                \uicontrol {Specify a Location For The Certificate} dialog
                opens.

            \li In the \uicontrol Keychain field, select \uicontrol System.

            \li Select \uicontrol {Keychain Access} > \uicontrol System, and
                locate the certificate.

            \li Double click the certificate to view certificate information.

            \li In the \uicontrol Trust section, select
                \uicontrol {Always Trust} in the
                \uicontrol {When using this certificate} field, and then close
                the dialog.

        \endlist

        \li To sign the binary, enter the following command in the terminal:

            \code
            codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb
            \endcode

        \li In \QC, select \uicontrol {\QC} > \uicontrol Preferences >
            \uicontrol Kits > \uicontrol Add to
            create a kit that uses FSF GDB.

            \li In the \uicontrol Debugger field, specify the path to FSF GDB
                (\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}
            of the project.

    \endlist
*/