CLion 2021.1 Help

GDB Remote Debug

The GDB Remote Debug configuration is one of the two options that CLion provides for debugging remotely under gdbserver. Use this configuration if you already have the executable with debug information and don't need CLion to build the project for you. This configuration is independent of a particular build system or project format.

With this configuration, you can remotely debug applications that were built by any build system. The only requirement is for the debug symbols to be present on the local machine.

There are also no restrictions on the target environment. Your program can run remotely under gdbserver on any OS including Linux-based embedded systems such as Raspbian OS (see Raspberry Pi OS Guide), on a cloud platform, or inside a Docker container. 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.

CLion's bundled GDB, which is used as a client debugger by default, is built with multiarch support, which makes it suitable for remote cross-platform debug in various Linux/Windows/macOS and embedded cases. Below you can find the full list of all supported targets:

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

General steps of the workflow

Find below a brief description of the steps to take for remote GDB debug. More details for each step are given in the next chapters.

  1. Prepare a binary with debug information. If required, use a cross-platform toolchain.

  2. Make sure to place the binary on the remote machine and symbol file on the local machine.

    Usually, the debug executable itself works well as a symbol file, or this can be a separate file as well.

  3. In CLion, create a GDB Remote Debug configuration. The settings you specify are crucial for the debugger to be able to stop on breakpoints during a remote session, so we recommend you double-check the confugration set up.

  4. Launch the program under gdbserver on the remote machine.

  5. Back in CLion, start debugging the configuration you created on step 3.

Create a GDB Remote Debug configuration

  1. Go to Run | Edit Configurations, click Icons general add, and select GDB Remote Debug from the list of templates.

  2. Remote Run/Debug Configuration

    Specify the following settings:

    • GDB

      Select the client debugger: bundled multiarch GDB (default), one of the toolchain debuggers, or a custom GDB binary.

    • 'target remote' args

      In this field, provide the connection to the remote system: IP address followed by a port number (like in our example) or connection details in another format.

    • Symbol file

      This is the local machine path to the file with debug symbols, which can be a non-stripped copy of the executable running on target or an ELF file containing only the debug info.

      Recent versions of GDB clients can transfer symbols from gdbserver automatically, so leaving this field empty may also work well if the executable running on target is a non-stripped binary.

    • Path mappings

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

    • Sysroot

      Sysroot is used by GDB client to access the copies of target libraries with debug symbols on your local system (in order to set breakpoints and find source lines in the libraries code).

      Most of the recent versions of GDB can download the files automatically, so it's not required that you specify this field. However, note that automatic download may slow down the debugging process significantly.

      If you choose to manually copy the libraries into a non-default local directory and want GDB to use it, set its path in this field.

Launch your program remotely under gdbserver

  1. To launch your application on the target under gdbserver, you can use the remote terminal or invoke the CLion's built-in SSH terminal (run Tools | Start SSH session and provide the credentials).

    Run gdbserver with two arguments:

    • Either a device name (for a serial line connection) or a TCP hostname with the port number (:1234 in the example below).

    • The path and filename of the executable to be debugged, followed by the program input arguments, if any.

    remote ssh terminal
  2. Gdbserver then suspends the program at the entry point and waits for the client debugger to connect.

Start a remote debug session

  1. In CLion, make sure to have GDB selected in Settings / Preferences | Build, Execution, Deployment | Toolchain, the Debugger field.

    Depending on your platform and the selected toolchain, choose from the following options: the bundled GDB, WSL GDB, Cygwin GDB, or custom GDB.

  2. If needed, place breakpoint in your code, then start a debug Icons actions start debugger session for the newly created GDB Remote Debug configuration.

  3. CLion’s debugger will connect to the running remote process. The terminal will show the Remote debugging from host.. message, and you can also check the debugger console for the Debugger connected to.. message.

  4. Now you can inspect your code as if it was running locally (for example, step through and examine variables as usual):

    debug via gds/gdbserver

Debug shared libraries

  • To debug shared libraries, you need to set the solib-search-paths variable in the ~/.gdbinit script on the local machine. Refer to Using .gdbinit/.lldbinit configuration files for instructions on how to access and edit the script.

    However, by default, this command is executed on the debugger startup before attaching to the remote target (see the corresponding issue). As a workaround for this, 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: 21 June 2021