Modern target-first CMake for C/C++ projects. Grounded against CMake 4.4.3; the examples floor at CMake 3.25 so the preset schema version 6 works.
\n| Field | \nBound contract | \n
|---|---|
| Trigger | \nThe task writes or refactors CMakeLists.txt, configures out-of-source builds, selects generators, manages targets with target_link_libraries, integrates packages via find_package or FetchContent, enables sanitizers, writes toolchain files, sets up presets, or resolves a cmake configure error. | \n
| Authority | \nReversible local: writes only CMakeLists.txt, CMakePresets.json, toolchain files, and the build directory; rollback is version control plus deleting the build directory. No remote mutation. | \n
| Side effect | \ncmake --build and cmake --install write local build outputs and install trees; FetchContent downloads declared dependencies. | \n
| Done | \nThe project configures and builds with the requested options, or the failing command and its error are reported. | \n
CMakeLists.txt lives.cmake --version. Preset schema version 6 needs CMake 3.25 or newer.Apply modern CMake rules. Define targets, not variables. Use target_* commands with PUBLIC/PRIVATE/INTERFACE to control propagation. Never use include_directories() or link_libraries(); they are legacy global state. Done when: every property attaches to a target.
Write the minimal project. Done when: cmake -S . -B build configures cleanly.
cmake_minimum_required(VERSION 3.25)\nproject(MyApp VERSION 1.0 LANGUAGES C CXX)\n\nset(CMAKE_C_STANDARD 23)\nset(CMAKE_C_STANDARD_REQUIRED ON)\nset(CMAKE_CXX_STANDARD 23)\nset(CMAKE_CXX_STANDARD_REQUIRED ON)\nset(CMAKE_EXPORT_COMPILE_COMMANDS ON) # clang-tidy and IDEs read this\n\nadd_executable(myapp src/main.c src/utils.c)\ntarget_include_directories(myapp PRIVATE include)\ntarget_compile_options(myapp PRIVATE -Wall -Wextra)\nadd_library(mylib STATIC lib/foo.c lib/bar.c)\ntarget_include_directories(mylib\n PUBLIC include # consumers inherit this\n PRIVATE src # only mylib sees this\n)\n\nadd_library(myshared SHARED lib/foo.c)\nset_target_properties(myshared PROPERTIES VERSION 1.0.0 SOVERSION 1)\n\ntarget_link_libraries(myapp PRIVATE mylib)\ncmake -S . -B build -G Ninja\ncmake --build build -- -j\"$(nproc)\"\n\ncmake -S . -B build-debug -DCMAKE_BUILD_TYPE=Debug\ncmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release\ncmake --install build-release --prefix /usr/local\nBuild types: Debug, Release, RelWithDebInfo, MinSizeRel.
find_package for system libraries, FetchContent for source builds, pkg_check_modules as a fallback. Done when: the dependency resolves and links.find_package(OpenSSL REQUIRED)\nfind_package(Threads REQUIRED)\nfind_package(ZLIB REQUIRED)\ntarget_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto Threads::Threads ZLIB::ZLIB)\n\ninclude(FetchContent)\nFetchContent_Declare(\n googletest\n GIT_REPOSITORY https://github.com/google/googletest.git\n GIT_TAG v1.17.0\n GIT_SHALLOW TRUE\n)\nFetchContent_MakeAvailable(googletest)\n\nfind_package(PkgConfig REQUIRED)\npkg_check_modules(LIBFOO REQUIRED libfoo>=1.2)\ntarget_link_libraries(myapp PRIVATE ${LIBFOO_LIBRARIES})\ntarget_include_directories(myapp PRIVATE ${LIBFOO_INCLUDE_DIRS})\ntarget_compile_options(myapp PRIVATE\n $<$<CONFIG:Debug>:-g -Og -fsanitize=address>\n $<$<CONFIG:Release>:-O2 -DNDEBUG>\n $<$<CXX_COMPILER_ID:GNU>:-fanalyzer>\n)\ntarget_link_options(myapp PRIVATE\n $<$<CONFIG:Debug>:-fsanitize=address>\n)\ncmake -DENABLE_ASAN=ON produces an instrumented build.option(ENABLE_ASAN \"Enable AddressSanitizer\" OFF)\nif(ENABLE_ASAN)\n target_compile_options(myapp PRIVATE -fsanitize=address -fno-omit-frame-pointer -g -O1)\n target_link_options(myapp PRIVATE -fsanitize=address)\nendif()\ncmake -DCMAKE_TOOLCHAIN_FILE=... configures for the target.# toolchain-aarch64.cmake\nset(CMAKE_SYSTEM_NAME Linux)\nset(CMAKE_SYSTEM_PROCESSOR aarch64)\nset(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)\nset(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)\nset(CMAKE_SYSROOT /opt/aarch64-sysroot)\nset(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)\nset(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)\nset(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)\nCMakePresets.json. Schema version 6 requires CMake 3.25 or newer. Done when: cmake --preset <name> configures and cmake --build --preset <name> builds.{\n \"version\": 6,\n \"configurePresets\": [\n {\n \"name\": \"release\",\n \"generator\": \"Ninja\",\n \"binaryDir\": \"${sourceDir}/build/release\",\n \"cacheVariables\": {\n \"CMAKE_BUILD_TYPE\": \"Release\",\n \"CMAKE_EXPORT_COMPILE_COMMANDS\": \"ON\"\n }\n },\n {\n \"name\": \"debug\",\n \"generator\": \"Ninja\",\n \"binaryDir\": \"${sourceDir}/build/debug\",\n \"cacheVariables\": { \"CMAKE_BUILD_TYPE\": \"Debug\", \"ENABLE_ASAN\": \"ON\" }\n }\n ],\n \"buildPresets\": [\n { \"name\": \"release\", \"configurePreset\": \"release\" },\n { \"name\": \"debug\", \"configurePreset\": \"debug\" }\n ]\n}\n| Error | \nCause | \nFix | \n
|---|---|---|
Could not find package Foo | \nPackage missing or wrong prefix | \nInstall the dev package; set CMAKE_PREFIX_PATH | \n
No CMAKE_CXX_COMPILER | \nNo C++ compiler found | \nInstall g++ or clang++; check PATH | \n
target_link_libraries called with wrong number of arguments | \nMissing PUBLIC/PRIVATE/INTERFACE | \nAdd the keyword | \n
Cannot find source file | \nTypo or wrong relative path | \nCheck the path relative to CMakeLists.txt | \n
Compatibility error on old cmake_minimum_required | \nCMake 4 dropped compatibility with versions below 3.5 | \nRaise the floor to 3.25 | \n
For complete project templates see references/templates.md.
find_package fails: install the -dev package or set CMAKE_PREFIX_PATH; fall back to FetchContent when no system package exists.FETCHCONTENT_SOURCE_DIR_<NAME> with a local copy.cmake --help-manual cmake-generator-expressions.cmake --version meets the schema version's floor.-U to clear a cache entry; do not edit CMakeCache.txt by hand.A working CMakeLists.txt or build configuration, verified by a successful cmake -S . -B build and cmake --build build. For debugging tasks, the diagnosed error with its cause and applied fix.