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

/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** 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.
**
**
****************************************************************************/

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


/*!
    \contentspage {Qt Creator Manual}
    \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 {Build and Run} > \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 {Build & Run} >
    \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 the Symbol
    Server in Windows}.

    \note To use the Free Software Foundation (FSF) version of GDB on
    OS X, 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

    Qt Creator 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 OS X, the LLDB
    debugger can be used. Basic support for LLDB is also available on Linux,
    but it is restricted by LLDB's capabilities there, and considered
    experimental.

    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 (experimental)
        \row
            \li Unix
            \li GCC, ICC
            \li GDB
        \row
            \li OS X
            \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 minimal supported version is GDB 7.4.1,
    using Python version 2.6, 2.7, or 3.x.

    For remote debugging using GDB and GDB server, the minimal
    supported version of GDB server on the target 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 OS X for supporting C++ on the
    desktop. LLDB is typically used with the Clang compiler (even though you
    can use it with GCC, too).

    You can use the LLDB version delivered with Xcode, but we recommend that you
    build it from sources using Xcode. The minimal supported version is LLDB
    179.5.

    \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

    Check the table below for the supported versions and other important
    information about installing native debuggers.

    \table
        \header
            \li Native Debugger
            \li Notes
        \row
            \li GDB
            \li On Windows, use the Python-enabled GDB versions 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. Follow the instructions in
                \l{http://wiki.qt.io/QtCreator_Build_Gdb}
                {Building GDB}.
                Builds of GDB shipped with Xcode on OS X are no longer
                supported.

        \row
            \li Debugging tools for Windows
            \li To use the CDB debugger, you must install the
                \e{Debugging tools for Windows}. You can download them from
                \l{http://msdn.microsoft.com/en-us/windows/hardware/gg463009/}
                {Download and Install Debugging Tools for Windows}.

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

                The pre-built \QSDK for Windows makes use of the library if it
                is present on the system. 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 the Symbol Server in Windows}.

       \row
            \li Debugging tools for OS X
            \li 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 OS X,
                see: \l{http://developer.apple.com/library/mac/#technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391}
                {Mac OS X Debugging Magic}.

       \row
            \li LLDB
            \li We recommend using the LLDB version that is delivered with Xcode 5.
    \endtable

    \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 where 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 the Symbol Server in 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.

        \li In the \uicontrol {Symbol paths} field, open the \uicontrol Insert
            menu and select \uicontrol{Symbol Server}.

        \li Select a directory where you want to store the cached information
            and click \uicontrol OK.

            Use a subfolder in a temporary directory, such as
            \c {C:\temp\symbolcache}.

    \endlist

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

    \note The first time you start debugging by using the Debugging tools for
    Windows, \QC prompts you to add the Symbol Server.

    \section1 Setting up FSF GDB for OS X

    To use FSF GDB on OS X, 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 >
            Certificate Assistant > 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 > 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 {Qt Creator > Preferences > Build & Run >
            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

    \section1 Setting Up Experimental LLDB Support

    To use the experimental interface to LLDB, you must set up a kit that uses
    the LLDB engine and select the kit for your project:

    \list 1

        \li Select \uicontrol Tools > \uicontrol Options >
            \uicontrol {Build & Run} > \uicontrol Kits.

        \li Select an automatically created kit in the list, and then select
            \uicontrol Clone to create a copy of the kit.

        \li In the \uicontrol Debugger field, select an LLDB Engine. If an LLDB Engine
            is not listed, select \uicontrol Manage to add it in \uicontrol Tools >
            \uicontrol Options > \uicontrol {Build & Run} > \uicontrol Debuggers. For more
            information, see \l {Adding Debuggers}.

        \li To use the debugger, add the kit in the \uicontrol {Build Settings}
            of the project.

    \endlist

*/