CLion 2019.1 Help

Remote Debug via GDB/gdbserver

CLion supports remote debug with GDB/gdbserver. Having an executable running on a remote machine under gdbserver, you can connect to it with the GDB from CLion on another machine and inspect the code using all the benefits of the CLion debugger: set breakpoints from the IDE, view variable values, evaluate expressions, and more.

The bundled GDB in CLion is built with multiarch support, so it can be used for remote cross-platform debug in various Linux/Windows/macOS and embedded cases. Below you can find the full list of remote targets supported by the bundled GDB:

Remote targets supported by the bundled GDB

  • i686-pc-mingw32 i686-w64-mingw32 x86_64-w64-mingw32 i686-linux-gnu x86_64-linux-gnu aarch64-linux-gnu alpha-linux-gnu arm-linux-gnu arm-linux-gnueabi arm-linux-gnueabihf hppa-linux-gnu ia64-linux-gnu m68k-linux-gnu m68k-rtems mips-linux-gnu mipsel-linux-gnu mips64-linux-gnu mips64el-linux-gnu powerpc-linux-gnu powerpc-linux-gnuspe

With remote GDB/gdbserver, you can run applications that were built using any build system; the only requirement is that debug symbols should be available for binaries and libraries. Also, it puts no restrictions on the target environment: you can launch your program under gdbserver on any OS including Linux-based embedded systems (for example, Raspbian OS), on a cloud platform, or, for example, inside a Docker container.

GDB/gdbserver is especially useful for the cases when building on target is time-consuming, expensive, or unavailable: you can place a binary built elsewhere on the target, run it under gdbserver, and get the full IDE debug experience in CLion running locally. Moreover, you can connect to any GDB stub that complies with the remote gdbserver protocol: for example, Qemu to debug OS kernels or OpenOCD to debug flashed firmware.

Create a Remote GDB configuration

In the Run | Edit Configurations dialog, create a new configuration from the GDB Remote Debug template:

Remote Run/Debug Configuration

  • Specify the following settings:

    • 'target remote' args

      Here you need to provide the medium to carry the debugging packets (serial line or an IP network using TCP or UDP). See gdb documentation for more details on connecting to a remote target.

    • Symbol file

      GDB that runs on the host needs access to debug information for the executable running on the target. For this, it requires the symbol file on host to be a non-stripped copy of the executable on the target. However, leaving this field empty may also work well, as recent versions of GDB can transfer symbols from GDB server automatically.

    • Sysroot

      In this field, specify the local directory that contains the symbol file and the copies of target libraries in corresponding subdirectories.

    • Path mappings

      Use this pane to provide paths on the target machine (the Remote column) to be mapped to local paths on host (the Local column).

Launch a remote debug session

  1. First, launch your application on the remote target under gdbserver. For this, you can use the built-in SSH terminal (run Tools | Start SSH session with the appropriate credentials):

    remote ssh terminal

    gdbserver suspends the program at the entry point and waits for the debugger to connect to it.

  2. Then switch to the newly created remote configuration and start a debug icons actions startDebugger svg session. CLion’s debugger connects to the remote process and uses the provided debug information to let you inspect the code as if it was running locally (for example, set breakpoints, step through, and examine the variables):

    debug via gds/gdbserver

Debug shared libraries

  • To debug shared libraries, you need to set the solib-search-paths variable in the ~/.gdbinit script. However by default, this command will be executed on the debugger startup before attaching to the remote target (see the corresponding issue). As a workaround, you can use GDB hooks:

    define target hookpost-remote set solib-search-path /path/to/ break main # if you also need the debug sessions to pause at the beginning end

    This way, GDB will execute set solib-search-path specified in the hook every time the remote target is connected.

Last modified: 24 July 2019