Skip to main content

CMake and Conan policy

Workflow-level policy for how superbuild workspaces describe builds and manage dependencies. This document is conceptual — product repos implement specifics in their root CMakeLists.txt, conanfile.py, and presets.

CMake is the authoritative build description​

  • Single language of build truth — targets, dependencies between targets, install rules, and toolchain settings are expressed in CMake
  • Superbuild root coordinates subprojects (under src/, libs/, or fetched dependencies) via add_subdirectory, ExternalProject, or equivalent established pattern in that workspace
  • No parallel build systems for core artifacts — do not introduce Visual Studio .vcxproj, ad-hoc Makefiles, or bespoke scripts that replace CMake for standard configure/build/test
  • Generators and platforms are selected through CMake presets and toolchain files, not one-off developer machine settings

Agents should modify or extend CMakeLists when changing how software is built, not bypass CMake.

Conan is the dependency and bootstrap layer​

Conan provides:

  • Dependency resolution for third-party libraries where packages exist
  • Toolchain and profile generation (compiler, C++ standard, flags)
  • Environment setup for consistent developer and CI machines

Conan does not replace the superbuild's CMake structure. It feeds CMake (e.g. via CMakeToolchain, CMakeDeps) so that find_package and target linking work uniformly.

Division of responsibility​

ConcernOwner
What targets exist and how they linkCMake
Where third-party binaries come fromConan (preferred) or libs/ (exception)
Cross-platform configure commandsCMake Presets + documented Conan install step
One-off developer PATH hacksDiscouraged — encode in Conan/CMake

CMake Presets​

Presets are the standard interface for configure, build, and test across Windows, Linux, and macOS.

Policy expectations:

  • Checked-in CMakePresets.json (and CMakeUserPresets.json locally if needed)
  • Named presets reflect intent (dev-debug, ci-release, platform variants) — exact names are consumer-defined but must be documented
  • CI and local developers use the same preset names where possible
  • Out-of-tree builds only — build directory separate from source (e.g. build/)

Agents should prefer cmake --preset <name> over manual cache flags unless fixing preset definitions themselves.

Cross-platform consistency​

Goals:

  • Same high-level flow on all platforms: Conan install → CMake preset configure → build
  • Platform differences isolated to profiles, toolchain files, generators, and documented options
  • No silent Linux-only or Windows-only steps without mention in consumer AGENTS.md

When proposing build changes, verify impact on all targeted platforms or explicitly document platform scope.

Windows generator policy​

Linux and macOS use Ninja (single-config). Windows supports two first-class CMake generators:

GeneratorConfigPrimary use on Windows
NinjaSingle-configFast CLI builds; parity with Linux/macOS command shape
Visual StudioMulti-configInteractive debugging in VS; installer / release builds via MSBuild

Both are driven by the same CMake target graph and checked-in presets. MSBuild runs CMake-generated project files — not hand-maintained .vcxproj.

Consumers must document in root AGENTS.md:

  • Preset names for each generator (separate binaryDir per preset)
  • Which CI job gates merge vs installer/release (VS generator Release typically gates installers)
  • Standard --config usage for VS generator builds

Full detail: conan-cmake-rollout.md.

Relationship to libs/​

When a dependency cannot use Conan (yet):

  • Build it from libs/ with CMake integrated into the superbuild
  • Document why Conan is not used
  • Plan Conan migration if applicable

Do not duplicate a Conan-available library in libs/ without documented exception.

What agents should not do​

  • Add non-CMake build entry points for core libraries
  • Hardcode absolute paths to dependencies
  • Skip Conan when the workspace standard is Conan + CMake toolchain
  • Change generator or compiler without updating presets/profiles and docs

Consumer implementation​

Each superbuild repo implements this policy in its own files. Shared workflow docs here do not contain product target names or version pins. For layout, see repository-layout.md. For multi-repo coordination, see superbuild-philosophy.md.