Skip to content

docs: document dual-build strategy for C++20 modules #644

Description

@kcenon

What

Document the dual-build strategy around the optional C++20 modules support (requires CMake 3.28+), so downstream consumers know when and how to enable it.

  • Current: Module support exists (CMakeLists.txt:176-250) but selection criteria are not documented
  • Expected: A short guide covering prerequisites, toolchain matrix, and fallback behaviour
  • Scope: docs/guides/CXX20_MODULES.md (new), linked from README.md

Why

  • C++20 modules are still experimental in some compilers; silently enabling them can confuse consumers
  • Dual-build expectations (header-only fallback vs. modules) should be explicit

How

Technical Approach

  1. Create docs/guides/CXX20_MODULES.md with:
    • Compiler/CMake matrix
    • -DCOMMON_BUILD_MODULES=ON usage
    • Known limitations (e.g. import under sanitizers)
  2. Link from README.md under "Advanced usage"

Acceptance Criteria

  • Guide page exists and is referenced from README
  • Matrix covers GCC 14+, Clang 17+, MSVC 2022+, Apple Clang 15+
  • Fallback behaviour explained

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions