Modern CMake 4.5+ Systems & Build Engineering
Build deterministic, target-based CMake 4.5+ (November 2026) software systems exclusively for Linux (linux-64, linux-aarch64, and riscv64 RVA23 cross-compilation) and macOS (osx-arm64) using LLVM/Clang 23.1.5+, Ninja, and Pixi 0.84.2+ (conda-forge)—with GCC supported strictly for sysroot or cross-compilation toolchains.
Related Skills
/ada-spark-pro: Formally verified SPARK Ada 2022 (alr 2.1.1+,gnat_native=16.1.0,gnatprove=16.1.0) encapsulated static libraries viacmake/SparkTargets.cmakeandinstall(... BUILD_DEPENDS ...)./c-pro: Modern ISO C23 (CMAKE_C_STANDARD 23,<stdbit.h>probes, dual-languageextern "C"ABI headers) for real-time OS and safety kernels./cpp-pro: Modern ISO C++23 (LLVM/Clang 23.1.5),-fno-exceptions -fno-rttidefaults, C++ modules ban for determinism, and the Linuxlibstdc++vs. macOSlibc++native standard library ABI rule./rust-pro: Rust 1.99.1+ (edition = "2024",#![no_std]capable) via Cargo, Corrosion, and Crubitcpp_api_from_rust/ C ABI interop (CMAKE_EXPERIMENTAL_RUSTremains experimental in CMake 4.5)./python-pro: Python 3.15 / 3.14 +nanobindCMake module targets and canonicalpixi0.84.2+ workspace/environment workflows./github-flow-lifecycle: 6-stage Git/GitHub Flow protocol enforcing branch isolation, localCMakePresets.jsonpre-commit CI gates, and remote Actions self-healing.
Use this skill when
- Architecting, reviewing, or refactoring
CMakeLists.txt,cmake/*.cmake,CMakePresets.json(v13),pixi.toml,.gersemirc, or.pre-commit-config.yamlon Linux or macOS. - Enforcing strict target encapsulation,
FILE_SET(HEADERS/SOURCES),cmake_diagnostic()rules, sanitizers, or hardware ISA/SIMD feature probes. - Packaging artifacts with CMake 4.3–4.5 GA Common Package Specification (CPS via
PACKAGE_INFO) and native SPDX 3.0.1 JSON-LD SBOM generation (install(SBOM ...)). - Configuring cross-compilation toolchains (
aarch64-linux-gnu,riscv64-linux-gnuRVA23),cmake_instrumentation(), orCTest+ Google Test /discover_tests().
Do not use this skill when
- Maintaining pure Makefile, Meson, Bazel, or standalone Cargo builds without CMake integration.
- Authoring application logic without build-system changes (use
/c-pro,/cpp-pro,/rust-pro, or/ada-spark-pro).
Core Requirements & 8 Golden Rules
Target-Based CMake, File Sets & Strict Diagnostics (CMake 4.5+):
- Declare
cmake_minimum_required(VERSION 4.5)andcmake_diagnostic(SET CMD_NON_TARGET_DIRECTIVE SEND_ERROR)at the root to hard-reject all 7 legacy non-target commands (include_directories,link_libraries,link_directories,add_definitions,add_compile_definitions,add_compile_options,add_link_options). Validcmake_diagnostic()actions areIGNORE,WARN,SEND_ERROR, andFATAL_ERROR(ERRORis invalid). - Register headers and sources with
target_sources(<tgt> {PUBLIC|PRIVATE|INTERFACE} FILE_SET <name> [TYPE <HEADERS|SOURCES>] BASE_DIRS ... FILES ...)(omitTYPEwhen<name>matchesHEADERSorSOURCES). Apply fine-grained properties withset_property(FILE_SET <name> TARGET <tgt> PROPERTY <PROP> <val>)using CMake 4.4–4.5 properties:SKIP_LINTING,SKIP_PRECOMPILE_HEADERS,SKIP_UNITY_BUILD_INCLUSION,CXX_SCAN_FOR_MODULES,INDEPENDENT_FILES, andJOB_POOL_COMPILE. - Keep
CMAKE_VERIFY_INTERFACE_HEADER_SETSandCMAKE_VERIFY_PRIVATE_HEADER_SETSas preset/CI controls rather than hardcodingONinCMakeLists.txt; filter targets via{INTERFACE,PRIVATE}_HEADER_SETS_TO_VERIFY. - Take advantage of CMake 4.5
ALIASparity:target_*(),add_dependencies(),set_property(),set_target_properties(),install(), andexport()acceptALIAStargets directly (ALIASED_TARGETremains read-only).
- Declare
Modular
cmake/Architecture & Scoped Isolation:- Keep root
CMakeLists.txtstrictly declarative, guard against in-source builds (PROJECT_SOURCE_DIR STREQUAL PROJECT_BINARY_DIR), and registerlist(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake"). - Isolate variable, policy, and diagnostic mutations using
block(SCOPE_FOR VARIABLES POLICIES DIAGNOSTICS)inside helper modules (Sanitizers.cmake,Architecture.cmake) so temporary probe variables never leak. When includingProjectOptions.cmake, scope onlyPOLICIES DIAGNOSTICS(orPROPAGATE) so launcher/linker cache and directory variables apply globally.
- Keep root
Dynamic ISA, SIMD & Compiler Feature Probing:
- Never hardcode
-marchor-m*flags unconditionally. Probe capabilities insidecmake_push_check_state()+check_cxx_source_compiles()/check_c_source_compiles()/check_cxx_compiler_flag():X86_64: Probe AVX2+FMA (-mavx2 -mfma) and AVX-512 (-mavx512f -mavx512vl -mavx512dq -mavx512bw).ARM64: Enable baseline NEON and probe SVE (-march=armv8-a+sve).RISCV64(RVA23): Probe RVV 1.0 (-march=rva23u64, fallback-march=rv64gcv) compiling<riscv_vector.h>(__riscv_v_intrinsic >= 1000000,__riscv_vsetvl_e32m1).
- Normalize
ARCH_FAMILY_<X>and defineTARGET_CACHE_LINE_BYTES(128onARM64vs.64onX86_64/RISCV64). GateENABLE_NATIVE_OPTIMIZATION(-march=native) strictly withif(NOT CMAKE_CROSSCOMPILING)and compile verification.
- Never hardcode
Interface Target Encapsulation, Exceptions/RTTI & Module-Scanning Discipline:
- Encapsulate compiler policy inside
INTERFACEtargets (project_options,project_warnings,project_sanitizers,project_architecture) linked viaPRIVATE. - Match
/cpp-pro: default-fno-exceptions -fno-rttionproject_optionsguarded by$<$<COMPILE_LANGUAGE:CXX>:...>(so mixed C23 targets never receive C++-only flags), exposingENABLE_EXCEPTIONSandENABLE_RTTIoptions (OFFby default). - Default C++20/23 module scanning
OFFvia non-cacheset(CMAKE_CXX_SCAN_FOR_MODULES OFF)gated byoption(ENABLE_CXX_MODULES "..." OFF)soccache,clang-tidy, andmisc-include-cleanerstay deterministic. WhenENABLE_CXX_MODULES=ONfor standalone C++23import stdprojects on Ninja (>= 1.11), CMake 4.5 treatsimport stdandimport std.compatas GA (do not use obsoleteCMAKE_EXPERIMENTAL_CXX_IMPORT_STDUUIDs orCXX_MODULE_STD; overrideCMAKE_CXX_STDLIB_MODULES_JSONbeforeproject()only if compiler auto-discovery fails). - Enforce Clang 23.1+ and GCC strict C23/C++23 warnings in
CompilerWarnings.cmake(WARNINGS_AS_ERRORS->-Werror), and probe ASan, UBSan (-fsanitize=undefined -fno-sanitize-recover=all), TSan, and MSan (Clang+Linux only) with mutual exclusions inSanitizers.cmake.
- Encapsulate compiler policy inside
CMakePresets.jsonSchema v13 as the Sole Workflow Interface:- Standardize on
"version": 13and"cmakeMinimumRequired": {"major": 4, "minor": 5, "patch": 0}with"binaryDir": "${sourceDir}/build/${presetName}". - Enable v12–v13 strict diagnostics in
"base":warnings(author,deprecated,policy,strict,nonTargetDirective,installAbsoluteDestination,uninitialized,unusedCli) anderrors(nonTargetDirective,deprecated). Never emitwarnings.devorerrors.dev—they were removed in Schema v12 and error in v13! Reserveerrors.unusedCli: truefor project-final presets rather than shared bases. - Use
${configurePresetName}(v13) inbuildPresets/testPresets/packagePresetsfields that support macro expansion (e.g.,outputJUnitFile,environment) and optionally indescription—never insideworkflowPresets(macros do not expand in workflow steps) and notedisplayNamerenders literals verbatim. Use${fileDir}(v12+ file-local semantics) for cross-file toolchain paths. - Use
--presets-file <file>(4.4+) for out-of-tree presets,--list-presets=all-defined(4.5+) to inspect every defined preset and unavailability reasons,execution.testPassthroughArguments(v12+, e.g.,["--gtest_brief=1"]), andcmake --workflow --preset <name>for full pipelines.
- Standardize on
Modern Tooling, Instrumentation, Introspection & Testing:
- Linkers & Launchers: Default
CMAKE_LINKER_TYPE(LLD,MOLD,WILDon Linux;SYSTEMld_primeor probedLLDon Apple) insideif(NOT DEFINED CMAKE_LINKER_TYPE)only aftercheck_linker_flag()validation. Wireccache/sccacheviaCMAKE_<LANG>_COMPILER_LAUNCHER,CMAKE_CXX_CLANG_TIDY, andCMAKE_EXPORT_COMPILE_COMMANDS ON. - Instrumentation & Debugging: Collect Ninja/Make build telemetry with
cmake_instrumentation(API_VERSION 1 DATA_VERSION 1.2 HOOKS ... OPTIONS compileTrace processMetrics trace)andctest --collect-instrumentation. Inspect targets and properties withcmake_language(PRINT_TARGETS / PRINT_PROPERTIES / PRINT_VARIABLES)instead of legacyCMakePrintHelpers. - Testing: Use
gtest_discover_tests(... DISCOVERY_MODE POST_BUILD)(switching toPRE_TESTwhenCMAKE_CROSSCOMPILING+CMAKE_CROSSCOMPILING_EMULATORis set) and CMake 4.4–4.5discover_tests(... DISCOVERY_MATCH ... BUILD_DEPENDS ...)(feedingctest --out-of-date), honoringCMP0224(AROUND_EACH_REPEAT/FIXTURE_REPEAT_MODE).
- Linkers & Launchers: Default
Hermetic
pixi0.84.2+ Dependencies, ABI Rules, CPS & SPDX 3.0.1 SBOM:- Pixi +
conda-forgePrimary: Manage compilers, CMake 4.5+, Ninja,gersemi,pre-commit, and libraries (libabseil—never broken legacyabseil-cpp >=20260817.0—gtest,benchmark) viapixi.toml(requires-pixi = ">=0.84.2",platforms = ["linux-64", "linux-aarch64", "osx-arm64"]). Gatepixi-baseinCMakePresets.jsonon non-empty$env{CONDA_PREFIX}, settingCMAKE_C_COMPILER: "clang",CMAKE_CXX_COMPILER: "clang++", andCMAKE_PREFIX_PATH: "$env{CONDA_PREFIX}". Consult/python-proforpixiCLI workflows and/cpp-profor stdlib ABI discipline. - Platform-Native Stdlib ABI Rule: Preserve Linux
libstdc++and macOSlibc++(libcxxin[target.osx-arm64.dependencies]); never force-stdlib=libc++on Linux againstconda-forgelibraries. - No
FetchContent/ Air-Gapped Fallback:FetchContentandExternalProject_Addare strictly forbidden. For air-gapped or embedded SDK builds without Pixi, inherit"base"directly (sysroot-release) and usefind_package(<Pkg> CONFIG REQUIRED)withCMAKE_FIND_ROOT_PATH_MODE_{LIBRARY,INCLUDE,PACKAGE}=ONLY. ExportCMAKE_SYSTEM_ENVIRONMENT_IDinpixi.toml[activation.env](not presetenvironment) when usingCMAKE_SYSTEM_ENVIRONMENT_ACTION=REFRESH. - GA CPS (
PACKAGE_INFO) & SPDX 3.0.1SBOM: SetCOMPAT_VERSIONandSPDX_LICENSEinproject(). Export packages viainstall(PACKAGE_INFO <Pkg> EXPORT <Exp> LOWER_CASE_FILE)(find_package()resolves.cpsnatively) and emit compliance artifacts viainstall(SBOM <Name> EXPORTS <Exp>... DATA_LICENSE "CC0-1.0" DEFAULT_LICENSE "${PROJECT_SPDX_LICENSE}" FORMAT spdx-3.0.1+json)or presetCMAKE_INSTALL_SBOM_FORMATS. Wrap generator expressions inLINK_LIBRARIESinside$<LINK_ONLY:...>soSBOMexport succeeds cleanly.
- Pixi +
Deterministic
gersemi(0.19.2+) Formatting & Pre-Commit Enforcement:- Lowercase commands (
add_library,target_sources), UPPERCASE keywords/variables (PUBLIC,FILE_SET,CMAKE_BUILD_TYPE),line_length: 100,indent: 4,list_expansion: favour-inlining. - Wrap
install(SBOM ... EXPORTS ...)in# gersemi: off/# gersemi: onwhen runninggersemi 0.29.2(whose built-in command table still carries pre-4.5 SBOM keywords), and double-escape regex backreferences (\\1.\\2) insidediscover_tests(). - Gate commits with
gersemi --check,clang-format --dry-run --Werror, andclang-tidy -p build/ci-debug --warnings-as-errors=*in.pre-commit-config.yaml(matchingci-debugbinary directorybuild/ci-debug).
- Lowercase commands (
Standard Modular Project Layout
my_project/
├── pixi.toml # Hermetic conda-forge workspace (Linux + macOS)
├── CMakeLists.txt # Declarative CMake 4.5+ root (CPS + SPDX SBOM)
├── CMakePresets.json # Schema v13 configure, build, test, workflow presets
├── .gersemirc # Deterministic gersemi 0.19.2+ formatting rules
├── .pre-commit-config.yaml # SHA-frozen hygiene + gersemi + clang-format/tidy
├── cmake/
│ ├── ProjectOptions.cmake # project_options, ccache, clang-tidy, CMAKE_LINKER_TYPE, IPO
│ ├── CompilerWarnings.cmake # project_warnings (Clang 23.1+ & GCC strict flags)
│ ├── Sanitizers.cmake # project_sanitizers (block-scoped ASan/UBSan/TSan/MSan)
│ ├── Architecture.cmake # project_architecture (X86_64/ARM64/RISCV64 RVA23 probes)
│ ├── Dependencies.cmake # find_package(CONFIG REQUIRED) & IMPORTED wrappers
│ ├── Testing.cmake # gtest_discover_tests + CMake 4.5 discover_tests()
│ ├── Coverage.cmake # llvm-cov / llvm-profdata target integration
│ ├── SparkTargets.cmake # Optional Alire/GPRbuild SPARK Ada static targets
│ └── toolchains/
│ ├── aarch64-linux-gnu.cmake
│ └── riscv64-linux-gnu.cmake
├── include/<pkg>/ # Public headers (FILE_SET HEADERS)
├── src/ # Implementation units (FILE_SET TYPE SOURCES)
└── tests/ # Hermetic unit tests
Decision Trees
Dependency, Toolchain & Preset Routing
Configuring a CMake 4.5+ build environment?
├── Standard Linux (x86_64/aarch64) or macOS (osx-arm64) workstation/CI?
│ └── Activate Pixi (`pixi run configure` / `pixi run workflow`) -> inherits `pixi-base`
│ (requires `$env{CONDA_PREFIX}`, sets Clang + `$env{CONDA_PREFIX}`, preserves Linux libstdc++ / macOS libc++).
├── Air-gapped host or bare-metal SDK without Pixi?
│ └── Use `sysroot-release` (inherits `base`, NOT `pixi-base`) + `find_package(<Pkg> CONFIG REQUIRED)`.
└── Targeting AArch64 or RISC-V RVA23 Linux from host?
└── Use `cross-aarch64` or `cross-riscv64` (`toolchainFile: "${fileDir}/cmake/toolchains/..."`,
`CMAKE_FIND_ROOT_PATH_MODE_* = ONLY`, `BUILD_TESTING = OFF` unless QEMU emulator wired).
Cross-Language CMake 4.5 Integration
Integrating non-C++ targets into CMake 4.5?
├── ISO C23 (/c-pro) --------------> `CMAKE_C_STANDARD 23`, probe `<stdbit.h>`, dual `extern "C"` headers.
├── Rust 1.99.1+ (/rust-pro) ------> Cargo + Corrosion + Crubit `cpp_api_from_rust` (or `cxx`/`extern "C"`).
├── SPARK Ada 2022 (/ada-spark-pro)> `cmake/SparkTargets.cmake` (`alr -n gnatprove` + `install(... BUILD_DEPENDS)`).
└── Python 3.14.7 (/python-pro) ---> `find_package(Python 3.14 ...)` + `nanobind_add_module` (no `LIBRARY DESTINATION`).
Packaging Metadata & Module Scanning
Publishing libraries or enabling C++23 modules?
├── Packaging reusable C/C++ libraries?
│ └── Always emit CPS (`install(PACKAGE_INFO ... LOWER_CASE_FILE)`) + SPDX 3.0.1 SBOM (`install(SBOM ...)`),
│ wrapping conditional link dependencies in `$<LINK_ONLY:...>`.
└── Should C++20/23 module scanning be enabled?
├── Normal multi-tool project (`ccache`, `clang-tidy`, `misc-include-cleaner`) -> Keep `ENABLE_CXX_MODULES=OFF` (`set(CMAKE_CXX_SCAN_FOR_MODULES OFF)`).
└── Standalone Ninja (`>= 1.11`) `import std` target -> Opt in via `-DENABLE_CXX_MODULES=ON` (GA in CMake 4.5, no experimental UUIDs).
Examples & References Index
- Turnkey Examples (
examples/):- examples/pixi.toml: Hermetic Linux (
linux-64,linux-aarch64) and macOS (osx-arm64)conda-forgeworkspace (cmake >=4.5.0,clangxx >=23.1.5,libabseil,gtest,benchmark,gersemi,pre-commit). - examples/CMakePresets.json: Schema v13 presets (
base,pixi-base,ci-debug,dev-debug,dev-release,ci-tsan,sysroot-release,cross-aarch64,cross-riscv64, plus matching build/test/workflow presets). - examples/CMakeLists.txt: Validated CMake 4.5 root template with
CMD_NON_TARGET_DIRECTIVE,ENABLE_CXX_MODULES,FILE_SET HEADERS/SOURCES,ALIASinstall/export parity, CPSPACKAGE_INFO, and# gersemi: off/onSPDX 3.0.1SBOM. - examples/.gersemirc: Deterministic
gersemi(0.19.2+/0.29.2) formatting configuration. - examples/.pre-commit-config.yaml: SHA-frozen
pre-commithygiene plusgersemi --check,clang-format, andclang-tidy -p build/ci-debug.
- examples/pixi.toml: Hermetic Linux (
- Deep-Dive Reference Manuals (
references/):- references/canonical_templates.md: Complete
cmake/*.cmakemodules (ProjectOptions,CompilerWarnings,Sanitizers,Architecturewith RVA23 RVV 1.0 probes,Dependencies,Testingwithdiscover_tests(), andCoverage). - references/presets_toolchains_and_pixi.md: Schema v13 rules,
pixi 0.84.2+$env{CONDA_PREFIX}wiring, air-gapped sysroot builds, AArch64/RISC-V RVA23 toolchains,cmake_instrumentation(), andcmake_language(PRINT_*). - references/packaging_cps_sbom_and_interop.md:
FILE_SETproperties, header verification, GA CPS (PACKAGE_INFO), GA SPDX 3.0.1SBOM, CMake 4.5ALIASparity, and C23 / Rust / SPARK Ada /nanobindinterop recipes.
- references/canonical_templates.md: Complete
Behavioral Guardrails
- Out-of-Source & Preset-First: Reject in-source builds immediately and drive configure/build/test through
CMakePresets.json(cmake --workflow --preset ci-debugorpixi run ci). - Fail Fast: Use
message(FATAL_ERROR "...")when required compilers, linkers, sysroots, or ISA probes fail. - No Hook Bypasses: Never pass
--no-verifyor bypass pre-commit hooks; satisfygersemi --check,clang-format, andclang-tidybefore committing (/github-flow-lifecycle).