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_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
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.
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
demo/ CMakeLists.txt lib/CMakeLists.txt lib/include/greeter/greeter.h lib/greeter.cpp app/CMakeLists.txt app/main.cpp tests/CMakeLists.txt
# 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()
# 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>)
# app/CMakeLists.txt add_executable(app main.cpp) target_link_libraries(app PRIVATE greeter)
Configure, build, test
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_packagefor libraries installed by the system or a package manager,FetchContentto 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()oradd_definitions()in new code. They set global state and hide which target needs what. - Do not set
CMAKE_CXX_FLAGSfor warnings. Usetarget_compile_optionsso 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 withCMAKE_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.jsonwith-DCMAKE_EXPORT_COMPILE_COMMANDS=ON. Editors and clang-tidy use it to see how each file is compiled.