- Qt Creator Documentation
- Debug remotely with GDB
- Qt Creator 20.0.0

Connect remote Linux devices ◦ Deploy applications to remote Linux devices

# Debug remotely with GDB

In the common case where the remote machine or container already has GDBserver installed and remote execution of an application is already set up and works by selecting the Run button (or Ctrl+R), you can start remote debugging by selecting the Debug button (or F5).

In this case, Qt Creator launches and connects the debug server and the application on the remote machine and the actual debugger on the development host in the right order automatically.

This is the preferred method.

If the requirements for this automated setup are not met but your remote machine is capable of running GDB server (or any compatible probe using the GDB serial protocol), you can still use Qt Creator to debug your application.

## Application running, SSH access to remote machine available

If you want to attach to an application that is already running on the remote machine and a debug server can be started via SSH from the local machine host, go to Debug > Start Debugging > Attach to running applications.

## Application not running, terminal access to remote machine available

If a debug server cannot be started via SSH from the local machine, check your device documentation for alternative means to start a debug server.

If you have some terminal access to the remote machine, and a GDB server installed there, you can manually transfer the executable to the remote machine and start `gdbserver` by passing a port number and the executable:

     gdbserver :1234 /path/to/executable

It then typically responds:

     Process /path/to/executable created; pid = 5159
     Listening on port 1234

On the local machine that runs Qt Creator:

1. Go to Debug > Start Debugging > Attach to Running Debug Server.

2. In Kit, select the build and run kit to use for building the project.
3. In Server port, enter the name of the remote machine and the port number to use.
4. In Local executable, specify the path to the application executable on the local machine.
5. In Command line arguments, specify command line arguments to be passed to the executable.
6. In Working directory, specify the working directory. It defaults to the directory of the build result.
7. Select Run in terminal for console applications.
8. Select Break at "main" to stop the debugger at the main function.
9. Select Use target extended-remote to connect to create the connection in the `target extended-remote mode`. In this mode, when the debugged application exits or you detach from it, the debugger remains connected to the target. You can rerun the application, attach to a running application, or use monitor commands specific to the target. For example, GDB does not exit unless it was invoked using the `--once` option, but you can make it exit by using the `monitor exit` command.
10. In Override SysRoot, specify the path to the `sysroot` to use instead of the default `sysroot`.
11. In Init commands, enter the commands to execute immediately after the connection to a target has been established.
12. In Reset commands, enter the commands to execute when resetting the connection to a target.
13. In Debug information, specify the location for storing debug information. You cannot use an empty path.
14. In Override server channel, specify a communication channel to use, such as a serial line or custom port.
15. In Recent, select a recent configuration to use.
16. Select OK to start debugging.

By default, a non-responsive GDB process is terminated after 40 seconds. To increase the timeout in GDB timeout, go to Preferences > Debugger > GDB.

For more information about connecting with `target extended-remote` mode in GDB, see Debugging with GDB: Connecting to a Remote Target.

## Application running, terminal access to remote machine and gdbserver available

This case is almost identical to the previous section, except that `gdbserver` is started differently:

     gdbserver --attach :1234 <PID of running application>

### Use SSH port forwarding

To enable debugging on remote targets that cannot expose GDB server ports, map the remote ports to local ports using SSH tunneling. Qt Creator automatically detects the local and remote ports.

To turn on SSH port forwarding:

1. Go to Preferences > Devices.

2. In Device, select Remote Linux Device.
3. Select Use SSH port forwarding for debugging.
4. Select Apply.

## GDB server started by a command

If you want to automate and persist the GDB server setup as part of your project (for example, you have a script that starts `gdbserver` on a remote device), add a Remote Debugger run configuration. The launcher command runs automatically each time you start debugging, so you do not need to set up the connection manually.

To add a Remote Debugger run configuration:

1. Go to Projects > Run Settings.
2. Select Add > Remote Debugger > Create.
3. In Command, specify a script or command that sets up the GDB server connection.
4. In Command line arguments, specify any arguments to pass to the launcher command.
5. In Symbol file (local executable), specify the path to the application executable on the local machine.
6. In Server channel, specify the communication channel to use. The default is `tcp://127.0.0.1:1234`.
7. Select Break at "main" to stop the debugger at the main function.
8. Select Run in terminal for console applications.
9. Select Use "target extended-remote" to connect to connect in extended-remote mode.
10. Select the run configuration in the kit selector and press F5 to start debugging.

See also How to: Debug, How to: Develop for remote Linux, GDB, Debugging, Debuggers, and Managing kits.