- Qt Creator Manual
- Setting Up Debugger
- Qt Creator Manual 4.13.0

Debugging ◦ Launching the Debugger

# 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 > 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 > Kits > 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 and Linux, the LLDB debugger can be used.

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

Platform | Compiler | Native Debugger
--- | --- | ---
Linux | GCC, ICC | GDB, LLDB
Unix | GCC, ICC | GDB
macOS | GCC, Clang | LLDB, FSF GDB (experimental)
Windows/MinGW | GCC | GDB
Windows/MSVC | Microsoft Visual C++ Compiler | Debugging Tools for Windows/CDB

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

The following sections provide information about installing native debuggers.

### 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 Building GDB.

Builds of GDB shipped with Xcode on macOS are no longer supported.

### Debugging Tools for Windows

To use the CDB debugger, you must install the Debugging tools for Windows. You can download them from 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 Qt Creator CDB Debugger Support (in Qt > Tools > Qt Creator) when you install Qt or the stand-alone Qt Creator.

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 CDB Paths on Windows.

### 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 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 macOS, see: Mac OS X Debugging Magic.

### LLDB

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

## Specifying Debugger Settings

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

### Specifying GDB Settings

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

To specify a timeout for terminating non-responsive GDB processes, set the number of seconds to wait in the 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 Skip known frames when stepping check box. For example, the atomic reference counting code is skipped, and a single 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 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 Adjust breakpoint locations check box.

To specify whether the dynamic or the static type of objects will be displayed, select the 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 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 Load system GDB pretty printers check box.

By default, GDB shows AT&T style disassembly. To switch to the Intel style, select the 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 Additional Startup Commands field.

To execute GDB commands after GDB has successfully attached to remote targets, enter them in the Additional Attach Commands field. You can add commands to further set up the target here, such as `monitor reset` or `load`.

To execute simple Python commands, prefix them with `python`. To execute sequences of Python commands spanning multiple lines, prepend the block with `python` on a separate line, and append `end` on a separate line. To execute arbitrary Python scripts, use `python execfile('/path/to/script.py')`.

### Specifying Extended GDB Settings

To specify extended settings for GBD, select Tools > Options > Debugger > 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.

To use asynchronous mode to control the inferior, select the respective check box.

To add common paths to locations of debug information, such as `/usr/src/debug`, when starting GDB, select the Use common locations for debug information check box.

To stop when `qWarning`, `qFatal`, or `abort` is called, select the respective check box.

To enable stepping backwards, select the 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 Debug all child processes check box.

### Specifying CDB Settings

To specify settings for managing the CDB process, select Tools > Options > Debugger > CDB.

You can specify additional arguments for starting CDB in the 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 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 `CrtCbgReport()` function, select the Stop when CrtCbgReport() is called check box. This catches runtime error messages caused by `assert()`, for example.

In the Break on group, specify whether the debugger should break on C++ exceptions, on thread creation or exit, on loading or unloading the specified application modules, or on the specified output.

To disable first-chance break on access violation exceptions, select the 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 Correct breakpoint location check box. For more information, see Setting Breakpoints.

To use the abstraction layer provided by Python Dumper classes to create a description of data items displayed in the Locals and Expressions views, select the Use Python dumper check box. For more information, see Debugging Helper Implementation.

To add information about first-chance and second-chance exceptions to the Issues output pane, select the check boxes in the Add Exceptions to the Issues View group.

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

Debugging ◦ Launching the Debugger