Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Preprocessor, Tools and Concepts

CMake for C++ projects

Learn the CMake basics every C++ project needs: CMakeLists.txt, targets, include directories, linking libraries, configurations, FetchContent and presets.

CMake is the most widely used build-system generator for C++. You describe your project in CMakeLists.txt files, and CMake generates the real build files (Makefiles, Ninja files, Visual Studio or Xcode projects) for your platform and compiler. It does not compile anything itself.

Modern CMake is organized around targets: an executable or library, with properties (sources, include directories, compile definitions, features) that propagate to whatever links against it. If you remember one rule, make it this: describe what a target needs with target_* commands, and never set global flags.

The CMake files and shell commands on this page are shown read-only, because our runner compiles a single file. The two live examples simulate the two ideas you will see most: what configure_file does, and how a library target and an application separate.

CMAKE
cmake_minimum_required(VERSION 3.28)
project(demo VERSION 1.2.0 LANGUAGES CXX)

add_executable(app src/main.cpp)
target_compile_features(app PRIVATE cxx_std_23)

Try it

C++ What configure_file does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ A library target and an application target

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

A small project

TEXT
demo/
  CMakeLists.txt
  lib/CMakeLists.txt
  lib/include/greeter/greeter.h
  lib/greeter.cpp
  app/CMakeLists.txt
  app/main.cpp
  tests/CMakeLists.txt
CMAKE
# CMakeLists.txt (top level)
cmake_minimum_required(VERSION 3.28)
project(demo VERSION 1.2.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)           # -std=c++23, not gnu++23

add_subdirectory(lib)
add_subdirectory(app)

include(CTest)
if(BUILD_TESTING)
  add_subdirectory(tests)
endif()
CMAKE
# lib/CMakeLists.txt
add_library(greeter greeter.cpp)
target_include_directories(greeter PUBLIC include)    # users of greeter get this too
target_compile_features(greeter PUBLIC cxx_std_23)
target_compile_options(greeter PRIVATE
  $<$<OR:$<CXX_COMPILER_ID:GNU>,$<CXX_COMPILER_ID:Clang>>:-Wall -Wextra>
  $<$<CXX_COMPILER_ID:MSVC>:/W4>)
CMAKE
# app/CMakeLists.txt
add_executable(app main.cpp)
target_link_libraries(app PRIVATE greeter)

Configure, build, test

Terminal
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release   # configure
cmake --build build                                       # build
ctest --test-dir build --output-on-failure                # run tests
cmake --install build --prefix /opt/demo                  # install

Key commands

Command Purpose
project(name VERSION x.y LANGUAGES CXX) Names the project and sets PROJECT_NAME, PROJECT_VERSION_*.
add_executable(app files...) Creates an executable target.
add_library(name [STATIC|SHARED|INTERFACE] files...) Creates a library target. INTERFACE is for header-only libraries.
target_sources(t PRIVATE files...) Adds source files to a target.
target_include_directories(t PUBLIC dir) Adds include paths.
target_link_libraries(t PRIVATE other) Links and inherits the other target's public requirements.
target_compile_definitions(t PRIVATE NAME=1) Adds -DNAME=1.
target_compile_features(t PUBLIC cxx_std_23) Requires a C++ standard.
find_package(Name REQUIRED) Finds an installed library and its imported targets.
FetchContent_Declare / FetchContent_MakeAvailable Downloads and builds a dependency at configure time.
add_test(NAME t COMMAND app) Registers a test for ctest.

PUBLIC, PRIVATE and INTERFACE

These keywords say who needs a property:

  • PRIVATE: only this target needs it (its own sources).
  • PUBLIC: this target and everything that links to it need it, for example the include directory of a header that other code includes.
  • INTERFACE: only consumers need it, not the target itself (typical for header-only libraries).

Presets and dependencies

CMakePresets.json stores configure and build settings so everyone (and CI) uses the same command: cmake --preset release. For dependencies, the options in order of control are:

  • find_package for libraries installed by the system or a package manager,
  • FetchContent to build the dependency from source at configure time,
  • a package manager such as vcpkg or Conan, which hands CMake a toolchain file.

Usage notes

  • Never use include_directories(), link_libraries() or add_definitions() in new code. They set global state and hide which target needs what.
  • Do not set CMAKE_CXX_FLAGS for warnings. Use target_compile_options so dependencies are not built with your warning flags.
  • Out-of-source builds only. Always pass -B build, and keep generated files out of the source folder.
  • Multi-config generators (Visual Studio, Xcode, Ninja Multi-Config) pick the configuration at build time with --config Release. Single-config generators (Makefiles, Ninja) fix it at configure time with CMAKE_BUILD_TYPE.
  • Glob patterns hide new files. file(GLOB ...) does not re-run when you add a file, so list sources explicitly.
  • Export compile_commands.json with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON. Editors and clang-tidy use it to see how each file is compiled.