CMake

CMake does not compile anything itself: it reads a CMakeLists.txt and writes the build files of a generator, make by default on Linux. The compiler runs later, from those files.

The reason to use it is portability and scale: the same file configures a build on Linux, Windows and macOS, and the target model carries include directories, compile features and linked libraries. This lesson starts with the smallest project and the three commands that build it.

The build directory also holds the cache: CMakeCache.txt remembers the compiler, the generator and every option, which is why a second configure is fast and why deleting the directory is the reliable reset.

The generator is chosen at configure time, so the same project builds with make, Ninja or an IDE project file. The commands of this lesson do not change with the generator, which is the point of the two-step interface.

A build directory can be deleted at any time and regenerated from CMakeLists.txt, which is the recovery step for a build that behaves strangely. The sources never live there.

The two commands are also what a script in the repository runs, so the build on a server is the build on a laptop.

A configure that fails leaves the build directory in a half-written state; the next configure overwrites it, and deleting the directory is the reliable reset.

CMakeLists.txt

The file names the minimum CMake version, the project, the C++ standard and one executable. project(toolbox CXX) tells CMake to look for a C++ compiler, and add_executable builds the target from main.cpp.

The program is a hello world with a version macro in the output. The standard is set for the target, which is the modern form and the subject of the next lesson.

CMakeLists.txt lives in the source directory and describes the project, not the build. The build directory is a separate tree that CMake fills with generated files.

CMakeLists.txt

cmake_minimum_required(VERSION 3.20) project(toolbox CXX) set(CMAKE_CXX_STANDARD 23) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(toolbox main.cpp)

main.cpp

#include <iostream> int main() { std::cout << "built by CMake\n"; }

cmake -S . -B build

-- The CXX compiler identification is GNU 15.2.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done (0.4s)
-- Generating done (0.0s)
-- Build files have been written to: /tmp/cppcourse/work/L099/s0/build

Configure and build

cmake -S . -B build reads the source directory and writes a build tree into build. The output names the compiler it found and ends with the line that says where the files went.

cmake --build build runs the generator on that tree and compiles only what is out of date. The program then runs the binary from the build directory.

The two steps are separate on purpose: configure once, build many times. A build script or an IDE runs the same two commands, which is why a project can be built the same way from a terminal and from an editor.

CMakeLists.txt

cmake_minimum_required(VERSION 3.20) project(toolbox CXX) set(CMAKE_CXX_STANDARD 23) set(CMAKE_CXX_STANDARD_REQUIRED ON) add_executable(toolbox main.cpp)

main.cpp

#include <iostream> int main() { std::cout << "built by CMake\n"; }

cmake -S . -B build
cmake --build build
./build/toolbox

Rebuild after a change

A second build finds the target up to date and prints nothing but the summary. That is the timestamp check of lesson 097, generated by CMake rather than written by hand.

The program builds once, then builds again. The second run prints the built target line and stops, which is the whole output of an up-to-date build.

CMake tracks the headers a source includes, so a header change does rebuild the object; that is the dependency problem of lesson 098 solved by the generator.

CMakeLists.txt

cmake_minimum_required(VERSION 3.20) project(toolbox CXX) add_executable(toolbox main.cpp)

main.cpp

#include <iostream> int main() { std::cout << "built by CMake\n"; }

cmake -S . -B build
cmake --build build
cmake --build build

A source that is not there

CMake checks the sources of a target at configure time. A file that does not exist is a configure error, and the message names the file and the target that wanted it.

The file below lists missing.cpp, which is not in the directory. CMake stops with Cannot find source file and a second error about the target having no sources, before the compiler is started.

The fix is the file name. A rename in the tree without a rename in CMakeLists.txt produces exactly this message, and it is the first thing to check when a configure that used to work stops.

cmake_minimum_required(VERSION 3.20) project(toolbox CXX) add_executable(toolbox missing.cpp)

cmake -S . -B build

-- The CXX compiler identification is GNU 15.2.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Configuring done (0.4s)
CMake Error at CMakeLists.txt:4 (add_executable):
Cannot find source file:

missing.cpp

CMake Error at CMakeLists.txt:4 (add_executable):
No SOURCES given to target: toolbox

CMake Generate step failed. Build files cannot be regenerated correctly.

Exercises

Add a second source file to the executable and rebuild.
Delete the build directory and configure again, and compare the output with the first configure.
Run `cmake --build build --verbose` and find the g++ command CMake generated.

The code on this page was built with g++ 15.2.0 and CMake 4.2.3 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container. The programs whose section shows a compiler error were compiled until that error and were not run.

Article author: Arthur Isaev

CMake

CMakeLists.txt

Configure and build

Rebuild after a change

A source that is not there

Exercises

Questions