Skip to content

ADR-001: Use cmake_layout only for C++ Library projects

Field Value
Date 2026-03-16
Status Accepted
Deciders —
Supersedes —
Superseded by —

Context and Problem Statement

C++ build tools (CMake + Conan) support two common layout strategies for build artefacts. The chosen strategy affects local developer workflow, CI pipeline structure, and the ability to package and distribute libraries.

A decision is needed because the generator produces multiple project types (library, service, CLI tool) that have different packaging and distribution requirements.

Decision Drivers

  • Libraries must be packaged as Conan packages and need both Debug and Release builds available simultaneously in the same workspace.
  • Services and CLI tools produce a single containerised executable; only one active build configuration is needed at a time.
  • Simpler build structures reduce cognitive overhead for service/tool developers.

Considered Options

  1. cmake_layout for all C++ project types
  2. Flat build/ for all C++ project types
  3. cmake_layout for libraries only; flat build/ for services and CLI tools

Decision Outcome

Chosen option: Option 3, because cmake_layout is a hard requirement for library packaging (make package relies on separate build/Debug/ and build/Release/ trees), while it adds unnecessary complexity for service and tool projects that never require parallel build configurations.

Positive Consequences

  • Library projects: clean separation of Debug and Release artefacts; make package works without requiring a prior make clean.
  • Service and tool projects: simpler flat build/ structure; CI always operates on a clean workspace, so the stale-object risk does not materialise in practice.

Negative Consequences / Risks

  • Service and tool projects: switching between make build (Debug) and make release-build (Release) locally without running make clean first may cause stale object files (compiled with different flags) to be linked into the new binary.
  • Mitigation: documented in specs/guidelines/cpp_coding.md under the CMake section.

Pros and Cons of the Options

Option 1 — cmake_layout for all project types

  • Pro: Uniform build structure across all project types.
  • Pro: No stale-object risk when switching build types locally.
  • Con: Unnecessary complexity for services and tools that never need parallel configs.
  • Con: Requires adapting service/tool CMakeLists.txt and Conan install commands.

Option 2 — Flat build/ for all project types

  • Pro: Simple, uniform build structure.
  • Con: make package for libraries breaks — Conan packaging requires separate Debug/Release trees when both are needed simultaneously.

Option 3 — cmake_layout for libraries only (chosen)

  • Pro: Each project type uses the minimal layout it actually requires.
  • Pro: Library packaging works without workarounds.
  • Con: Inconsistent build structure between project types — mitigated by documentation.
  • internal/templating/cpp/makefile_partials.go — generator code that selects build_cpp_library.tmpl vs build_cpp.tmpl based on project type
  • internal/templating/cpp/files/Makefile.d/build_cpp_library.tmpl — uses cmake_layout
  • internal/templating/cpp/files/Makefile.d/build_cpp.tmpl — uses flat build/
  • specs/guidelines/cpp_coding.md — CMake section, build directory layout bullet