Launching the Debugger

To start a program under the control of the debugger, select Debug > Start Debugging > Start Debugging, or press F5. Qt Creator checks whether the compiled program is up-to-date, and rebuilds it if necessary. The debugger then takes over and starts the program.

Note: Starting a program in the debugger can take a long time, typically in the range of several seconds to minutes if complex features (like QtWebKit) are used.

The debugger is launched in the appropriate operating mode (plain, terminal, or on-device), based on the build and run settings for the active project. Select Debug menu options to launch the debugger in other modes.

Note: Debugging QML and JavaScript is supported only in plain mode.

Launching the Debugger in Different Modes

The debugger plugin runs in different operating modes depending on where and how the process is started and run. Some of the modes are only available for a particular operating system or platform.

You can launch the debugger in the following modes:

• Plain to debug locally started applications, such as a Qt based GUI application.
• Terminal to debug locally started processes that need a console, typically without a GUI.
• Attach to debug local processes started outside Qt Creator.
• Remote to debug a process running on a different machine.
• Core to debug crashed processes on Unix.
• Post-mortem to debug crashed processes on Windows.
• On-device to debug processes running on a mobile device.

Note: Debugging QML and JavaScript is supported only in plain mode.

Launching in Plain Mode

To launch the debugger in the plain mode, click the Start Debugging button for the active project, or choose Debug > Start Debugging > Start and Debug External Application... and specify an executable.

Launching in Terminal Mode

To launch the debugger in the terminal mode, select Projects > Run Settings and select the Run in terminal check box. Then click the Start Debugging button for the active project.

Launching in Attach Mode

To launch the debugger in the attach mode, select Debug > Start Debugging > Attach to Running External Application..., and then select a process by its name or process ID to attach to.

You can load the source project in advance and set breakpoints in it before attaching to an already running process. For more information, see Setting Breakpoints.

Launching in Remote Mode

The remote mode allows you to debug processes that run on remote machines.

Using GDB

In remote mode, the local GDB process talks to a GDB server process running on the remote machine that controls the process to be debugged.

The GDB server process is started on the remote machines by passing a port number and the executable:

 gdbserver :1234 <executable>

It then typically responds:

 Process bin/qtcreator created; pid = 5159
 Listening on port 1234

On the local machine that runs Qt Creator:

1. Select Debug > Start Debugging > Start and Attach to Remote Application....
2. In the Host and port field, enter the name of the remote machine and the port number to use.
3. Select OK to start debugging.

Using CDB

In remote mode, the local CDB process talks to a CDB process that runs on the remote machine. The process is started with special command line options that switch it into server mode. The remote CDB process must load the Qt Creator CDB extension library that is shipped with Qt Creator:

1. Install the Debugging Tools for Windows on the remote machine. The installation folder contains the CDB command line executable (cdb.exe).
2. Copy the Qt Creator CDB extension library from the Qt installation directory to the a new folder on the remote machine (32 or 64 bit version depending on the version of the Debugging Tools for Windows used):
   • \lib\qtcreatorcdbext32\qtcreatorcdbext.dll (32 bit)
   • \lib\qtcreatorcdbext64\qtcreatorcdbext.dll (64 bit)
3. Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point to that folder.
4. To use TCP/IP as communication protocol, launch remote CDB as follows:

            cdb.exe -server tcp:port=1234 <executable>

5. On the local machine running Qt Creator, select Debug > Start Debugging > Attach to Remote CDB Session...
6. In the Connection field enter the connection parameters. For example, for TCP/IP:

            Server:Port

   If you chose some other protocol, specify one of the alternative formats:

            tcp:server=Server,port=Port[,password=Password][,ipversion=6]
            tcp:clicon=Server,port=Port[,password=Password][,ipversion=6]
            npipe:server=Server,pipe=PipeName[,password=Password]
            com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
            spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
            ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
            ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]

7. Click OK to start debugging.

Launching in Core Mode

The core mode it used to debug core files (crash dumps) that are generated from crashed processes if the system is set up to allow this.

To enable the dumping of core files on a Unix system enter the following command in the shell from which the application will be launched:

 ulimit -c unlimited

To launch the debugger in the core mode, select Debug > Start Debugging > Attach to Core....

Launching in Post-Mortem Mode

The post-mortem mode is available only on Windows, if you have installed the debugging tools for Windows.

The Qt Creator installation program asks you whether you want to register Qt Creator as a post-mortem debugger. To change the setting, select Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging.

You can launch the debugger in the post-mortem mode if an application crashes on Windows. Click the Debug in Qt Creator button in the error message that is displayed by the Windows operating system.

Launching in On-device Mode

The on-device mode is a special mode available for run configurations targeting mobile devices. It debugs processes running on mobile devices using on-device debugging agents, such as CODA on Symbian and gdbserver on Linux-based devices.

To launch the debugger in the on-device mode, open the project, select a run configuration that targets a mobile device, and click the Start Debugging button.