Building Projects with CMake

CMake isn't a single program; it's a suite of tools. You can interact with it in several ways, and the best one often depends on the task at hand.

The Command Line (cmake)

This is the most fundamental and powerful way to use CMake. It's what CI/CD pipelines use for automated builds, and it's what IDEs often run under the hood.

IDE Integration

This is how most developers use CMake day-to-day. Modern C++ IDEs have embraced CMake as a first-class project model.

• Visual Studio: Has native support for opening a folder containing a CMakeLists.txt file. It will automatically configure the project, let you select build targets, and provide full IntelliSense and debugging.
• VS Code: The CMake Tools extension provides a popular workflow. It gives you a status bar to switch configurations, a side panel to view targets, and buttons to configure, build, and debug your project.
• CLion: This IDE uses CMake as it's primary method of managing builds. Its entire project model is a CMake project, offering deep integration, code completion for CMake commands, and easy management of profiles and configurations.

The heart of any CMake project is the CMakeLists.txt file. This is a plain text file that contains a series of commands that describe how to build your project.

Let's create this file in the root directory of our project, alongside our vendor directory and README.md.

1# Set the minimum version of CMake required
2cmake_minimum_required(VERSION 3.23)
3
4# Define the project
5project(
6  MyGame
7  VERSION 1.0
8  DESCRIPTION "My first SDL3 Game"
9  LANGUAGES CXX
10)
11
12# Set the C++ standard to C++20
13set(CMAKE_CXX_STANDARD 20)
14set(CMAKE_CXX_STANDARD_REQUIRED ON)

Let's break this down:

• cmake_minimum_required(VERSION 3.23): This is always the first line. It tells CMake what version it needs to be to understand the commands in this file. Version 3.23 is a safe, modern choice that's widely available.
• project(...): This command defines our project. We give it a name (MyGame), a version, a short description, and specify that its primary language is C++ (CXX).
• set(CMAKE_CXX_STANDARD 20): This tells CMake that we want to build our project using the C++20 standard.
• set(CMAKE_CXX_STANDARD_REQUIRED ON): This ensures that the chosen C++ standard is strictly enforced. If the compiler doesn't support C++20, CMake will stop with an error.

With just these few lines, we've defined the basic properties of our project.

CMake Presets are the modern, recommended way to define common configuration options for your project. Instead of passing long, complex arguments on the command line, you can define named "presets" in a JSON file. This makes your build process repeatable and easy to share with other developers.

Let's create a file named CMakePresets.json in our project's root directory.

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "default",
5    "binaryDir": "build"
6  }],
7  "buildPresets": [{
8    "name": "default",
9    "configurePreset": "default"
10  }]
11}

This file defines two types of presets - presets for when we're configuring the project, and presets for when we're building the project. We cover these two steps in the next section, so this will make more sense soon, but broadly:

• We run the configuration step once to perform all the initial setup of our build system. On Windows, for example, the configure step might create a Visual Studio solution for our project.
• We run the build step every time we want to compile our software. This takes the configuration files, such as the Visual Studio solution, and uses them to create an executable we can run.

We can configure preset settings for each of these steps:

configurePresets

These define options for the "configure" step, where CMake generates the build files.

• We've created one named "default".
• "binaryDir": "build" tells CMake to put all the generated project files, compiled code, and final executables into a separate directory named build. This practice is called an out-of-source build, and it keeps our source code directory clean.

buildPresets

These define options for the "build" step.

• We've also created a "default" build preset.
• "configurePreset": "default" links this build preset to our "default" configure preset, telling it which configuration to use. The most notable effect is that it informs CMake where the build system is. In this case, we're saying it's in the binaryDir specified in our default configuration preset.

Now that we have a CMakeLists.txt and a CMakePresets.json, we can perform the two main steps of a CMake build: configuring and building.

The first step is to "configure" the project. During this phase, CMake reads your CMakeLists.txt, detects your compiler and development environment, and generates the actual project files for your native build system (like a Visual Studio solution or a Makefile).

To run the configure step using our preset, we execute this command from the project's root directory:

1cmake --preset default

You'll see output as CMake checks your system and sets up the build environment. When it's finished, you'll find a new build directory in your project. This directory contains all the generated files.

With the project configured, we can now build it. This step takes the generated project files and runs the actual compiler to turn your source code into an executable.

We could do that using the generated files directly. For example, if CMake generated a Visual Studio project in our /build directory, we could open that solution in Visual Studio and use it like any other .sln file.

However, we can alternatively trigger the build step through CMake, which works across all the different build systems it recognizes. We can trigger the build using our default build preset like this:

1cmake --build --preset default

Since we don't have any source code to compile yet, this command will run very quickly and report that there's nothing to do.

This workflow is the core of using CMake:

1. Configure once: You only need to run the cmake --preset default command when you first create the project, or when you make significant changes to your configuration such that you want to recreate a clean build environment. If things ever get strange with your build, a common troubleshooting step is to delete the build directory and run the configure step again.
2. Build many times: As you make changes to your C++ code, you will repeatedly run the cmake --build --preset default command to recompile and see your changes.

A CMake Generator is what determines the type of native build files that CMake will create in your build directory. CMake is smart and will automatically choose a default generator based on your system.

• On a Windows system with Visual Studio installed, it will likely default to a "Visual Studio" generator, creating a .sln file.
• On macOS or Linux, it will likely default to "Unix Makefiles", creating a Makefile.
• If you have the Ninja build system installed, CMake may prefer it, as it's known for being very fast.

Listing Generators

You can see a full list of the generators available on your machine by running cmake --help. The output is long, but will include a section listing the available generators:

1cmake --help

1...
2The following generators are available on this platform (* marks default):
3  Visual Studio 17 2022
4  Visual Studio 16 2019
5  ...

Specifying the Generator

While you can let CMake pick the default, you (or your team) may have a preference that doesn't match the default. We can specify which generator to use directly in our CMakePresets.json file.

For example, we could update our preset to explicitly request the Visual Studio 2022 generator. Note the generator value should exactly match one of the options listed in the cmake --help output:

1{
2  "version": 3,
3  "configurePresets": [{
4    "name": "default",
5    "binaryDir": "build",
6    "generator": "Visual Studio 17 2022"
7  }],
8  "buildPresets": [{
9    "name": "default",
10    "configurePreset": "default"
11  }]
12}

We should commit our changes to source control regularly, however, we should not commit files that are automatically generated, such as the contents of our /build directory.

To make this easier, git supports a .gitignore file, containing patterns that we want it to ignore.

We can ask git to ignore all contents of our /build directory like this:

1build/*

Now, if we check our status, we should see that the new files we created are being tracked, but the automatically generated content in our /build directory isn't:

1git status

We can stage, commit, and push our changes in the usual way:

1git add .

1git commit -m "Add CMake"

1git push

In this lesson, we set up a project using CMake, the industry-standard build system generator for C++.

We began by installing CMake and verified that it was accessible from our command line. We then discussed the different ways to interact with CMake, either from the command line or via an IDE that natively supports it.

The core of the lesson was creating our first CMakeLists.txt file, where we defined our project's name and specified the C++ standard. We then created a CMakePresets.json file to standardize the two-step build process:

1. Configuring the project with cmake --preset default to generate native build files in a clean build directory.
2. Building the project with cmake --build --preset default to compile our code into an executable.

Finally, we learned about CMake Generators and how to explicitly define one in our presets file to specify exactly which build system we want CMake to use.