Qt Creator Manual

Setting Up Debugger

Note: The information in this section applies only to debugging the C++ language.

Typically, the interaction between Qt Creator and the native debugger is set up automatically and you do not need to do anything. However, you might have an unsupported GDB version installed, your Linux environment might not have GDB installed at all, or you might want to use the debugging tools for Windows.

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) GDB on Mac OS, you must sign it and add it to Qt Creator as a tool chain.

This section explains the options you have for debugging C++ code and provides installation notes for the supported native debuggers.

Supported Native Debugger Versions

The debugger plugin supports different builds of the GDB debugger, both with and without the ability to use Python scripting. Use a Python enabled version if one is available. On Windows, Symbian, Maemo, and MeeGo Harmattan, only the Python version is supported.

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.

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

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

PlatformCompilerNative DebuggerPythonDebugger Modes
LinuxGCCGDBYesPlain, Terminal, Attach, Remote, Core
UnixGCCGDBYesPlain, Terminal, Attach, Remote, Core
Mac OS/GDBGCCGDBNoPlain, Terminal, Attach, Core
Mac OS/FSF GDB (experimental)GCCFSF GDBYesPlain, Terminal, Attach, Core
Windows/MinGWGCCGDBYesPlain, Terminal, Attach, Remote, Core
Windows/MSVCMicrosoft Visual C++ CompilerDebugging Tools for Windows/CDBNot applicablePlain, Terminal, Attach, Post-Mortem
MeeGo HarmattanGCCGDBYesOn-device

For more information on the debugger modes, see Launching the Debugger in Different Modes.

Installing Native Debuggers

There are various reasons why the debugger plugin may fail to automatically pick up a suitable native debugger. The native debugger might be missing (which is usually the case for the CDB debugger on Windows which always needs to be installed manually by the user) or the installed version is not supported. 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. For a custom target, you can build your own Python-enabled GDB. Follow the instructions on Building GDB. You must use at least Python version 2.5, but we recommend that you use version 2.6.
Debugging tools for WindowsUsing this engine requires you to install the Debugging tools for Windows http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx or http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx package (Version 6.12 for the 32-bit or the 64-bit version of Qt Creator, respectively), which are freely available for download from the Microsoft Developer Network.

The Qt Creator help browser does not allow you to download files, and therefore, you must copy the above links to a browser.

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.

You can download an experimental version of FSF GDB that supports Python from ftp://ftp.qt.nokia.com/misc/gdb/7.2/gdb72_mac_platform.tar.bz2. To use FSF GDB on Mac OS, you must sign it and add it to the Qt Creator tool chains. For more information, see Setting up FSF GDB for Mac OS.

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.

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 tool chains.

  1. To create a key for signing FSF GDB, select Keychain Access > Certificate Assistant > Create a Certificate:
    1. In the Certificate Type field, select Code Signing.
    2. Select the Let me override defaults check box.
    3. Select Continue, and follow the instructions of the wizard (use the default settings), until the Select a Location for the Certificate dialog opens.
    4. In the Keychain field, select System.
    5. Select Keychain Access > System, and locate the certificate.
    6. Double click the certificate to view certificate information.
    7. In the Trust field, select Always Trust.
  2. To sign the binary, enter the following command in the terminal, where $USER is the name of the certificate (which is the same as the user name, by default):
     codesign -f -s "$USER" $INSTALL_LOCATION/fsfgdb
  3. In Qt Creator, select Qt Creator > Preferences > Build & Run > Tool Chains, to add a tool chain that uses the debugger:
    1. Select a native tool chain (usually, a x86 64-bit tool chain) and click Clone to clone it.
    2. In the Debugger field, specify the path to FSF GDB ($HOME/gdb72/bin/fsfgdb, but with an explicit value for $HOME).
  4. To use the debugger, select the tool chain in the Tool chain field in the Build Settings of the project.