Cmake

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

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

CMake Project Templates

Minimal C library + executable

myproject/
├── CMakeLists.txt
├── include/
│   └── mylib/
│       └── mylib.h
├── src/
│   ├── mylib.c
│   └── main.c
└── test/
    └── test_mylib.c

cmake_minimum_required(VERSION 3.20)
project(MyProject VERSION 1.0 LANGUAGES C)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)   # for clang-tidy / IDEs

# Library
add_library(mylib STATIC src/mylib.c)
target_include_directories(mylib PUBLIC include)
target_compile_options(mylib PRIVATE -Wall -Wextra)

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

# Tests
enable_testing()
add_executable(test_mylib test/test_mylib.c)
target_link_libraries(test_mylib PRIVATE mylib)
add_test(NAME mylib_tests COMMAND test_mylib)

# Install
install(TARGETS myapp RUNTIME DESTINATION bin)
install(TARGETS mylib ARCHIVE DESTINATION lib)
install(DIRECTORY include/ DESTINATION include)

---

C++ project with GoogleTest via FetchContent

cmake_minimum_required(VERSION 3.20)
project(MyProject VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Main library
add_library(mylib STATIC
    src/engine.cpp
    src/parser.cpp
)
target_include_directories(mylib PUBLIC include PRIVATE src)
target_compile_options(mylib PRIVATE
    -Wall -Wextra
    $<$<CONFIG:Debug>:-g -Og>
    $<$<CONFIG:Release>:-O2 -DNDEBUG>
)

# Main executable
add_executable(myapp src/main.cpp)
target_link_libraries(myapp PRIVATE mylib)

# Tests
include(FetchContent)
FetchContent_Declare(
    googletest
    GIT_REPOSITORY https://github.com/google/googletest.git
    GIT_TAG        v1.14.0
    GIT_SHALLOW    TRUE
)
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(googletest)

enable_testing()
add_executable(unit_tests
    test/test_engine.cpp
    test/test_parser.cpp
)
target_link_libraries(unit_tests PRIVATE mylib GTest::gtest_main)
include(GoogleTest)
gtest_discover_tests(unit_tests)

---

Sanitizer option pattern

# In CMakeLists.txt (at project level)

option(SANITIZE_ADDRESS  "Enable ASan"  OFF)
option(SANITIZE_THREAD   "Enable TSan"  OFF)
option(SANITIZE_UNDEFINED "Enable UBSan" OFF)

set(SANITIZER_FLAGS "")
if(SANITIZE_ADDRESS)
    list(APPEND SANITIZER_FLAGS -fsanitize=address -fno-omit-frame-pointer)
endif()
if(SANITIZE_THREAD)
    list(APPEND SANITIZER_FLAGS -fsanitize=thread)
endif()
if(SANITIZE_UNDEFINED)
    list(APPEND SANITIZER_FLAGS -fsanitize=undefined)
endif()

if(SANITIZER_FLAGS)
    # Apply to all targets in this directory and below
    add_compile_options(${SANITIZER_FLAGS})
    add_link_options(${SANITIZER_FLAGS})
endif()

---

Dependency management patterns

External package with fallback

find_package(ZLIB QUIET)
if(NOT ZLIB_FOUND)
    message(STATUS "ZLIB not found, fetching...")
    include(FetchContent)
    FetchContent_Declare(zlib
        GIT_REPOSITORY https://github.com/madler/zlib.git
        GIT_TAG        v1.3.1
    )
    FetchContent_MakeAvailable(zlib)
    set(ZLIB_TARGET zlibstatic)
else()
    set(ZLIB_TARGET ZLIB::ZLIB)
endif()
target_link_libraries(myapp PRIVATE ${ZLIB_TARGET})

Vendored library (in tree)

add_subdirectory(third_party/json)
target_link_libraries(myapp PRIVATE nlohmann_json::nlohmann_json)