CMake Tools

The CMake Tools extension enables us to build, run and test our code directly in VS Code.

Furthermore, it will help us in the next section to get the language server going.

Install the extension

To install/enable the extension, follow the same steps as in the CMake section.

Settings

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

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

You can also simply copy the section // cmake settings from the user_settings.json file to your own user settings. Remember to adjust any paths for your specific machine.

Let's take a closer look at the most useful 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.

The other settings are less important. You can either remove them or keep them depending on your preferences.

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.

Get started

Setting the source directory

To get started with CMake Tools, we have to tell it where the source directory is:

• Run >CMake: Configure. This should either
  • ask you to choose a kit and then ask for a source directory or
  • ask for a source directory right away.
• Select any kit you like for now (if you are asked to choose one).
• 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

If you haven't selected any kit yet, you can now let CMake Tools scan for possible kits on your machine or add kits manually. 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.

If your file is missing a kit, you can add it manually.

Select a kit + variant and configure the project

Once you are satisfied with the available kits, you can 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:

We chose the kit Clang 19 and the Release build type.

Build the project

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

• Run >CMake: Build

On macOS with homebrew's llvm (v19.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/test/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 19",
  "compilers": {
    "C": "/opt/homebrew/opt/llvm@19/bin/clang",
    "CXX": "/opt/homebrew/opt/llvm@19/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 19 to link to libc++.

Run tests and examples

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

In the status bar, you can find various short cuts for selecting a variant, selecting a kit, building the project, running the tests, running specific executables, etc.