CLion 2021.2 Help

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.

  1. Select File | Open from the main menu and open the source files.

  2. Set breakpoints and make sure they are going to be hit after you attach to the process.

  3. Launch the process. You can do that outside the IDE or using the built-in terminal (View | Tool Windows | Terminal or Alt+F12).

  4. In CLion, call Run | Attach to Process from the main menu or press Ctrl+Alt+F5.

  5. In the list of entries, search for your process:

    Attaching to a running process

  6. After the debugger is attached successfully, you will be able to debug as usual. See the Debugging section for details.

    Debugging a running process

  7. When finished, call Run | Stop or click Suspend 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.

  1. Click New Project on the Welcome screen or select File | New Project from the main menu.

  2. Select any of the C/C++ templates, specify the project's name, and click Create.

    Creating a fake CMake project

  3. 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.

    Default CMake configuration

  4. Go to Run | Edit Configurations. In the configuration settings, set the path the your executable:

    Setting a custom executable in the CMake configuration

    Apply the settings.

  5. Open the binary's sources using File | Open from the main menu.

  6. Navigate through the sources and set breakpoints.

    Breakpoints in external sources

    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.

  7. When ready, start a debug session for the configuration you set up on step 4.

    Debugging an external executable from a fake CMake project

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

  1. Open the source files in CLion using File | Open from the main menu.

  2. Navigate through the sources and set breakpoints.

  3. Go to Run | Edit Configurations, click Icons general add and choose Custom Build Application from the list of templates.

  4. 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 Icons general add to add a new target. Specify the target's name and leave the other fields empty:

    Creating a fake custom build target

    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.

    Custom run/debug configuration
  5. Save the configuration and start a debug session:

    Debugging a custom build application

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. See this tutorial on how to work with a Meson project using compilation databases and File Watchers. You can follow similar steps for your build system or just open the sources in CLion without creating a compilation database.

  1. Go to Settings / Preferences | Build, Execution, Deployment | Custom Build Targets and click Icons general add to add a new target.

  2. 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:

    Custom build tool
  3. Go to Run | Edit Configurations and select the newly created custom target in the Target field:

    Custom configuration with build
  4. Now if you debug this configuration, your project will be built using the specified tools first.

Last modified: 14 May 2021