Debug servers
OS: Windows, Linux, macOS
Debug Servers is a configuration option that makes it easier to set up debugging for embedded development. Using a pre-configured debug server, you can run different run/debug configurations or build system targets such as CMake or Makefile. You can also run long-lived debug server sessions, known as GDB target extended-remote mode: the server does not shut down when you stop debugging.
This guide explains how to configure a debug server and run a debug session. To demonstrate the feature functionality, we use the nRF52840 Development Kit with a built-in SEGGER J-Link debugger and a simple application example that outputs “Hello world” in the console.
note
Debug Servers is an experimental feature that doesn’t yet work with PlatformIO (however, there is a workaround), West, and CTest. We encourage you to give it a try and share your feedback using Help | Submit Feedback… in the main IDE menu.
Go to Settings | Advanced Settings | Debugger and select the Enable Debug Servers checkbox:
Find the Debug Servers option in Settings | Debugger or select Native | Edit Debug Servers in the main toolbar switcher:
Click + to add a new debug server:
Select one of the two template types, Generic or SEGGER J-Link:
The Generic template is suitable for any debug probe and offers a broader range of options.
The SEGGER J-Link template is specifically designed for J-Link debug probes. It is more straightforward and less flexible than Generic, providing only the necessary options.
Configure a GDB server, device, and debugger in appropriate tabs as needed for your project. Both debug server templates have some default settings you can use. However, there are some settings you may need or want to customize, which are listed in the tabs below.
In the SEGGER JLink GDB Server tab, you need to specify the device you are working with:
CLion tries to guess the installation path with an executable, but sometimes, you must manually give it the path.
In the Device Settings tab, you can select and configure a preferred console type, such as RTT, Semihosting, or SWO, to view the
printf
output. In addition to the port, SWO has other parameters to configure. Be sure that your MCU and firmware are configured accordingly.The Debugger tab has a Persistent session option. This option, enabled by default, maintains the connection to the debug server even after the session is closed. You just need to specify the port of your GDB server.
A persistent session is useful when you want a debug server to be ready for the next session without waiting for it to start back up. You can uncheck this option if you don’t need it.
The GDB Server tab does not have default settings, so you need to manually specify all the fields.
The Help field of the GDB Server tab allows you to run the GDB server with the
--help
command-line parameter, view the output directly in this field, and find the available arguments. You can click on the arguments highlighted in blue, and they will be automatically added to the Arguments field. Note that this option only works for GDB servers that support the--help
parameter.You can also check your arguments’ validity by clicking Test Run… next to the Arguments field.
The Device Settings tab allows you to specify only a console port. This means you are not limited to a console type and can use any. To configure your console, use the Arguments field of the GDB Server tab.
In the Debugger tab, the Persistent session feature has several configuration options. In the Arguments field, you can specify a TCP host, port, and other command-line arguments. You can also create a custom connection script to run when debugging starts.
When you are finished configuring the debug server, click OK. The debug server will appear in the main toolbar switcher. You can start debugging.
Be sure you have J-Link software installed.
Some important settings to note:
Some important settings to note:
If you have already used a GDB server run configuration in CLion, you can import it and convert it into a generic debug server. If the IDE detects such a configuration, the corresponding icon appears in the dialog:
![Import configuration icon Import configuration icon](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_servers_import_icon.png)
Click the icon, select the configuration you want, and then click Import:
![Import configuration button Import configuration button](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_servers_import_button.png)
You can share your debug server configurations using a version control system like Git. A debug server XML file can be found in your project’s .idea/debugServer
:
![Sharing a debug server Sharing a debug server](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_servers_vcs.png)
Set breakpoints in the source code.
Select your Run / Debug Configuration from the switcher on the main toolbar:
Click
on the toolbar to start a debug session. The debugger will connect to your debug probe:
You can then perform available debugger actions and analyze the necessary data. To learn more about the features of the debugger tool window, see its overview.
In the Debug tool window, there are some options specifically designed for debugging embedded systems. For example, you can reset your MCU:
![Resetting a device Resetting a device](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_server_reset.png)
To view debug server logs or console output, click the Show Service icon in the Debug tool window or the Services tool window icon from the left:
![Switching to services Switching to services](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_server_console.png)
Select the GdbServer tab:
![Viewing a GDB server logs Viewing a GDB server logs](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_server_services.png)
To view the console output, select the MCU Console tab:
![Viewing console output Viewing console output](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_server_console_tab.png)
For more convenience, you can move the Services tool window to the right to work with the debugger and see, for example, console output at the same time:
![Moving the Services tab Moving the Services tab](https://resources.jetbrains.com/help/img/idea/2024.3/cl_debug_servers_console_output.png)
Thanks for your feedback!