The Remote Debug configuration
The Remote Debug configuration allows you to debug remotely under gdbserver or lldb-server. 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.
Target platforms
There are no restrictions on target environment in case it supports gdbserver.
Your program can run remotely on any OS including Linux-based embedded like Raspbian OS (refer to 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. Find the full list of the supported targets below.
Remote targets supported by the bundled GDB
You can target macOS, Linux, Android, Apple TV/Apple Watch, and other platforms that support lldb-server. See Local system in the LLDB documentation.
General steps of the workflow
Find below a brief description of the steps to take for remote GDB/LLDB debug. More details for each step are given in the next chapters.
Prepare a binary with debug information. If required, use a cross-platform toolchain.
In the case of remote LLDB, the debugger does not download any debug symbols or system libraries automatically, so they should be present on the local machine. For cross-platform debug from macOS to Linux or from Linux to macOS, use cross-compilation via musl (or the alternatives), which will be shipped with the required libraries.
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.
In CLion, create a 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 configuration set up.
Launch the program under gdbserver/lldb-server on the remote machine.
Back in CLion, start debugging the configuration you created on step 3.
Create a Remote Debug configuration
Go to Run | Edit Configurations, click , and select Remote Debug from the list of templates.
Specify the following settings:
Debugger
Select the client debugger: bundled GDB / bundled LLDB, one of the toolchain GDB debuggers, or a custom GDB binary.
'target remote' args ('process connect' url for LLDB)
In this field, provide the connection to the remote system.
For GDB, this is IP address followed by a port number (like in our example) or connection details in another format.
For LLDB, use the
connect://host:port
notation, for example,connect://127.0.0.1:1234
.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.
CLion employs lldb-server in the g[dbserver] mode, which requires that you transfer all the files manually.
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/LLDB 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.
For LLDB, it is required that you specify the sysroot when debugging a binary built without cross-compilation on a remote platform that differs from the host. For example, if you debug from macOS to remote Linux where the binary is linked to Linux system libraries.
Launch your program remotely under gdbserver/lldb-server
To launch your application on the target, you can use the remote terminal or invoke the CLion's built-in SSH terminal (run 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.
For LLDB, start lldb-server with a command like
lldb-server g *:1234 ./binary
.On macOS, use debugserver as lldb-server:
debugserver 0.0.0.0:1234 ./binary
. By default, debugserver is located either in /Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Versions/A/Resources/debugserver (as part of the Xcode distribution) or in /Library/Developer/CommandLineTools/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/debugserver (as part of the command-line tools).Gdbserver/lldb-server then suspends the program at the entry point and waits for the client debugger to connect.
Start a remote debug session
in CLion, place breakpoint in your code, then start a debug session for the newly created Remote Debug configuration.
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.
Now you can inspect your code as if it was running locally (for example, step through and examine variables as usual):
Debug shared libraries
To debug shared libraries, add the following commands in ~/.gdbinit or .lldbinit on the local machine. For more information about accessing and editing the script, refer to Using .gdbinit/.lldbinit configuration files.
set solib-search-paths for GDB
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/my.so:/path/to/sysroot:/path/to/vendorlibs break main # if you also need the debug sessions to pause at the beginning endThis way, GDB will execute
set solib-search-path
specified in the hook every time the remote target is connected.settings set target.exec-search-paths /path/to/libs
for LLDB