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.

If the debugger you want to use is not automatically detected, select Tools > Options > Build & Run > Debuggers > 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 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 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. On macOS, 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:

Supported GDB Versions

Starting with version 3.1, Qt Creator 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 device is 7.0.

Supported CDB Versions

All versions of CDB targeting platforms supported by Qt are supported by Qt Creator.

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.

Installing Native Debuggers

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

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:

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 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:

1. Select Tools > Options > Debugger > CDB Paths.

   

2. In the Symbol Paths group, select Insert.
3. Select the directory where you want to store the cached information.

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

4. Select OK.

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 Source Paths field: srv*.

Setting up FSF GDB for macOS

To use FSF GDB on macOS, 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 an LLDB Engine. If an LLDB Engine is not listed, select Manage to add it in Tools > Options > Build & Run > Debuggers. For more information, see Adding Debuggers.
4. To use the debugger, add the kit in the Build Settings of the project.