To start an application from an open project under the control of a debugger, press the Debug button in the lower left corner of the main view, or press F5.
Qt Creator checks whether the compiled program is up-to-date, and rebuilds and deploys it if the Always build project before deploying it and Always deploy before running options are selected in the Build and Run options.
The debugger then takes over and starts the program with suitable parameters.
Note: Starting a C++ 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 plugin can run the native debuggers in various 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.
In general, the F5 and the Debug button are set up in a way to start operating mode that is commonly used the a given context. So if the current project is set up as a C++ application using the MinGW toolchain targeting desktop Windows, the GDB engine will be started in Start Local mode. If the current project is a QML application using C++ plugins targeting Meego a "mixed" QML/C++ engine will be started, with the C++ parts being handled by GDB and GDB server remote debugging.
To select other modes of operation, change the run run configuration parameters (such as Run in Terminal) in the run settings of the project, or select options from the Debug > Start Debugging menu.
The debugger can run in the following modes:
Start Local mode is the default start mode for most projects, including all projects using a desktop Qt version and plain C++ projects.
To launch the debugger in Start Local mode, click the Start Debugging button for the active project.
To lauch Start Local mode to run any executable already present in the system without using a project, select Debug > Start Debugging > Start and Debug External Application.
Terminal mode is a variation of Start Local and creates an additional console window to enable user-terminal interaction. This is mainly useful for non-GUI applications using the stdin and stdout channels for communication. To launch the debugger in the terminal mode, go to Projects > Run Settings and select the Run in terminal check box. Then click the Start Debugging button for the active project.
To attach the debugger to an already running process, select Debug > Start Debugging > Attach to Running Local Application, and then select a process by its name or process ID to attach to.
While this mode does not strictly require a project to be opened in Qt Creator, it is beneficial to have open one, as it makes setting breakpoints and stepping throught the code easier.
For more information, see Setting Breakpoints.
The Remote modes allow you to debug processes that run on remote machines.
In general, the setup consist of a probe running on the remote machine and a counterpart running on the host side. The probe is either integrated into the running process (e.g. for QML debugging) or runs a separate process (e.g. when using GDB server on embedded Linux, or TRK/CODA on Symbian). The host side typically consists of Qt Creator itself, often with help of external process such as CDB or GDB.
While this setup might look daunting, it is mostly invisible to the user. With a properly loaded and configured project, pressing F5 starts up all necessary helper processes and debugging on the selected target.
Special use cases, such as attaching to a running process on the target, might still require manual setup.
When debugging on a target supported by GDB server, a local GDB process talks to a GDB server 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:
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:
cdb.exe -server tcp:port=1234 <executable>
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]
The Core mode is used to inspect core files (crash dumps) that are generated from crashed processes on Linux and Unix systems 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.
Also in this mode, using a properly configured project containing the sources of the crashed program is not strictly necessary, but helpful.
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 Qt 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.