Debug arbitrary executables

You can use CLion to debug an executable that was built elsewhere using any build system. This article describes three options you can choose between depending on your application. Whichever one you use, all the CLion debugging facilities will be fully available for your code. The requirements are that your binary includes debug symbols and you have the source files on hand.

Option 1: Attach to a running process

The quickest solution is to attach the debugger to an already running process. This is suitable for applications that can run indefinitely, like various services.

Select File | Open from the main menu and open the source files.
Set breakpoints and make sure they are going to be hit after you attach to the process.
Launch the process. You can do that outside the IDE or using the built-in terminal (View | Tool Windows | Terminal or Alt+F12).
In CLion, call Run | Attach to Process from the main menu or press Control+Alt+F5.
In the list of entries, search for your process:
After the debugger is attached successfully, you will be able to debug as usual. For more information, refer to the Debugging section.
When finished, call Run | Stop or click on the toolbar or in the Debug tool window to detach from the process.

Option 2: Debug a fake CMake project

Another option is to create a basic CMake project and use a CMake Application configuration for debugging an external executable.

Click New Project on the Welcome screen or select File | New Project from the main menu.
Select any of the C/C++ templates, specify the project's name, and click Create.
CLion will generate a stub project with a default run/debug configuration. You can use that configuration or create a new one from the CMake Application template.
Go to Run | Edit Configurations. In the configuration settings, set the path the your executable:
Apply the settings.
Open the binary's sources using File | Open from the main menu.
You don't need to copy the sources into your project folder.
Navigate through the sources and set breakpoints.
CLion will show warnings that the files don't belong to the project. Since you are not using CMake as a build system, you can safely ignore these warnings.
When ready, start a debug session for the configuration you set up on step 4.
If required, you can switch between the available debuggers in the project's toolchain settings.

Option 3: Debug a custom build application

As a more full-fledged alternative, employ CLion's custom build targets - a way to set up building and running/debugging for various kinds of C/C++ applications. You can configure debugging or a complete chain of build, clean, and debug.

Create a custom configuration for debug

Open the source files in CLion using File | Open from the main menu.
Navigate through the sources and set breakpoints.
Go to Run | Edit Configurations, click and choose Custom Build Application from the list of templates.
First, you need to specify a build target even if no actual build will be performed. This is required because the build target defines the toolchain from which the debugger is taken.
Click Configure custom build targets. In the dialog that opens, click to add a new target. Specify the target's name and leave the other fields empty:
If you want CLion to perform build/clean for you, configure a proper build target as described below.
Save the target and get back to the configuration settings.
- Select the created build target in the Target field.
  CLion will show a warning at the bottom of the Edit Configurations dialog. For debugging purposes, this warning can be ignored.
- Specify the application binary in the Executable field.
Save the configuration and start a debug session:

Configure a custom build target (additionally)

In addition to a custom configuration for debugging, you can also set up the build/clean tools for your project.

We will take the Meson build system as an example. For more information about working with a Meson project using compilation databases and File Watchers, refer to this tutorial. You can follow similar steps for your build system or just open the sources in CLion without creating a compilation database.

Go to Settings | Build, Execution, Deployment | Custom Build Targets and click to add a new target.
Set up the build/clean tools. Make sure to specify the proper Working directory.
In our example, the Build tool is named Meson_build, and it calls meson compile in the buildir directory:
After saving the target, you can start using the Build Project / Rebuild Project actions.
Go to Run | Edit Configurations and select the newly created custom target in the Target field:
Now if you debug this configuration, your project will be built using the specified tools first.

Last modified: 31 October 2023