Qt Creator Manual

Setting Up Debugger

The main debugger settings are associated with the kit you build and run your project with. To specify the debugger and compiler to use for each kit, select Tools > Options > Build and Run > 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 kit, you can Clone the kit and change the parameters in the clone. Make sure to select the cloned kit for your project.

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 Setting the Symbol Server in Windows.

Note: To use the Free Software Foundation (FSF) version of GDB on Mac OS, you must sign it and modify your 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 Launching the Debugger in Different Modes.

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. There is also an incomplete experimental interface to LLDB on Mac OS and Linux available when building Qt Creator from source.

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

PlatformCompilerNative Debugger
Mac OS XGCC, ClangApple GDB, FSF GDB (experimental), LLDB (experimental)
Windows/MSVCMicrosoft Visual C++ CompilerDebugging Tools for Windows/CDB
Maemo, MeeGoGCCGDB

Supported GDB Versions

GDB comes in two varieties with common roots.

One is used on Mac OS X and does not support Python as scripting language. The minimal supported versions in is GDB 6.3.50-20050815, build 1469.

The second is maintained by the Free Software Foundation, and can use Python as scripting language. The minimal supported version in this case is FSF GDB 7.4.1, using Python version 2.6 or 2.7. Note that Python 3.x is not supported by GDB.

The Python enabled versions are very convenient to interface, and much of Qt Creator's advanced data display options depend on the availability of Python scripting. Since Python enabled versions of GDB are bundled with all recent Linux versions, active support for non-Python builds has been dropped for platforms other than Mac OS X.

The non-Python versions use the compiled version of the debugging helpers, that you must enable separately. For more information, see Debugging Helpers Based on C++.

The Python version uses a script version of the debugging helpers that does not need any special setup.

FSF GDB can also be compiled for Mac OS, but the build is currently unstable, and thererefore, this is not recommended.

Supported CDB Versions

The CDB native debugger has similar functionality to the non-Python GDB debugger engine. Specifically, it also uses compiled C++ code for the debugging helper library.

Supported LLDB Versions

The LLDB native debugger has similar functionality to the GDB debugger. LLDB is the default debugger in Xcode on Mac 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 300.99.

Installing Native Debuggers

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

Native DebuggerNotes
GDBOn Linux and Windows, use the Python-enabled GDB versions that are installed when you install Qt Creator and Qt SDK. On Mac OS X, use the GDB provided with Xcode. You can also build your own Python-enabled GDB. Follow the instructions in Building GDB.
Debugging tools for WindowsTo use this engine, you must install the Debugging tools for Windows. You can download them from 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 Qt SDK for Windows makes use of the library if it is present on the system. When manually building Qt Creator using the Microsoft Visual C++ Compiler, the build process checks for the required files in "%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 Setting the Symbol Server in Windows.

Debugging tools for Mac OS XThe 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 Qt Creator, you can set a flag in your run configuration, in Projects mode. In the run configuration, select Use debug version of frameworks.

For more detailed information about debugging on the Mac OS X, see: Mac OS X Debugging Magic.

Note: The Mac OS X Snow Leopard (10.6) has a bug that might cause the application to crash. For a workaround, see: QTBUG-4962.

LLDBAn LLDB version is delivered with Xcode, but we recommend that you build LLDB from sources using Xcode.

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:

  1. Select Tools > Options > Debugger > General > Add.
  2. In the Source path field, specify the source path in the debug information of the executable as reported by the debugger.
  3. In the Target path field, specify the actual location of the source tree on the local machine.

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:

  1. Select Tools > Options > Debugger > CDB.
  2. In the Symbol paths field, open the Insert menu and select Symbol Server.
  3. Select a directory where you want to store the cached information and click OK.

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

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, Qt Creator prompts you to add the Symbol Server.

Setting up FSF GDB for Mac OS

To use FSF GDB on Mac OS, you must sign it and add it to the Qt Creator kits.

  1. To create a key for signing FSF GDB, select Keychain Access > Certificate Assistant > Create a Certificate:
    1. In the Name field, input fsfgdb to replace the existing content.
    2. In the Certificate Type field, select Code Signing.
    3. Select the Let me override defaults check box.
    4. Select Continue, and follow the instructions of the wizard (use the default settings), until the Specify a Location For The Certificate dialog opens.
    5. In the Keychain field, select System.
    6. Select Keychain Access > System, and locate the certificate.
    7. Double click the certificate to view certificate information.
    8. In the Trust section, select Always Trust in the When using this certificate field, and then close the dialog.
  2. To sign the binary, enter the following command in the terminal:
     codesign -f -s "fsfgdb" $INSTALL_LOCATION/fsfgdb
  3. In Qt Creator, select Qt Creator > Preferences > Build & Run > Kits > Add to create a kit that uses FSF GDB.
  4. In the Debugger field, specify the path to FSF GDB ($HOME/gdb72/bin/fsfgdb, but with an explicit value for $HOME).
  5. To use the debugger, add the kit in the Build Settings of the project.

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:

  1. Select Tools > Options > Build & Run > Kits.
  2. Select an automatically created kit in the list, and then select Clone to create a copy of the kit.
  3. In the Debugger field, select Edit to change the automatically detected debugger to LLDB Engine.
  4. In the Engine field, select LLDB Engine.
  5. Select Choose to set the path to the LLDB engine in the Binary field.
  6. To use the debugger, add the kit in the Build Settings of the project.