What is CMake? A build system generator, explained

CMake is a build system generator: an open-source, cross-platform tool that reads a file named CMakeLists.txt and writes the build files for the program that runs your compiler, such as Make, Ninja or Visual Studio. The file lists your sources and how they fit together; describe the project once, and CMake writes the build for Windows, Linux or macOS.

The smallest project is two files in one folder. main.cpp:

#include <iostream>

int main() {
    const double average = (3.0 + 5.0 + 10.0) / 3;
    std::cout << "Hello, CMake!\n";
    std::cout << "average: " << average << '\n';
}

CMakeLists.txt, beside it:

cmake_minimum_required(VERSION 3.20)
project(hello LANGUAGES CXX)
add_executable(hello main.cpp)
target_compile_features(hello PRIVATE cxx_std_17)

Two commands in that folder configure the project into a new build folder and build it; then the program runs. Trimmed, with the folder paths shortened to the project folder, they printed:

hello> cmake -S . -B build
-- Building for: Visual Studio 17 2022
-- The CXX compiler identification is MSVC 19.44.35228.0
-- Build files have been written to: hello/build

hello> cmake --build build
  main.cpp
  hello.vcxproj -> hello\build\Debug\hello.exe

hello> build\Debug\hello.exe
Hello, CMake!
average: 6

These runs used CMake 4.4.5 and Ninja 1.13.2 on Windows, with Visual Studio 2022 and its compiler, MSVC 19.44. Nothing here was run on Linux or macOS, where the two cmake commands are the same but the generated files and the program’s path differ. The C++ is C++17 and printed the same on MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++): Clang vs GCC compares them, and Since When lists the releases that support each C++17 feature.

Older tutorials run cmake . inside the source folder, which writes CMake’s files among your sources; -S . names the source folder and -B build the folder to write into.

What does CMake do, and is it a compiler?

No: CMake compiles none of your files. It writes instructions that two other programs carry out:

1. CMake reads CMakeLists.txt and writes build files: Makefiles, a build.ninja file or a Visual Studio solution.
2. A build tool (Make, Ninja or MSBuild) reads them and runs the compiler and linker on what changed.
3. The compiler (GCC, Clang or MSVC) turns each .cpp file into an object file; the linker joins them into your program.

A build system is those build files plus the tool that runs them; CMake generates one, hence the name. When you configure, CMake does start your compiler briefly, to identify and test it, but your sources wait for cmake --build.

What goes in a CMakeLists.txt?

Commands that describe what to build, one per line. The four lines of the first example:

• cmake_minimum_required(VERSION 3.20) comes first: the oldest CMake the file is written for. CMake 4 rejects anything below 3.5, which breaks the first line of older tutorials: with VERSION 3.0, CMake 4.4.5 stopped with Compatibility with CMake < 3.5 has been removed from CMake. To build an old project without editing it, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to the configure command, as the error suggests.
• project(hello LANGUAGES CXX) names the project and turns on C++, which CMake calls CXX.
• add_executable(hello main.cpp) declares a target, one thing the build makes: a program hello, built from main.cpp.
• target_compile_features(hello PRIVATE cxx_std_17) means “build this target as C++17 or newer”: the build passed /std:c++17 to MSVC. PRIVATE keeps it to hello itself.

How do you build a project with CMake?

Configure with cmake -S . -B build, then build with cmake --build build each time you change a file. Configuring reads CMakeLists.txt, finds the compiler and writes the build files into build; building runs the build tool, which compiles what changed.

The kind of build files CMake writes is its generator. With no -G, CMake chose Visual Studio on the Windows machine these ran on (cmake --help stars the default); cmake -G Ninja -S . -B build asks for Ninja. On Windows with MSVC, run that from Visual Studio’s x64 Native Tools Command Prompt with ninja on the PATH, or it stops with No CMAKE_CXX_COMPILER could be found. The Ninja build, then a rebuild with nothing changed, printed:

hello> cmake --build build
[1/2] Building CXX object CMakeFiles\hello.dir\main.cpp.obj
[2/2] Linking CXX executable hello.exe

hello> cmake --build build
ninja: no work to do.

The program lands in build\hello.exe with Ninja and in build\Debug\hello.exe with Visual Studio, which keeps one folder per configuration (Debug, Release).

What is the build folder, and how do you clean it?

build holds everything generated: the build files, CMake’s cache (CMakeCache.txt), the object files and the program. Keep build out of version control; to start over, delete it and configure again.

cmake --build build --target clean removes the compiled files and keeps the generated build files. With Ninja it printed:

hello> cmake --build build --target clean
[1/1] Cleaning all built files...
Cleaning... 2 files.

With Visual Studio the clean printed only MSBuild’s version line, but removed the program all the same.

CMake vs Make: what is the difference?

Make runs a Makefile you write by hand. CMake writes that Makefile for you from one CMakeLists.txt (with the Unix Makefiles generator) and Make then runs it, so the two work together; CMake can write Ninja files or Visual Studio projects instead.

How do you add more files and a library?

Add source files to the list in add_executable, or move shared code into a library target with add_library and link it with target_link_libraries. Here average() moved into stats.cpp, declared in stats.h, all four files in one folder:

cmake_minimum_required(VERSION 3.20)
project(hello LANGUAGES CXX)

add_library(stats stats.cpp)
target_include_directories(stats PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
target_compile_features(stats PRIVATE cxx_std_17)

add_executable(hello main.cpp)
target_link_libraries(hello PRIVATE stats)
target_compile_features(hello PRIVATE cxx_std_17)

stats.cpp:

#include "stats.h"

double average(double a, double b, double c) {
    return (a + b + c) / 3;
}

main.cpp now includes stats.h and prints average(3.0, 5.0, 10.0); what goes in a header file explains the .h and .cpp split. The Ninja build printed:

stats> cmake --build build
[1/4] Building CXX object CMakeFiles\stats.dir\stats.cpp.obj
[2/4] Linking CXX static library stats.lib
[3/4] Building CXX object CMakeFiles\hello.dir\main.cpp.obj
[4/4] Linking CXX executable hello.exe

add_library with no type made a static library, stats.lib, linked into hello.exe, which printed the same two lines. target_include_directories names the folder of the library’s headers (${CMAKE_CURRENT_SOURCE_DIR}, the project’s own), and PUBLIC passes it on to whatever links stats; this flat folder built without it, but headers in a folder of their own need it.

How do you make a Debug or a Release build?

Ninja and the Makefile generators pick the build type when you configure; Visual Studio picks it when you build:

Each form belongs to its kind of generator: --config Release on the earlier Ninja build printed only ninja: no work to do. and built nothing.

The CMake commands you will use

Next: presets (a CMakePresets.json committed with the project) keep the configure settings in a file, and the official CMake tutorial goes further. The C++ toolchain list puts CMake beside Ninja and the IDEs; Tooling covers the rest of the build.