CMake Tools

The CMake Tools extension provides language support for CMake files and enables us to build, run and test our code directly in VS Code.

Furthermore, it will help us in the next section when we need to set up the language server.

Install the extension

To install the extension,

• Go to Extensions in the activity bar
• Search for cmake tools
• Select the CMake Tools extension by Microsoft
• Click the blue Install button

If you remove cmake tools from the search field, you should see that one extension shows up under the Installed category:

Settings

The CMake Tools extension can (or should) be configured with various settings. To scroll through them, we can

• Run >Preferences: Open Settings (UI)
• Go to the Extensions menu
• Go to CMake Tools

Alternatively, we can edit directly the JSON file by running >Preferences: Open User Settings (JSON). We are going to add 3 settings:

• "cmake.buildDirectory": "${workspaceFolder}/build.${buildKitVendor}-${buildKitVersion}-${buildType}": Specifies the build directory. In our case, it will be created in the workspace folder moderncpp_vscode.
• "cmake.copyCompileCommands": "${sourceDirectory}/compile_commands.json": By default, CMake Tools generates a compilation database compile_commands.json in the build directory. With this setting, a copy will be placed in the source directory as well (important for clangd in the next section).
• "cmake.installPrefix": "${workspaceFolder}/build.${buildKitVendor}-${buildKitVersion}-${buildType}/install": Specifies a default install directory.

Kits vs. Presets

CMake Tools can be configured to either work with kits or presets. Although presets is the recommended way, we will use kits in this tutorial.

For more information on kits see CMake Tools docs.

Getting started

Setting the source directory

At first, we try to configure the project:

• Run >CMake: Configure.

This should ask you to choose an existing kit or scan for kits:

• Select any kit you like for now or simply choose [Unspecified]
• Specify the source directory by selecting the toplevel ${workspaceFolder}/moderncpp_vscode.src/CMakeLists.txt file.

This will create a .vscode directory in your workspace. Here you can put project specific VS Code files.

CMake Tools should have already written a settings.json file with the following content:

Scan and edit kits

Now, we're going to let CMake Tools scan for possible kits on our machine and then edit the detected kits manually if necessary. In order to do this,

• Run >CMake: Scan for Kits
• Run >CMake: Edit User-Local CMake Kits

This should open the file cmake-tools-kits.json and display all the kits that were found on your machine:

As you can see, a kit has a name and defines a set of compilers. In addition, it can also set environment variables, specify a toolchain file or run a script. We will come back to that in a moment.

For now, let's keep the kits as they are.

Select a kit + variant and configure the project

To select a kit and a variant:

• Run >CMake: Select a Kit and choose the kit you like
• Run >CMake: Select a Variant and choose the build type you like

This should run CMake and configure your project. It also creates a build directory in the workspace folder:

As you can see by the name of the build directory and the CMake output, we chose the kit Clang 21.1.2 arm64-apple-darwin24.6.0 in Debug mode.

Build the project

To build the library, the unit tests and the examples, simply

• Run >CMake: Build

On macOS with homebrew's llvm (v21.1.2), this gives an error on the author's machine because by default it links to the standard library provided by Apple:

To fix this, we can tell clang++ to link to llvm's libc++ instead by updating the settings file .vscode/settings.json to

{
    "cmake.sourceDirectory": "/Users/thahn/repos/modernc++/moderncpp_vscode/moderncpp_vscode.src",
    "cmake.configureEnvironment": {
        "LDFLAGS": "-L/opt/homebrew/opt/llvm/lib/c++ -L/opt/homebrew/opt/llvm/lib/unwind -lunwind"
    }
}

Then we clean the cache, reconfigure the project and perform a clean rebuild:

• Run >CMake: Delete Cache and Reconfigure
• Run >CMake: Clean Rebuild

Now the build should succeed.

Note: Instead of changing the workspace settings, we could also change the kit in cmake-tools-kits.json. For example,

{
  "name": "Clang 21.1.2 arm64-apple-darwin24.6.0",
  "compilers": {
    "C": "/opt/homebrew/opt/llvm/bin/clang",
    "CXX": "/opt/homebrew/opt/llvm/bin/clang++"
  },
  "environmentVariables": {
    "LDFLAGS": "-L/opt/homebrew/opt/llvm/lib/c++ -L/opt/homebrew/opt/llvm/lib/unwind -lunwind"
  },
  "isTrusted": true
}

This makes sense, if we always want Clang 21.1.2 arm64-apple-darwin24.6.0 to link to llvm's libc++.

Run tests and examples

To check if everything worked as planned, go to the terminal, cd into the build directory and run ./ctest:

Alternatively, we can also run the tests via >CMake: Run Tests.

Language support

If we open again a CMakeLists.txt file, we can see that VS Code now provides proper syntax highlighting, code completion, etc. for CMake files: