CMake Runner

CMake Runner is a VS Code extension for CMake-based C++ projects. It puts the common workflow of select preset -> configure -> discover executable targets -> build -> run/debug into a dedicated sidebar.

It is designed for projects that already use CMakePresets.json and want a more direct way to work from the current source file back to the executable target that owns it.

What It Does

• Activates automatically when the workspace contains CMakePresets.json
• Lists available CMake configure presets in the Presets view
• Resolves preset details from CMakePresets.json and CMakeUserPresets.json, including include and inherits
• Associates configure presets with matching CMake build presets when available
• Runs preset configure directly from VS Code tasks
• After the configure is complete, the executable target is automatically discovered
• Builds a source file to executable target mapping from the CMake codemodel
• Reveals the matching source node when the active editor switches to a mapped file
• Supports target filtering by target name, executable name, or source file name
• Builds, runs, and debugs targets from the Targets view or from the active mapped source file
• Lists GoogleTest cases for built executable targets, opens a case's source on click, and provides inline run/debug actions
• Adds an editor title build button that starts from the current file and lets you pick from auto-filtered targets
• Lets you customize configure, build, and run command templates through settings.json

Typical Workflow

The extension revolves around two activity bar views:

• Presets: choose the active CMake configure preset
• Targets: inspect discovered executable targets and their source files

Typical usage looks like this:

1. Open a workspace that contains CMakePresets.json
2. Select a configure preset in Presets
3. Run Build on that preset to configure the project
4. The extension reads the CMake File API reply data from the preset's build directory
5. Discovered executable targets appear in Targets
6. Build, run, or debug a target from the tree
7. When you open a mapped source file, the extension reveals the corresponding source entry in the tree

Requirements

Before using the extension, make sure the workspace meets these conditions:

1. The workspace root contains a valid CMakePresets.json
2. The project is a working CMake C++ project that can be configured and built
3. A C/C++ debugging backend is available in VS Code
   • Windows: usually cppvsdbg
   • Linux: usually lldb
   • macOS: usually lldb

By default, preset configure runs cmake --preset ${preset}. Target discovery and source mapping rely on the configure step completing successfully.

On Windows, CMake-based tasks are wrapped with vcvarsall.bat automatically when Visual C++ build tools can be located.

Installation

Install from VSIX in VS Code

1. Open the Command Palette
2. Run Extensions: Install from VSIX...
3. Select the generated .vsix file for this repository

Install from the command line

code --install-extension cmakerunner-0.x.x.vsix

Quick Start

1. Open a project

Open a CMake project folder that contains CMakePresets.json. The extension activates automatically.

2. Select a preset

Open the cmakerunner activity bar item and choose a configure preset in the Presets view.

3. Configure and discover targets

Run Build on the selected preset.

If configure succeeds, executable targets appear in Targets.

4. Build a target

In the Targets view, run Build on a target. You can also trigger build, run, or debug from an active source file if that file maps to a discovered target.

After a successful target build, the extension offers quick Run and Debug actions.

5. Run or debug

You can invoke these actions directly on a target:

• Run
• Debug

By default, both actions build the target first.

6. Filter targets

Use Filter in the Targets view to open a target picker that is auto-filtered from the current file when possible. You can still fall back to manual text filtering to match:

• target display name
• executable file name
• source file name
• relative source path

Use Clear Filter to remove the current filter.

7. Run one GoogleTest case

Use the GTests view next to Targets to inspect GoogleTest cases by executable target. Expanding a target runs it with --gtest_list_tests. Use the inline Run action beside a discovered case to run the same target with --gtest_filter=<suite.case>. Use Filter to choose from the current target, discovered suites, or discovered cases. It matches target names, executable names, suite names, case names, or full suite.case filters. When a filter is active, the target-level Run action runs only the visible GoogleTest cases. Use Clear Filter to remove the filter, and Refresh to clear cached discovery results.

Commands

The extension currently contributes these commands:

• cmakerunner.refresh: reload presets and rebuild the current targets view
• cmakerunner.selectPreset: choose the active configure preset
• cmakerunner.buildPreset: configure the selected preset and refresh targets
• cmakerunner.rebuildPreset: re-configure the selected preset and refresh targets
• cmakerunner.buildTarget: build the resolved target
• cmakerunner.buildTargetFromCurrentFile: build the target mapped to the active source file
• cmakerunner.runTarget: build and run the resolved target
• cmakerunner.runGTestCase: build the resolved target, select a GoogleTest case, and run only that case
• cmakerunner.debugGTestCase: build the resolved target, write/update a launch configuration for one GoogleTest case, and start debugging it
• cmakerunner.debugTarget: build and debug the resolved target
• cmakerunner.refreshGTests: clear cached GoogleTest discovery results and reload the GTests view
• cmakerunner.filterGTests: filter visible GoogleTest targets and cases
• cmakerunner.clearGTestFilter: clear the current GoogleTest filter
• cmakerunner.filterTargets: filter visible targets and source nodes
• cmakerunner.clearTargetFilter: clear the current target filter

Configuration

The extension exposes these settings in VS Code settings.json:

Supported variables for configure templates

• ${buildDir}
• ${preset}
• ${sourceDir}

Supported variables for build and run templates

• ${buildDir}
• ${preset}
• ${target}
• ${sourceDir}
• ${buildPreset}
• ${configuration}
• ${configurationArgument}
• ${buildPresetArgument}
• ${executablePath}
• ${quotedExecutablePath}
• ${executableCommand}

Example configuration

{
  "cmakerunner.cmakePath": "C:/Program Files/Microsoft Visual Studio/2022/Professional/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe",
  "cmakerunner.tasks.presetConfigureCommandTemplate": "cmake --preset ${preset}",
  "cmakerunner.tasks.buildCommandTemplate": "cmake --build ${buildDir}${configurationArgument} --target ${target}",
  "cmakerunner.tasks.runCommandTemplate": "${executableCommand}",
  "cmakerunner.tasks.clearTerminalBeforeRun": true
}

Windows run command example

If you want to make the PowerShell invocation explicit, you can override the run command template like this:

{
  "cmakerunner.tasks.runCommandTemplate": "& ${quotedExecutablePath}"
}

Recommended CMake Presets Style

It is still a good idea to enable CMAKE_EXPORT_COMPILE_COMMANDS in your presets for compatibility with other C++ tooling. For this extension, target discovery and source mapping currently depend on the CMake File API codemodel data:

{
  "version": 3,
  "configurePresets": [
    {
      "name": "debug",
      "binaryDir": "${sourceDir}/build/debug",
      "cacheVariables": {
        "CMAKE_EXPORT_COMPILE_COMMANDS": true
      }
    }
  ]
}

Known Limitations

• Target discovery and source mapping depend on the CMake File; if configure has not succeeded yet, the target list stays empty
• The extension focuses on preset configure, target discovery, build, run, and debug; it is not a full CMake project manager
• Debug configurations are created dynamically at runtime and depend on an available C/C++ debug backend
• The extension operates on the first VS Code workspace folder

License

This project is licensed under MIT, as declared in package.json.