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:
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.
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).
- 'target remote' args
Launch a remote debug session
First, launch your application on the remote target under gdbserver. For this, you can use the built-in SSH terminal (run with the appropriate credentials):
gdbserver suspends the program at the entry point and waits for the debugger to connect to it.
Then switch to the newly created remote configuration and start a debug 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 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/my.so:/path/to/sysroot:/path/to/vendorlibs break main # if you also need the debug sessions to pause at the beginning end
This way, GDB will execute
set solib-search-pathspecified in the hook every time the remote target is connected.