CMake

Purpose

Guide agents through modern (target-first) CMake for C/C++ projects: out-of-source builds, dependency management, generator selection, and integration with CI and IDEs.

Triggers

• "How do I write a CMakeLists.txt for my project?"

• "How do I add an external library with CMake?"

• "CMake can't find my package / library"

• "How do I enable sanitizers in CMake?"

• "How do I cross-compile with CMake?"

• "How do I use CMake Presets?"

Workflow

1. Modern CMake principles

• Define targets, not variables. Use target_* commands.

• Use PUBLIC /PRIVATE /INTERFACE to control property propagation.

• Never use include_directories() or link_libraries() (legacy).

• Minimum CMake version: cmake_minimum_required(VERSION 3.20) for most features.

2. Minimal project

cmake_minimum_required(VERSION 3.20) project(MyApp VERSION 1.0 LANGUAGES C CXX)

set(CMAKE_C_STANDARD 11) set(CMAKE_C_STANDARD_REQUIRED ON) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(myapp src/main.c src/utils.c )

target_include_directories(myapp PRIVATE include) target_compile_options(myapp PRIVATE -Wall -Wextra)

3. Static / shared libraries

Static library

add_library(mylib STATIC lib/foo.c lib/bar.c) target_include_directories(mylib PUBLIC include # consumers get this include path PRIVATE src # only mylib itself sees this )

Shared library

add_library(myshared SHARED lib/foo.c) set_target_properties(myshared PROPERTIES VERSION 1.0.0 SOVERSION 1 )

Link executable against library

add_executable(myapp src/main.c) target_link_libraries(myapp PRIVATE mylib)

4. Configure and build

Out-of-source build (always do this)

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

With generator

cmake -S . -B build -G Ninja cmake --build build -- -j$(nproc)

Debug build

cmake -S . -B build-debug -DCMAKE_BUILD_TYPE=Debug cmake --build build-debug

Release

cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release cmake --build build-release

Install

cmake --install build --prefix /usr/local

Build types: Debug , Release , RelWithDebInfo , MinSizeRel .

5. External dependencies

find_package (system-installed libraries)

find_package(OpenSSL REQUIRED) target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto)

find_package(Threads REQUIRED) target_link_libraries(myapp PRIVATE Threads::Threads)

find_package(ZLIB REQUIRED) target_link_libraries(myapp PRIVATE ZLIB::ZLIB)

FetchContent (download and build dependency)

include(FetchContent)

FetchContent_Declare( googletest GIT_REPOSITORY https://github.com/google/googletest.git GIT_TAG v1.14.0 ) FetchContent_MakeAvailable(googletest)

add_executable(mytest test/test_foo.cpp) target_link_libraries(mytest PRIVATE GTest::gtest_main mylib)

pkg-config fallback

find_package(PkgConfig REQUIRED) pkg_check_modules(LIBFOO REQUIRED libfoo>=1.2) target_link_libraries(myapp PRIVATE ${LIBFOO_LIBRARIES}) target_include_directories(myapp PRIVATE ${LIBFOO_INCLUDE_DIRS})

6. Compiler options by configuration

target_compile_options(myapp PRIVATE $<$<CONFIG:Debug>:-g -Og -fsanitize=address> $<$<CONFIG:Release>:-O2 -DNDEBUG> $<$<CXX_COMPILER_ID:GNU>:-fanalyzer> $<$<CXX_COMPILER_ID:Clang>:-Weverything> )

target_link_options(myapp PRIVATE $<$<CONFIG:Debug>:-fsanitize=address> )

Generator expressions: $<condition:value> evaluated at build time.

7. Enable sanitizers

option(ENABLE_ASAN "Enable AddressSanitizer" OFF)

if(ENABLE_ASAN) target_compile_options(myapp PRIVATE -fsanitize=address -fno-omit-frame-pointer -g -O1) target_link_options(myapp PRIVATE -fsanitize=address) endif()

Build: cmake -DENABLE_ASAN=ON -S . -B build-asan && cmake --build build-asan

8. Cross-compilation toolchain file

toolchain-aarch64.cmake

set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc) set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++) set(CMAKE_SYSROOT /opt/aarch64-sysroot) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

cmake -S . -B build-arm -DCMAKE_TOOLCHAIN_FILE=toolchain-aarch64.cmake

9. CMake Presets (CMake 3.20+)

{ "version": 6, "configurePresets": [ { "name": "release", "displayName": "Release", "generator": "Ninja", "binaryDir": "${sourceDir}/build/release", "cacheVariables": { "CMAKE_BUILD_TYPE": "Release", "CMAKE_EXPORT_COMPILE_COMMANDS": "ON" } }, { "name": "debug", "displayName": "Debug", "generator": "Ninja", "binaryDir": "${sourceDir}/build/debug", "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", "ENABLE_ASAN": "ON" } } ], "buildPresets": [ { "name": "release", "configurePreset": "release" }, { "name": "debug", "configurePreset": "debug" } ] }

cmake --preset release cmake --build --preset release

10. Common errors

Error Cause Fix

Could not find package Foo

Package not installed or wrong prefix Install dev package; set CMAKE_PREFIX_PATH

No CMAKE_CXX_COMPILER

No C++ compiler found Install g++/clang++; check PATH

target_link_libraries called with wrong number of arguments

Missing PUBLIC/PRIVATE/INTERFACE

Add the keyword

Cannot find source file

Typo or wrong relative path Check path relative to CMakeLists.txt

generator expression error Wrong $<> syntax Check CMake docs for expression name

For a complete CMakeLists.txt template, see references/templates.md.

Related skills

• Use skills/build-systems/ninja for Ninja generator details

• Use skills/build-systems/make for Make generator

• Use skills/compilers/cross-gcc for cross-compilation toolchain setup

• Use skills/runtimes/sanitizers for sanitizer integration details